🎛️ Handlers#

Handlers are where your bot reacts to incoming WhatsApp updates.

In pywa, every incoming webhook update is converted into a typed update object, such as Message, CallbackButton, or MessageStatus. You register callback functions for the update types you care about, and pywa calls the right function when WhatsApp sends an update.

The usual workflow is:

Create a WhatsApp client.
Register handlers with decorators or Handler objects.
Give WhatsApp a public callback URL.
Run the app with pywa dev while developing, or pywa run when deploying.

This guide starts with the day-to-day part: writing handlers.

Your First Handler#

A handler callback receives the WhatsApp client and the update object.

main.py#

from pywa import WhatsApp, filters, types

wa = WhatsApp(
    phone_id="1234567890",
    token="EAA...",
    verify_token="my-verify-token",
)

@wa.on_message(filters.text)
def echo(client: WhatsApp, msg: types.Message):
    msg.reply(f"You said: {msg.text}")

Then run the file with the pywa CLI:

Terminal#

pywa dev

pywa dev starts the webhook server and reloads it when your code changes.

Registering Handlers#

You can register handlers in two main ways:

Decorators, which are the simplest option for most projects.
Handler objects, which are useful when handlers are assembled dynamically or imported from many modules.

Using decorators#

Use the on_... decorators on your WhatsApp client.

main.py#

from pywa import WhatsApp, types

wa = WhatsApp(...)

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

@wa.on_callback_button
def handle_callback_button(client: WhatsApp, clb: types.CallbackButton):
    clb.react("❤️")

You can pass filters to many handlers:

main.py#

from pywa import WhatsApp, filters, types

wa = WhatsApp(...)

@wa.on_message(filters.command("start"))
def start(client: WhatsApp, msg: types.Message):
    msg.reply("Welcome!")

See the filters guide for built-in filters and custom filters.

Loading handlers from modules#

If your handlers live in another module and do not have direct access to the client instance, register them on the WhatsApp class.

handlers.py#

from pywa import WhatsApp, filters, types

@WhatsApp.on_message(filters.text)
def handle_text(client: WhatsApp, msg: types.Message):
    msg.reply(msg.text)

Then load that module when creating the client:

main.py#

from pywa import WhatsApp
import handlers

wa = WhatsApp(
    ...,
    handlers_modules=[handlers],
)

You can also load modules later:

wa.load_handlers_modules(handlers)

Using `Handler` objects#

For larger projects, or when handlers are created dynamically, wrap callbacks in Handler objects and register them with add_handlers().

handlers.py#

from pywa import types

def handle_message(client, msg: types.Message):
    print(msg.text)

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

main.py#

from pywa import WhatsApp, filters, handlers
import handlers as my_handlers

wa = WhatsApp(...)

wa.add_handlers(
    handlers.MessageHandler(my_handlers.handle_message, filters.text),
    handlers.CallbackButtonHandler(my_handlers.handle_callback_button),
)

Available Handlers#

Decorator	Handler	Update type
`on_message()`	`MessageHandler`	`Message`
`on_callback_button()`	`CallbackButtonHandler`	`CallbackButton`
`on_callback_selection()`	`CallbackSelectionHandler`	`CallbackSelection`
`on_flow_completion()`	`FlowCompletionHandler`	`FlowCompletion`
`on_flow_request()`	`FlowRequestHandler`	`FlowRequest`
`on_message_status()`	`MessageStatusHandler`	`MessageStatus`
`on_template_status_update()`	`TemplateStatusUpdateHandler`	`TemplateStatusUpdate`
`on_template_category_update()`	`TemplateCategoryUpdateHandler`	`TemplateCategoryUpdate`
`on_template_quality_update()`	`TemplateQualityUpdateHandler`	`TemplateQualityUpdate`
`on_template_components_update()`	`TemplateComponentsUpdateHandler`	`TemplateComponentsUpdate`
`on_phone_number_change()`	`PhoneNumberChangeHandler`	`PhoneNumberChange`
`on_identity_change()`	`IdentityChangeHandler`	`IdentityChange`
`on_call_connect()`	`CallConnectHandler`	`CallConnect`
`on_call_terminate()`	`CallTerminateHandler`	`CallTerminate`
`on_call_status()`	`CallStatusHandler`	`CallStatus`
`on_call_permission_update()`	`CallPermissionUpdateHandler`	`CallPermissionUpdate`
`on_user_marketing_preferences()`	`UserMarketingPreferencesHandler`	`UserMarketingPreferences`
`on_edited_message()`	`EditedMessageHandler`	`EditedMessage`
`on_deleted_message()`	`DeletedMessageHandler`	`DeletedMessage`
`on_outgoing_message()`	`OutgoingMessageHandler`	`OutgoingMessage`
`on_outgoing_edited_message()`	`OutgoingEditedMessageHandler`	`OutgoingEditedMessage`
`on_outgoing_deleted_message()`	`OutgoingDeletedMessageHandler`	`OutgoingDeletedMessage`
`on_account_update()`	`AccountUpdateHandler`	`AccountUpdate`
`on_raw_update()`	`RawUpdateHandler`	`RawUpdate`

Handlers or Listeners?#

Handlers are best for app entry points: commands, buttons, statuses, template events, and other updates that start a unit of work.

When you need to continue a conversation and wait for the user’s next message, use a listener.

main.py#

from pywa import WhatsApp, filters, types

wa = WhatsApp(...)

@wa.on_message(filters.command("start"))
def start(client: WhatsApp, msg: types.Message):
    age = msg.reply("Hello! What's your age?").wait_for_reply(filters.text).text
    msg.reply(f"Nice, you are {age}.")

Making WhatsApp Reach Your App#

WhatsApp sends updates to a public HTTPS callback URL. During local development, that usually means opening a tunnel from the internet to your local server.

Pywa provides start_ngrok_tunnel() for this:

main.py#

from pywa import WhatsApp, filters, types, utils

callback_url = utils.start_ngrok_tunnel(
    port=8000,
    auth_token="your-ngrok-auth-token",
    domain="subdomain.ngrok-free.app",
)

wa = WhatsApp(
    phone_id="1234567890",
    token="EAA...",
    app_id="1234567890",
    app_secret="xxxx",
    callback_url=callback_url,
    verify_token="my-verify-token",
)

@wa.on_message(filters.text)
def echo(client: WhatsApp, msg: types.Message):
    msg.reply(msg.text)

Run the app:

Terminal#

pywa dev

Install the ngrok package before using the helper:

Terminal#

pip install ngrok

Tip

Use a static ngrok domain while developing. It keeps the callback URL stable across restarts. After the first successful registration, you can usually comment out callback_url to avoid registering the same webhook every time you restart the app.

You can also use any other HTTPS tunnel or deployed URL, such as:

Cloudflare Tunnel
localtunnel
Your production server URL

Registering the Callback URL#

WhatsApp must know where to send webhook requests. You can register the callback URL automatically with pywa or manually in the Meta app dashboard.

Automatic registration#

Automatic registration is the easiest option for development and for most apps.

Pass callback_url and verify_token to WhatsApp. For the default app-level registration, also pass app_id and app_secret.

main.py#

from pywa import WhatsApp, utils

wa = WhatsApp(
    phone_id="1234567890",
    token="EAA...",
    app_id="1234567890",
    app_secret="xxxx",
    callback_url=utils.start_ngrok_tunnel(domain="subdomain.ngrok-free.app"),
    verify_token="my-verify-token",
)

When the server starts, pywa registers the URL and handles WhatsApp’s verification challenge for you.

By default, pywa registers the URL in the app scope. You can use another scope with callback_url_scope:

main.py#

from pywa import WhatsApp, utils

wa = WhatsApp(
    phone_id="1234567890",
    token="EAA...",
    callback_url="https://example.com",
    verify_token="my-verify-token",
    callback_url_scope=utils.CallbackURLScope.PHONE,
)

The required IDs depend on the scope:

Scope	Registers	Required values
`CallbackURLScope.APP`	The app webhook subscription	`app_id` and `app_secret`
`CallbackURLScope.WABA`	A WABA alternate callback URL	`waba_id`
`CallbackURLScope.PHONE`	A phone-number alternate callback URL	`phone_id`

Manual registration#

If you prefer to register the URL yourself:

Create the client with the same verify_token you will enter in Meta.
Start the app so pywa can answer the verification challenge.
Open App Dashboard > WhatsApp > Configuration.
Enter your public callback URL and verify token.

main.py#

from pywa import WhatsApp

wa = WhatsApp(
    token="EAA...",
    verify_token="my-verify-token",
)

Subscribing to Webhook Fields#

When registering manually, make sure your app is subscribed to the webhook fields you need.

Go to App Dashboard > WhatsApp > Configuration and scroll to Webhook Fields.

Pywa can process these fields:

messages - user messages, callbacks, and message statuses
calls - call connect, terminate, and status updates
message_template_status_update - template approval or rejection updates
message_template_quality_update - template quality score updates
message_template_components_update - template component updates
template_category_update - template category changes
user_preferences - user marketing preferences

If you register the callback URL automatically, pywa subscribes to the webhook fields it supports. You can customize the fields with webhook_fields.

Use on_raw_update() if you want to receive unsupported webhook events yourself.

Running pywa#

After handlers and callback settings are in place, run the server.

Using the CLI (recommended)#

Install the server extras:

Terminal#

pip install "pywa[server]"

Use pywa dev while developing:

Terminal#

pywa dev

Use pywa run when you want to run without auto-reload:

Terminal#

pywa run main.py

Both commands run pywa’s built-in Starlette application with Uvicorn and register the webhook endpoint automatically.

You can also point the CLI to a specific client object:

Terminal#

pywa dev main:wa2
pywa run --app wa2

Common options include:

Terminal#

pywa dev --reload-dir src
pywa run --workers 4

Using `WhatsApp.run()`#

For quick scripts and prototypes, you can start the built-in server directly from Python:

main.py#

from pywa import WhatsApp

wa = WhatsApp(...)

# Register handlers here

wa.run()

This uses the same Starlette-based webhook app, but it is blocking and does not include the development features of pywa dev. Prefer pywa dev and pywa run for normal use.

Using FastAPI or Flask#

If your project already has a FastAPI or Flask app, pass it to server. Pywa registers the webhook routes on that app, and you run the app yourself.

FastAPI:

main.py#

from fastapi import FastAPI
from pywa import WhatsApp, filters, types

app = FastAPI()

wa = WhatsApp(
    ...,
    server=app,
    webhook_endpoint="/whatsapp",
)

@wa.on_message(filters.text)
def echo(client: WhatsApp, msg: types.Message):
    msg.reply(msg.text)

Run FastAPI normally:

Terminal#

fastapi dev main.py

Flask works the same way:

app.py#

from flask import Flask
from pywa import WhatsApp, filters, types

app = Flask(__name__)

wa = WhatsApp(
    ...,
    server=app,
    webhook_endpoint="/whatsapp",
)

@wa.on_message(filters.text)
def echo(client: WhatsApp, msg: types.Message):
    msg.reply(msg.text)

if __name__ == "__main__":
    app.run(port=8000)

If you pass a custom FastAPI or Flask server, pywa does not run it for you.

Handler Order and Flow#

By default, pywa stops after the first handler that matches an update.

main.py#

from pywa import WhatsApp, types

wa = WhatsApp(...)

@wa.on_message
def first(client: WhatsApp, msg: types.Message):
    print("first")
    # No later message handlers run for this update.

@wa.on_message
def second(client: WhatsApp, msg: types.Message):
    print("second")

Handlers run in registration order unless you set priority. Higher priority runs earlier.

main.py#

from pywa import WhatsApp, types

wa = WhatsApp(...)

@wa.on_message(priority=1)
def first(client: WhatsApp, msg: types.Message):
    print("First:", msg)

@wa.on_message(priority=2)
def second(client: WhatsApp, msg: types.Message):
    print("Second:", msg)

To keep checking later handlers by default, enable continue_handling:

main.py#

wa = WhatsApp(..., continue_handling=True)

You can also control the flow from inside a handler with stop_handling() and continue_handling().

main.py#

from pywa import WhatsApp, filters, types

wa = WhatsApp(...)

@wa.on_message(filters.text)
def handle_message(client: WhatsApp, msg: types.Message):
    if msg.text == "stop":
        msg.stop_handling()
    else:
        msg.continue_handling()

Validating Updates#

WhatsApp recommends validating incoming webhook requests with the X-Hub-Signature-256 header.

Pywa validates updates by default when app_secret is provided:

main.py#

from pywa import WhatsApp

wa = WhatsApp(
    app_secret="xxxx",
    validate_updates=True,
    ...
)

If no app_secret is provided, pywa disables validation and emits a warning. If validation is enabled and the signature is missing or invalid, pywa rejects the request before calling your handlers. You can disable validation explicitly with validate_updates=False.

Using Other Web Frameworks#

FastAPI and Flask are registered automatically. For any other web framework, create the HTTP routes yourself and call pywa’s webhook helper methods.

Your framework needs two routes on the same endpoint:

GET for the verification challenge.
POST for incoming webhook updates.

Verification route:

main.py#

challenge, status = wa.webhook_challenge_handler(
    vt=request.GET[utils.HUB_VT],
    ch=request.GET[utils.HUB_CH],
)

return challenge, status

Update route:

main.py#

body = request.body

validation_error = wa.webhook_update_validator(
    update=body,
    hmac_header=request.headers.get(utils.HUB_SIG),
)

if validation_error:
    return validation_error

response, status = wa.webhook_update_handler(update=body)
return response, status

With manual framework integration, you are responsible for returning the right response format for your framework and for running the server.

What pywa runs#

When you use pywa dev, pywa run, or run(), pywa creates a small Starlette app and runs it with Uvicorn.

That app registers:

A GET route on webhook_endpoint for WhatsApp’s verification challenge.
A POST route on webhook_endpoint for incoming webhook updates.

For supported custom servers, pywa registers equivalent routes on the FastAPI or Flask app you pass to server. For other frameworks, use the manual helper methods above.

🎛️ Handlers

Contents

🎛️ Handlers#

Your First Handler#

Registering Handlers#

Using decorators#

Loading handlers from modules#

Using Handler objects#

Available Handlers#

Handlers or Listeners?#

Making WhatsApp Reach Your App#

Registering the Callback URL#

Automatic registration#

Manual registration#

Subscribing to Webhook Fields#

Running pywa#

Using the CLI (recommended)#

Using WhatsApp.run()#

Using FastAPI or Flask#

Handler Order and Flow#

Validating Updates#

Using Other Web Frameworks#

What pywa runs#

Using `Handler` objects#

Using `WhatsApp.run()`#