PyWa • Python wrapper for the WhatsApp Cloud API#

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#

Get Started • WhatsApp Client • Handlers • Filters • Updates • Flows • Examples

⚡ 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://xyz.ngrok-free.app",
    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) from the command line:

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

💫 Async Usage

PyWa has beta async support. At the moment it seems that there are problems running with flask or with fastapi when running uvicorn from the code (and not from the command line). To use the async version, just 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#

Python 3.10 or higher - https://www.python.org

📖 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.

PyWa • Python wrapper for the WhatsApp Cloud API

Contents