pywa Documentation

Pywa is built around several key abstractions:

• WhatsApp: The core client used to send messages, manage business profiles, and register handlers.
• Handlers: Callbacks that trigger when specific updates (like messages or button clicks) occur.
• Listeners: A mechanism to wait for a user's next specific reply inline, useful for step-by-step conversational flows.
• Filters: Composable conditions used to decide if a handler should process an update. They support Python-like logic using & (AND), | (OR), and ~ (NOT).
• Updates: The data objects representing incoming events (messages, button clicks, delivery statuses, etc.).
• Flows: A way to build interactive, multi-screen experiences within WhatsApp using Python.
• Errors: The mechanism for surfacing and handling WhatsApp API errors.

Errors in pywa are reported in two distinct ways depending on when the failure is detected:

1. Raised exceptions: These occur immediately when you call a method with invalid parameters (e.g., duplicate callback_data in buttons). You handle these using standard Python try/except blocks.
2. Returned errors (Message Status Updates): These occur asynchronously when the WhatsApp API reports a failure after a message has been sent (e.g., sending media that is too large or attempting to message outside the 24h window). These do not raise exceptions in your main execution flow; instead, they arrive as pywa.types.MessageStatus updates. You must register a handler using @wa.on_message_status(filters.failed) to catch these.

A Flow is a collection of related screens that can exchange data with each other and with your server.

Each Screen is an independent unit with its own data and consists of:

• id: A unique identifier used for navigation.
• title: The title rendered at the top of the screen.
• layout: A Layout object containing the visual elements (children) displayed on the screen.
• data: The data the screen expects to receive to configure its components dynamically.

Screens can be static (content is pre-configured when the flow is created) or dynamic (components like TextInput can have dynamic labels, helper text, or pre-filled values based on the data passed to the screen).

from pywa.types.flows import Screen, Layout

# Example of a static screen definition
START = Screen(
    id="START",
    title="Home",
    layout=Layout(children=[...])
)

The FlowJSON object is the core configuration for a WhatsApp Flow. It requires the following properties:

• version: The version of the Flow JSON schema.
• data_api_version: The version of the data API being used (e.g., utils.Version.FLOW_DATA_API).
• routing_model: A dictionary defining navigation. Keys are screen IDs, and values are lists of screen IDs that can be navigated to from that screen. For example, {"START": ["SIGN_UP"]} means the START screen can navigate to SIGN_UP.
• screens: A list of Screen objects that make up the flow's UI.

When building screens, you often need to pass values from a ScreenData object or a Form child (like a TextInput) into an Action payload.

Instead of manually constructing ScreenDataRef or ComponentRef objects using string names, you can use the .ref property on the component or data object itself. This is more type-safe and can be easily implemented using the Python walrus operator (:=) to assign components to variables during layout definition.

• first_name_initial_value.ref: A shortcut for a ScreenDataRef referencing the first_name_initial_value key.
• first_name.ref: A shortcut for a ComponentRef referencing the first_name component.

Filters are conditions used with handlers (like @wa.on_message) to decide whether an incoming update should be processed or ignored. If a filter returns True, the handler's callback is executed; if False, the update is skipped. You can use built-in filters from the pywa.filters module or create custom ones.

from pywa import WhatsApp, types, filters

wa = WhatsApp(...)

# The handler only runs if the message starts with 'Hello' or 'Hi' (case-insensitive)
@wa.on_message(filters.startswith("Hello", "Hi", ignore_case=True))
def handle_hello(wa: WhatsApp, msg: types.Message):
    msg.reply("Hello!")

# The handler only runs if the callback button matches 'click'
@wa.on_callback_button(filters.matches("click"))
def handle_click(wa: WhatsApp, clb: types.CallbackButton):
    clb.reply("You clicked me!")

Instead of just reacting to single events, you can use wait_for_reply to chain conversations. This allows you to pause execution and wait for a specific type of user input (like text) before proceeding.

@wa.on_message(filters.command("start"))
def start(_: WhatsApp, msg: types.Message):
    # Waits for the next text reply from the user
    name = msg.reply("What's your name?").wait_for_reply(filters=filters.text).text
    msg.reply(f"Nice to meet you, {name}!")