Ctrl+K

Flow Types

Flow Types#

class pywa.types.flows.FlowRequest#

Represents a flow data exchange request. This request is sent to the flow endpoint when a user interacts with a flow and perform an Action that trigger a data exchange.

Variables:

  • version (str) – The version of the data exchange.

  • flow_token (str | None) – The flow token used to create the flow. None if action is FlowRequestActionType.PING.

  • action (pywa.types.flows.FlowRequestActionType) – The action that triggered the request.

  • screen (str | None) – The screen that triggered the request. None if action is FlowRequestActionType.PING.

  • data (dict[str, Any] | None) – The data sent from the screen. None if action is FlowRequestActionType.PING and optional if action is FlowRequestActionType.BACK or FlowRequestActionType.INIT.

property has_error: bool#

Check if the request has an error. When True, if flow endpoint register with acknowledge_errors=True, pywa will acknowledge the error and ignore the response from the callback. The callback still be called.

property is_health_check: bool#

Check if the request is a health check. When True, if flow endpoint register with handle_health_check=True, pywa will not call the callback and will return a health check response.

class pywa.types.flows.FlowRequestActionType#

The type the action that triggered the request.

Variables:

  • INIT – if the request is triggered when opening the Flow

  • BACK – if the request is triggered when pressing “back” (The screen has refresh_on_back set to True)

  • DATA_EXCHANGE – if the request is triggered when submitting the screen

  • PING – if the request is triggered by a health check (ignore this requests by leaving handle_health_check to True)

class pywa.types.flows.FlowResponse#

Represents a flow data exchange response. This response is sent to the flow endpoint to determine the next screen to display or to close the flow. You should return this response from your flow endpoint callback.

Read more at developers.facebook.com.

Variables:

  • version (str) – The version of the data exchange.

  • screen (str | None) – The screen to display (if the flow is not closed).

  • data (dict[str, Any]) – The data to send to the screen or to add to flow completion message (received to the webhook).

  • error_message (str | None) – This will redirect the user to screen and will trigger a snackbar error with the error_message present (if the flow is not closed).

  • flow_token (str | None) – The flow token to close the flow (if the flow is closed).

  • close_flow (bool) – Whether to close the flow or just navigate to the screen.

class pywa.types.flows.FlowCategory#

The category of the flow

Variables:

  • SIGN_UP – Sign up

  • SIGN_IN – Sign in

  • APPOINTMENT_BOOKING – Appointment booking

  • LEAD_GENERATION – Lead generation

  • CONTACT_US – Contact us

  • CUSTOMER_SUPPORT – Customer support

  • SURVEY – Survey

  • OTHER – Other

class pywa.types.flows.FlowDetails#

Represents the details of a flow.

Variables:

  • id (str) – The ID of the flow.

  • name (str) – The name of the flow.

  • status (FlowStatus) – The status of the flow.

  • json_version (str | None) – The version of the flow JSON.

  • data_api_version (str | None) – The version to use during communication with the WhatsApp Flows Data Endpoint.

  • categories (tuple[FlowCategory, ...]) – The categories of the flow.

  • validation_errors (tuple[FlowValidationError, ...] | None) – The validation errors of the flow.

  • endpoint_uri (str | None) – The endpoint URI of the flow.

  • preview (FlowPreview | None) – The preview of the flow.

  • whatsapp_business_account (WhatsAppBusinessAccount | None) – The WhatsApp Business Account that owns the flow.

  • application (FacebookApplication | None) – The application that owns the flow.

publish() → bool#
Update the status of this flow to FlowStatus.PUBLISHED.

  • This action is not reversible.

  • The Flow and its assets become immutable once published.

  • To update the Flow after that, you must create a new Flow. You specify the existing Flow ID as the clone_flow_id parameter while creating to copy the existing flow.

    You can publish your Flow once you have ensured that:

    • All validation errors and publishing checks have been resolved.

    • The Flow meets the design principles of WhatsApp Flows

    • The Flow complies with WhatsApp Terms of Service, the WhatsApp Business Messaging Policy and, if applicable, the WhatsApp Commerce Policy

Returns:

Whether the flow was published.

Raises:

FlowPublishingError – If this flow has validation errors or not all publishing checks have been resolved.

delete() → bool#
When the flow is in FlowStatus.DRAFT status, you can delete it.
Returns:

Whether the flow was deleted.

Raises:

FlowDeletingError – If this flow is already published.

deprecate() → bool#

When the flow is in FlowStatus.PUBLISHED status, you can only deprecate it.

Returns:

Whether the flow was deprecated.

Raises:

FlowDeprecatingError – If this flow is not published or already deprecated.

get_assets() → tuple[pywa.types.flows.FlowAsset, ...]#

Get all assets attached to this flow.

Returns:

The assets of the flow.

update_metadata(name: str | None = None, categories: Iterable[FlowCategory | str] | None = None, endpoint_uri: str | None = None) → bool#
Parameters:

  • flow_id – The flow ID.

  • name – The name of the flow (optional).

  • categories – The new categories of the flow (optional).

  • endpoint_uri – The URL of the FlowJSON Endpoint. Starting from FlowJSON 3.0 this property should be specified only gere. Do not provide this field if you are cloning a FlowJSON with version below 3.0.

Example

>>> from pywa.types.flows import FlowCategory
>>> wa = WhatsApp(business_account_id='1234567890', ...)
>>> my_flows = wa.get_flows()
>>> my_flows[0].update_metadata(
...     name='Feedback',
...     categories=[FlowCategory.SURVEY, FlowCategory.OTHER],
...     endpoint_uri='https://my-api-server/feedback_flow'
... )
Returns:

Whether the flow was updated.

Raises:

ValueError – If neither name, categories or endpoint_uri is provided.

update_json(flow_json: FlowJSON | dict | str | Path | bytes | BinaryIO) → bool#

Update the json of this flow.

Parameters:

flow_json – The new json of the flow. Can be a FlowJSON object, dict, json str, json file path or json bytes.

Returns:

Whether the flow was updated.

Raises:

FlowUpdatingError – If the flow json is invalid or this flow is already published.

class pywa.types.flows.FlowStatus#

The status of the flow

Variables:

  • DRAFT – This is the initial status. The Flow is still under development. The Flow can only be sent with “mode”: “draft” for testing.

  • PUBLISHED – The Flow has been marked as published by the developer so now it can be sent to customers. This Flow cannot be deleted or updated afterwards.

  • DEPRECATED – The developer has marked the Flow as deprecated (since it cannot be deleted after publishing). This prevents sending and opening the Flow, to allow the developer to retire their endpoint. Deprecated Flows cannot be deleted or deprecated.

  • BLOCKED – Monitoring detected that the endpoint is unhealthy and set the status to Blocked. The Flow cannot be sent or opened in this state; the developer needs to fix the endpoint to get it back to Published state (more details in Flows Health and Monitoring).

  • THROTTLED –

    Monitoring detected that the endpoint is unhealthy and set the status to Throttled. Flows with throttled status can be opened, however only 10 messages of the Flow could be sent per hour. The developer needs to fix the endpoint to get it back to the PUBLISHED state (more details in Flows Health and Monitoring on developers.facebook.com).

class pywa.types.flows.FlowPreview#

Represents the preview of a flow.

Variables:

  • url (str) – The URL to the preview.

  • expires_at (datetime.datetime) – The expiration date of the preview.

class pywa.types.flows.FlowValidationError#

Represents a validation error of a flow.

Variables:

  • error (str) – The error code.

  • error_type (str) – The type of the error.

  • message (str) – The error message.

  • line_start (int) – The start line of the error.

  • line_end (int) – The end line of the error.

  • column_start (int) – The start column of the error.

  • column_end (int) – The end column of the error.

class pywa.types.flows.FlowAsset#

Represents an asset in a flow.

Variables:

  • name (str) – The name of the asset (e.g. "flow.json").

  • type (str) – The type of the asset (e.g. "FLOW_JSON").

  • url (str) – The URL to the asset.

class pywa.types.flows.FlowTokenNoLongerValid#

This exception need to be returned or raised from the flow endpoint callback when the Flow token is no longer valid.

  • The layout will be closed and the FlowButton will be disabled for the user. You can send a new message to the user generating a new Flow token. This action may be used to prevent users from initiating the same Flow again.

  • You are able to set an error message to display to the user. e.g. “The order has already been placed”

class pywa.types.flows.FlowRequestSignatureAuthenticationFailed#

This exception need to be returned or raised from the flow endpoint callback when the request signature authentication fails.

  • A generic error will be shown on the client.

pywa.utils.FlowRequestDecryptor#

Type hint for the function that decrypts the request from WhatsApp Flow.

  • All parameters need to be positional.

Parameters:

  • encrypted_flow_data_b64 (str) – encrypted flow data

  • encrypted_aes_key_b64 (str) – encrypted AES key

  • initial_vector_b64 (str) – initial vector

  • private_key (str) – private key

  • password (str) – password for the private key. Optional.

Returns:

tuple[dict, bytes, bytes] - decrypted_data (dict): decrypted data from the request - aes_key (bytes): AES key you should use to encrypt the response - iv (bytes): initial vector you should use to encrypt the response

pywa.utils.FlowResponseEncryptor#

Type hint for the function that encrypts the response to WhatsApp Flow.

  • All parameters need to be positional.

Parameters:

  • response (dict) – response to encrypt

  • aes_key (bytes) – AES key

  • iv (bytes) – initial vector

Returns:

encrypted response to send back to WhatsApp Flow

Return type:

encrypted_response (str)

Contents