PyWa • Python wrapper for the WhatsApp Cloud API

PyWa Logo

PyWa • Python wrapper for the WhatsApp Cloud API#

PyPi Downloads PyPI Version Tests Docs License CodeFactor Telegram

PyWa is a Fast, Simple, Modern and easy-to-use asynchronous Python framework for building WhatsApp bots using the WhatsApp Cloud API.

📄 Quick Documentation Index#

⚡ Features#

  • 🚀 Fast and simple to use. No need to worry about the low-level details.

  • 💬 Send text messages with interactive keyboards, images, videos, documents, audio, locations, contacts, etc.

  • 📩 Receive messages, callbacks, message status updates, etc.

  • ♻️ Create, send and listen to Flows (NEW!)

  • 🔄 Built-in support for webhooks (Flask, FastAPI, etc.)

  • 🔬 Filters for handling incoming updates

  • 📄 Send and create templates

  • ✅ Fully typed, documented and tested

👨‍💻 Usage#

  • Create a WhatsApp client and send a message ..

    See Getting Started for more information.

from pywa import WhatsApp

wa = WhatsApp(
    phone_id="100458559237541",
    token="EAAEZC6hUxkTIB"
)

wa.send_message(
    to="9876543210",
    text="Hello from PyWa!"
)

  • To listen to updates, create a WhatsApp client, pass a web server app (FastAPI in this example) and register callbacks:

See Handlers for more information.

# wa.py
from pywa import WhatsApp, filters
from pywa.types import Message, CallbackButton, Button
from fastapi import FastAPI

fastapi_app = FastAPI()
wa = WhatsApp(
    phone_id="1234567890",
    token="xxxxxxx",
    server=fastapi_app,
    callback_url="https://yourdomain.com/",
    verify_token="xyz123",
    app_id=123456,
    app_secret="yyyyyy"
)

@wa.on_message(filters.matches("Hello", "Hi"))
def hello(client: WhatsApp, msg: Message):
    msg.react("👋")
    msg.reply_text(
        text=f"Hello {msg.from_user.name}!",
        buttons=[
            Button(
                title="Click me!",
                callback_data="id:123"
            )
        ]
    )

@wa.on_callback_button(filters.startswith("id"))
def click_me(client: WhatsApp, clb: CallbackButton):
    clb.reply_text("You clicked me!")

  • To run the server, use uvicorn (pip install "uvicorn[standard]"):

uvicorn wa:fastapi_app  # see uvicorn docs for more options (port, host, reload, etc.)

💫 Async Usage

  • PyWa has async support! To use the async version, replace all the imports from pywa to pywa_async and use async/await:

# wa.py
import fastapi
from pywa_async import WhatsApp, types

fastapi_app = fastapi.FastAPI()
wa = WhatsApp(..., server=fastapi_app)

async def main():
    await wa.send_message(...)

@wa.on_message()
async def hello(_: WhatsApp, msg: types.Message):
    await msg.react("👋")
    await msg.reply(...)

uvicorn wa:fastapi_app

🎛 Installation#

  • Install using pip3:

pip3 install -U pywa

  • Install from source (the bleeding edge):

pip3 install -U git+https://github.com/david-lev/pywa.git

  • If you going to use the webhook features, here is shortcut to install the required dependencies:

pip3 install -U "pywa[fastapi]"
pip3 install -U "pywa[flask]"

  • If you going to use the Flow features and want to use the default FlowRequestDecryptor and the default FlowResponseEncryptor, here is shortcut to install the required dependencies:

pip3 install -U "pywa[cryptography]"

💾 Requirements#

📖 Setup and Usage#

See the Documentation for detailed instructions

☑️ TODO#

  • Add support for async

  • Add support for more web frameworks (Django, aiohttp, etc.)

  • Add support for flows

  • Add support for more types of updates (account_alerts, phone_number_quality_updates, template_category_updates, etc.)

  • Add more examples and guides

Feel free to open an issue if you have any suggestions. or even better - submit a PR!

⚖️ License#

This project is licensed under the MIT License - see the LICENSE file for details

🔱 Contributing#

Contributions are welcome! Please feel free to submit a Pull Request.

📝 Changelog#

NOTE: pywa follows the semver versioning standard.

1.23.0 (2024-07-14) Latest#

  • [client] allowing to manage multiple numbers from the same client (Partner solutions)

  • [flows] adding .respond() shortcut for FlowRequest

  • [flows] allowing body in FlowResponseError subclasses

1.22.0 (2024-06-16)#

  • [handlers] introducing FlowRequestCallbackWrapper to help split flow endpoint logic to multiple handlers

  • [client] adding add_flow_request_handler method to register FlowRequestHandlers

  • [flows] pop flow_token from FlowCompletion.response

  • [docs] update examples

1.21.0 (2024-06-14)#

  • [flows] added new components PhotoPicker, DocumentPicker, If and Switch

  • [flows] added .data_key_of and .form_ref_of to refer from other screens

  • [flows] added description to CheckboxGroup and to RadioButtonsGroup

  • [utils] adding flow_request_media_decryptor function to decrypt medias from flow requests

  • [client] allow updating flow application id with update_flow_metadata

  • [server] remove event loop

  • [docs] update examples

  • [version] bump FLOW_JSON version to 4.0

For full changelog, see here.#

🔗 Contents#

Contents