Keyboard

Keyboard#

class pywa.types.callback.SectionList#

Interactive list messages allow you to present WhatsApp users with a list of options to choose from. When a user taps the button in the message, it displays a modal that lists the options available.

  • Users can then choose one option and their selection will be sent as a reply. When a user selects an option, a CallbackSelection update is triggered.

  • Interactive list messages support up to 10 sections, with up to 10 rows for all sections combined, and can include an optional header and footer.

  • Read more at developers.facebook.com.

Variables:

  • button_title (str) – The title of the button that opens the section list (up to 20 characters).

  • sections (Iterable[pywa.types.callback.Section]) – The sections in the section list (at least 1, no more than 10).

class pywa.types.callback.Section#

Represents a section in a section list.

Variables:

  • title (str) – The title of the section (up to 24 characters).

  • rows (Iterable[pywa.types.callback.SectionRow]) – The rows in the section (at least 1, no more than 10).

class pywa.types.callback.SectionRow#

Represents a choice row in a section rows.

Variables:

  • title (str) – The title of the row (up to 24 characters).

  • callback_data (str | pywa.types.callback.CallbackData) – The payload to send when the user clicks on the row (up to 200 characters, for complex data You can use CallbackData).

  • description (str | None) – The description of the row (optional, up to 72 characters).

class pywa.types.callback.Button#

Interactive reply buttons messages allow you to send up to three predefined replies for users to choose from. Users can respond to a message by selecting one of the predefined buttons, which triggers an CallbackButton update.

Variables:
class pywa.types.callback.URLButton#

Represents a button in the bottom of the message that opens a URL.

Variables:

  • title (str) – The title of the button (up to 20 characters).

  • url (str) – The URL to open when the user clicks on the button.

class pywa.types.callback.FlowButton#

Represents a button that opens a flow.

Variables:

  • title (str) – Text on the CTA button. e.g SignUp, Up to 20 characters, no emojis)

  • flow_id (str | int | None) – Unique ID of the Flow provided by WhatsApp (You can provide either flow_id or flow_name).

  • flow_name (str | None) – Name of the Flow provided by WhatsApp (You can provide either flow_id or flow_name).

  • flow_token (str | None) – Flow token generated by the business to serve as an identifier (Default value: unused)

  • flow_message_version (int | float | str | Literal[pywa.utils.Version.FLOW_MSG]) – Version of the flow message. Default is the latest version.

  • flow_action_type (Literal[pywa.types.flows.FlowActionType.NAVIGATE, pywa.types.flows.FlowActionType.DATA_EXCHANGE] | None) – Type of action to be performed when the user clicks on the button.

  • flow_action_screen (str | None) – The ID of the screen to navigate to. Required when flow_action_type is FlowActionType.NAVIGATE (default).

  • flow_action_payload (dict[str, Any] | None) – The data to provide to the navigation screen, if the screen requires it.

  • mode (Literal[pywa.types.flows.FlowStatus.PUBLISHED, pywa.types.flows.FlowStatus.DRAFT]) – The mode of the flow. FlowStatus.PUBLISHED (default) or FlowStatus.DRAFT (for testing).

class pywa.types.callback.VoiceCallButton#

Represents a button that initiates a voice call on WhatsApp.

Variables:

  • title (str | None) – The text to display on the button (up to 20 characters) default is Call Now.

  • ttl_minutes (int | None) – The time-to-live for the call in minutes (up to 43200 minutes (30 days)), default is 10080 minutes (7 days).

class pywa.types.callback.CallPermissionRequestButton#

Represents a button that requests a call on WhatsApp.

class pywa.types.callback.CallbackData#

Base class for all callback data classes. Subclass this class to create a type-safe callback data class.

If you use dataclasses.dataclass(), which is the recommended way (You get free ordered __init__ and extra features), you should not use kw_only=True. This is because we are limited to 200 characters in the callback data, so we need to use positional arguments. So object like User(id=123, name='John') will be converted to 123:John.

Currently, the following types are supported: str, int, bool, float and enum.Enum that inherits from str (e.g class State(str, Enum)). You can also use all the types as Optional or Union (e.g Optional[int] or Union[int, None]). the Union length must be 2 at most, and one of the types must be None. All fields can be with default values.

The characters and ~ cannot be used when sending callbacks, because they are used as separators. You can change the separators by overriding __callback_data_sep__ (~ for individual objects) and CallbackData.__callback_sep__ ( in the base class level, affects all child classes).

When providing subclassed CallbackData as a factory parameter in callback handlers, a basic matching filter will be added automatically. So no need to create one yourself.

Example

>>> from pywa.types import CallbackData
>>> from dataclasses import dataclass # Use dataclass to get free ordered __init__
>>> @dataclass(frozen=True, slots=True) # Do not use kw_only=True
>>> class UserData(CallbackData): # Subclass CallbackData
...     id: int
...     name: str | None
...     admin: bool = False

>>> from pywa import WhatsApp
>>> from pywa.types import Button
>>> wa = WhatsApp(...)
>>> wa.send_message(
...     to='972987654321',
...     text='Click the button to get the user',
...     buttons=[
...         Button(
...             title='Get user',
...             callback_data=UserData(id=123, name='John', admin=True)
...         )
...     ]
... )

>>> @wa.on_callback_button(factory=UserData) # Use the factory parameter to convert the callback data
... def on_user_data(client: WhatsApp, btn: CallbackButton[UserData]): # For autocomplete
...    if btn.data.admin: print(btn.data.id) # Access the data object as an attribute
class pywa.types.others.ProductsSection#

Represents a section in a section list.

Variables:

  • title (str) – The title of the products section (up to 24 characters).

  • skus (Iterable[str]) – The SKUs of the products in the section (at least 1, no more than 30).

Contents