Skip to content


Repository files navigation

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 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(

    text="Hello from PyWa!"
  • To listen to updates, create a WhatsApp client, pass a web server app (Flask in this example) and register callbacks:

See Handlers for more information.

from pywa import WhatsApp, filters
from pywa.types import Message, CallbackButton, Button
from flask import Flask

flask_app = Flask(__name__)
wa = WhatsApp(

@wa.on_message(filters.matches("Hello", "Hi"))
def hello(client: WhatsApp, msg: Message):
        text=f"Hello {}!",
                title="Click me!",

def click_me(client: WhatsApp, clb: CallbackButton):
    clb.reply_text("You clicked me!")  # Run the flask app to start the server

πŸŽ› Installation

  • Install using pip3:
pip3 install -U pywa
  • Install from source (the bleeding edge):
pip3 install -U git+
  • If you going to use the webhook features, here is shortcut to install the required dependencies:
pip3 install -U "pywa[flask]"
pip3 install -U "pywa[fastapi]"
  • 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, Starlette, etc.)
  • 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.