🎛️ Handlers#

In order to handle the incoming updates from WhatsApp, you need to do two things: - Start a web server that will receive the updates from the webhook - Register a callback functions that will be called when an update is received

Let’s see how to do that.

Starting a web server#

The first thing you need to do is to start a web server that will receive the updates from WhatsApp.

Note

To allow maximum flexibility, pywa does not initialize the server itself. This allows the server to be initialized independently with the desired configurations without any need for pywa to know them. All pywa does is register a route that will handle the incoming updates from WhatsApp. This means that you can use the same server to handle other parts of your software without any limitation from pywa.

You first need to register webhook url to your WhatsApp app.

Note

The webhook url must be a public, secure (HTTPS) url that points to your server (or your local machine if you are testing locally). You can use a service like ngrok , localtunnel or serveo to create a secure tunnel to which WhatsApp can send the updates. These services will give you a public url that points to your machine (where you run the code).

Once you have a public url, You need to start a web server that will receive the updates from WhatsApp.

Here is an example using Flask (pip3 install flask):

from flask import Flask
from pywa import WhatsApp

flask_app = Flask(__name__)

wa = WhatsApp(
    phone_id='1234567890',
    token='xxxxxxxxxxxxxxxxxxxx',
    server=flask_app,
    verify_token='XYZ123
)

if __name__ == '__main__':
    flask_app.run(host='localhost', port=8000)  # or any other way to start a flask server (e.g. gunicorn, waitress, etc.)

And here is an example using FastAPI (pip3 install fastapi[uvicorn]):

import uvicorn
from fastapi import FastAPI
from pywa import WhatsApp

fastapi_app = FastAPI()

wa = WhatsApp(
    phone_id='1234567890',
    token='xxxxxxxxxxxxxxxxxxxx',
    server=fastapi_app,
    verify_token='XYZ123
)

if __name__ == '__main__':
    uvicorn.run(fastapi_app, host='localhost', port=8000)  # or any other way to start a fastapi server

After you start the server, you can go to your WhatsApp app settings and register the webhook url. This can be done in the App Dashboard > WhatsApp > Configuration > Callback URL. You need to enter the webhook url and the verify token that you used when initializing the WhatsApp client. When you click on Save, WhatsApp will send a GET request to the webhook url to verify that it is valid and that the verify token is correct (pywa will automatically handle this request and send the correct response to WhatsApp). If everything is correct, WhatsApp will start sending the updates to the webhook url. In the next section we will see how to handle these updates.

Registering a callback function#

After you start the server and register the webhook url, you need to register a callback function that will be called when an update is received from WhatsApp.

Attention

All callback functions must be registered before starting the server. Otherwise, the updates will not be handled!

There are two ways to register a callback function:

Using decorators#

The easiest way to register a callback function is to use the on_message and the other on_... decorators:

from pywa import WhatsApp
from pywa.types import Message, CallbackButton

wa = WhatsApp(...)  # initialize the WhatsApp client and provide web server (e.g. flask, fastapi, etc.)

@wa.on_message()
def handle_message(client: WhatsApp, message: Message):
    print(message)


@wa.on_callback_button()
def handle_callback_button(client: WhatsApp, clb: CallbackButton):
    print(clb.data)

if __name__ == '__main__':
    # start the server

Using `Handler` objects#

The other way to register a callback function is to use the add_handlers() method and pass the function wrapped in a Handler object. This is useful when your application is large and you want to separate the handlers from the main code, or when you want to dynamically register handlers programmatically.

my_handlers.py#

from pywa import WhatsApp
from pywa.types import Message, CallbackButton

def handle_message(client: WhatsApp, message: Message):
    print(message)

def handle_callback_button(client: WhatsApp, clb: CallbackButton):
    print(clb.data)

main.py#

from pywa import WhatsApp
from pywa.handlers import MessageHandler, CallbackButtonHandler
from my_handlers import handle_message, handle_callback_button

wa = WhatsApp(...)  # initialize the WhatsApp client and provide web server (e.g. flask, fastapi, etc.)

wa.add_handlers(
    MessageHandler(handle_message),
    CallbackButtonHandler(handle_callback_button)
)

if __name__ == '__main__':
    # start the server

Available handlers#

Decorator	Handler	The type of the update
`on_message()`	`MessageHandler`	`Message`
`on_callback_button()`	`CallbackButtonHandler`	`CallbackButton`
`on_callback_selection()`	`CallbackSelectionHandler`	`CallbackSelection`
`on_message_status()`	`MessageStatusHandler`	`MessageStatus`
`on_template_status()`	`TemplateStatusHandler`	`TemplateStatus`
`on_raw_update()`	`RawUpdateHandler`	`dict`

🎛️ Handlers

Contents