Ctrl+K

Flow JSON

Flow JSON#

Here you will find all the components that make up a Flow JSON object.

class pywa.types.flows.FlowJSON#

Represents a WhatsApp Flow JSON.

Variables:

  • screens (Iterable[pywa.types.flows.Screen]) –

    The screens that are part of the flow (Read more at developers.facebook.com).

  • version (str | float | Literal[<Version.FLOW_JSON: '3.0'>]) –

    The Flow JSON version. Default to latest (Read more at developers.facebook.com).

  • data_api_version (str | float | Literal[<Version.FLOW_JSON: '3.0'>] | None) – The version to use during communication with the WhatsApp Flows Data Endpoint. Default to latest. Required if the data channel is set.

  • routing_model (dict[str, Iterable[str]] | None) –

    Defines the rules for the screen by limiting the possible state transition. (Read more at developers.facebook.com).

  • data_channel_uri (str | None) – The endpoint to use to communicate with your server (When using v3.0 or higher, this field need to be set via WhatsApp.update_flow_metadata()).

class pywa.types.flows.Screen#

Represents a screen (page) in a WhatsApp flow.

Variables:

  • id (str) – Unique identifier of the screen which works as a page url. SUCCESS is a reserved keyword and should not be used as a screen id.

  • layout (pywa.types.flows.Layout) –

    Associated screen UI Layout that is shown to the user (Read more at developers.facebook.com).

  • title (str | None) – Screen level attribute that is rendered in the top navigation bar.

  • data (dict[str, dict] | None) – Declaration of dynamic data that fills the components field in the Flow JSON. It uses JSON Schema to define the structure and type of the properties.

  • terminal (bool | None) – Each Flow should have a terminal state where we terminate the experience and have the Flow completed. Multiple screens can be marked as terminal. It’s mandatory to have a Footer component on the terminal screen.

  • refresh_on_back (bool | None) –

    Whether to trigger a data exchange request with the WhatsApp Flows Data Endpoint when using the back button while on this screen (Read more at developers.facebook.com).

class pywa.types.flows.Layout#

Layout is the top level component that holds the other components.

Variables:
class pywa.types.flows.LayoutType#

The type of layout that is used to display the components.

Variables:

SINGLE_COLUMN – A single column layout.

class pywa.types.flows.Form#

To get and submit the data entered from users, Flow JSON uses a straightforward concept from HTML - Forms.

Variables:
class pywa.types.flows.TextHeading#

Represents text that is displayed as a heading.

Variables:

  • text (str | pywa.types.flows.DataKey) – The text of the heading. Limited to 4096 characters. Can be dynamic (e.g DataKey("text")).

  • visible (bool | str | pywa.types.flows.DataKey | None) – Whether the heading is visible or not. Default to True, Can be dynamic (e.g DataKey("is_visible")).

class pywa.types.flows.TextSubheading#

Represents text that is displayed as a subheading.

Variables:

  • text (str | pywa.types.flows.DataKey) – The text of the subheading. Limited to 60 characters. Can be dynamic (e.g DataKey("text")).

  • visible (bool | str | pywa.types.flows.DataKey | None) – Whether the subheading is visible or not. Default to True, Can be dynamic (e.g DataKey("is_visible")).

class pywa.types.flows.TextBody#

Represents text that is displayed as a body.

Variables:
class pywa.types.flows.TextCaption#

Represents text that is displayed as a caption.

Variables:
class pywa.types.flows.FontWeight#

The text weight

Variables:

  • BOLD – Bold text

  • ITALIC – Italic text

  • BOLD_ITALIC – Bold and italic text

  • NORMAL – Normal text

class pywa.types.flows.TextInput#

Represents a text entry component that allows for a single line of text.

Variables:

  • name (str) – The unique name (id) for this component (to be used dynamically or in action payloads).

  • label (str | pywa.types.flows.DataKey) – The label of the text input. Limited to 20 characters. Can be dynamic (e.g DataKey("label")).

  • input_type (pywa.types.flows.InputType | str | pywa.types.flows.DataKey | None) – The input type of the text input (for keyboard layout and validation rules). Can be dynamic (e.g DataKey("input_type")).

  • required (bool | str | pywa.types.flows.DataKey | None) – Whether the text input is required or not. Can be dynamic (e.g DataKey("required")).

  • min_chars (int | str | pywa.types.flows.DataKey | None) – The minimum number of characters allowed in the text input. Can be dynamic (e.g DataKey("min_chars")).

  • max_chars (int | str | pywa.types.flows.DataKey | None) – The maximum number of characters allowed in the text input. Can be dynamic (e.g DataKey("max_chars")).

  • helper_text (str | pywa.types.flows.DataKey | None) – The helper text of the text input. Limited to 80 characters. Can be dynamic (e.g DataKey("helper_text")).

  • enabled (bool | str | pywa.types.flows.DataKey | None) – Whether the text input is enabled or not. Default to True. Can be dynamic (e.g DataKey("enabled")).

  • visible (bool | str | pywa.types.flows.DataKey | None) – Whether the text input is visible or not. Default to True. Can be dynamic (e.g DataKey("is_visible")).

class pywa.types.flows.InputType#

The input type of the text entry component.

  • This is used by the WhatsApp client to determine the keyboard layout and validation rules.

Variables:

  • TEXT – A single line of text

  • NUMBER – A number

  • EMAIL – An email address

  • PASSWORD – A password

  • PASSCODE – A passcode

  • PHONE – A phone number

class pywa.types.flows.TextArea#

Represents a text entry component that allows for multiple lines of text.

Variables:

  • name (str) – The unique name (id) for this component (to be used dynamically or in action payloads).

  • label (str | pywa.types.flows.DataKey) – The label of the text area. Limited to 20 characters. Can be dynamic (e.g DataKey("label")).

  • required (bool | str | pywa.types.flows.DataKey | None) – Whether the text area is required or not. Can be dynamic (e.g DataKey("required")).

  • max_length (int | str | pywa.types.flows.DataKey | None) – The maximum number of characters allowed in the text area. Can be dynamic (e.g DataKey("max_length")).

  • helper_text (str | pywa.types.flows.DataKey | None) – The helper text of the text area. Limited to 80 characters. Can be dynamic (e.g DataKey("helper_text")).

  • enabled (bool | str | pywa.types.flows.DataKey | None) – Whether the text area is enabled or not. Default to True. Can be dynamic (e.g DataKey("enabled")).

  • visible (bool | str | pywa.types.flows.DataKey | None) – Whether the text area is visible or not. Default to True. Can be dynamic (e.g DataKey("is_visible")).

class pywa.types.flows.CheckboxGroup#

CheckboxGroup component allows users to pick multiple selections from a list of options.

Variables:

  • name (str) – The unique name (id) for this component (to be used dynamically or in action payloads).

  • data_source (Iterable[pywa.types.flows.DataSource] | str | pywa.types.flows.DataKey) – The data source of the checkbox group. Can be dynamic (e.g DataKey("data_source")).

  • label (str | pywa.types.flows.DataKey | None) – The label of the checkbox group. Limited to 30 characters. Can be dynamic (e.g DataKey("label")).

  • min_selected_items (int | str | pywa.types.flows.DataKey | None) – The minimum number of items that can be selected. Minimum value is 1. Can be dynamic (e.g DataKey("min_selected_items")).

  • max_selected_items (int | str | pywa.types.flows.DataKey | None) – The maximum number of items that can be selected. Maximum value is 20. Can be dynamic (e.g DataKey("max_selected_items")).

  • required (bool | str | pywa.types.flows.DataKey | None) – Whether the checkbox group is required or not. Can be dynamic (e.g DataKey("required")).

  • visible (bool | str | pywa.types.flows.DataKey | None) – Whether the checkbox group is visible or not. Default to True. Can be dynamic (e.g DataKey("is_visible")).

  • enabled (bool | str | pywa.types.flows.DataKey | None) – Whether the checkbox group is enabled or not. Default to True. Can be dynamic (e.g DataKey("enabled")).

  • on_select_action (pywa.types.flows.Action | None) – The action to perform when an item is selected.

class pywa.types.flows.RadioButtonsGroup#

RadioButtonsGroup component allows users to pick a single selection from a list of options.

Variables:

  • name (str) – The unique name (id) for this component (to be used dynamically or in action payloads).

  • data_source (Iterable[pywa.types.flows.DataSource] | str | pywa.types.flows.DataKey) – The data source of the radio buttons group. Can be dynamic (e.g DataKey("data_source")).

  • label (str | pywa.types.flows.DataKey | None) – The label of the radio buttons group. Limited to 30 characters. Can be dynamic (e.g DataKey("label")).

  • required (bool | str | pywa.types.flows.DataKey | None) – Whether the radio buttons group is required or not. Can be dynamic (e.g DataKey("required")).

  • visible (bool | str | pywa.types.flows.DataKey | None) – Whether the radio buttons group is visible or not. Default to True. Can be dynamic (e.g DataKey("is_visible")).

  • enabled (bool | str | pywa.types.flows.DataKey | None) – Whether the radio buttons group is enabled or not. Default to True. Can be dynamic (e.g DataKey("enabled")).

  • on_select_action (pywa.types.flows.Action | None) – The action to perform when an item is selected.

class pywa.types.flows.Footer#

Footer component allows users to navigate to other screens or submit the flow.

Variables:

  • label (str | pywa.types.flows.DataKey) – The label of the footer. Limited to 35 characters. Can be dynamic (e.g DataKey("label")).

  • on_click_action (pywa.types.flows.Action) – The action to perform when the footer is clicked. Required.

  • left_caption (str | pywa.types.flows.DataKey | None) – Can set left_caption and right_caption or only center_caption, but not all 3 at once. Limited to 15 characters. Can be dynamic (e.g DataKey("left_caption")).

  • center_caption (str | pywa.types.flows.DataKey | None) – Can set center-caption or left-caption and right-caption, but not all 3 at once. Limited to 15 characters. Can be dynamic (e.g DataKey("center_caption")).

  • right_caption (str | pywa.types.flows.DataKey | None) – Can set right-caption and left-caption or only center-caption, but not all 3 at once. Limited to 15 characters. Can be dynamic (e.g DataKey("right_caption")).

  • enabled (bool | str | pywa.types.flows.DataKey | None) – Whether the footer is enabled or not. Default to True. Can be dynamic (e.g DataKey("enabled")).

class pywa.types.flows.OptIn#

OptIn component allows users to check a box to opt in for a specific purpose.

Variables:

  • name (str) – The unique name (id) for this component (to be used dynamically or in action payloads).

  • label (str | pywa.types.flows.DataKey) – The label of the opt in. Limited to 30 characters. Can be dynamic (e.g DataKey("label")).

  • required (bool | str | pywa.types.flows.DataKey | None) – Whether the opt in is required or not. Can be dynamic (e.g DataKey("required")).

  • visible (bool | str | pywa.types.flows.DataKey | None) – Whether the opt in is visible or not. Default to True. Can be dynamic (e.g DataKey("is_visible")).

  • on_click_action (pywa.types.flows.Action | None) – The action to perform when the opt in is clicked.

class pywa.types.flows.Dropdown#

Dropdown component allows users to pick a single selection from a list of options.

Variables:

  • name (str) – The unique name (id) for this component (to be used dynamically or in action payloads).

  • label (str | pywa.types.flows.DataKey) – The label of the dropdown. Limited to 30 characters. Can be dynamic (e.g DataKey("label")).

  • data_source (Iterable[pywa.types.flows.DataSource] | str | pywa.types.flows.DataKey) – The data source of the dropdown. minimum 1 and maximum 200 items. Can be dynamic (e.g DataKey("data_source")).

  • enabled (bool | str | pywa.types.flows.DataKey | None) – Whether the dropdown is enabled or not. Default to True. Can be dynamic (e.g DataKey("enabled")).

  • required (bool | str | pywa.types.flows.DataKey | None) – Whether the dropdown is required or not. Can be dynamic (e.g DataKey("required")).

  • visible (bool | str | pywa.types.flows.DataKey | None) – Whether the dropdown is visible or not. Default to True. Can be dynamic (e.g DataKey("is_visible")).

  • on_select_action (pywa.types.flows.Action | None) – The action to perform when an item is selected.

EmbeddedLink component allows users to click on a link that opens a web page.

  • This component must be inside a Form.

  • Max Number of Embedded Links Per Screen is 2.

  • Empty or Blank value is not accepted for the text field.

  • Read more at developers.facebook.com.

Variables:

  • text (str | pywa.types.flows.DataKey) – The text of the embedded link. Limited to 35 characters. Can be dynamic (e.g DataKey("text")).

  • on_click_action (pywa.types.flows.Action) – The action to perform when the embedded link is clicked.

  • visible (bool | str | pywa.types.flows.DataKey | None) – Whether the embedded link is visible or not. Default to True. Can be dynamic (e.g DataKey("is_visible")).

class pywa.types.flows.DatePicker#

DatePicker component allows users to select a date

Variables:

  • name (str) – The unique name (id) for this component (to be used dynamically or in action payloads).

  • label (str | pywa.types.flows.DataKey) – The label of the date picker. Limited to 40 characters. Can be dynamic (e.g DataKey("label")).

  • min_date (str | pywa.types.flows.DataKey | None) – The minimum date (timestamp in ms) that can be selected. Can be dynamic (e.g DataKey("min_date")).

  • max_date (str | pywa.types.flows.DataKey | None) – The maximum date (timestamp in ms) that can be selected. Can be dynamic (e.g DataKey("max_date")).

  • unavailable_dates (Iterable[str] | str | pywa.types.flows.DataKey | None) – The dates (timestamp in ms) that cannot be selected. Can be dynamic (e.g DataKey("unavailable_dates")).

  • helper_text (str | pywa.types.flows.DataKey | None) – The helper text of the date picker. Limited to 80 characters. Can be dynamic (e.g DataKey("helper_text")).

  • enabled (bool | str | pywa.types.flows.DataKey | None) – Whether the date picker is enabled or not. Default to True. Can be dynamic (e.g DataKey("enabled")).

  • required (bool | str | pywa.types.flows.DataKey | None) – Whether the date picker is required or not. Can be dynamic (e.g DataKey("required")).

  • visible (bool | str | pywa.types.flows.DataKey | None) – Whether the date picker is visible or not. Default to True. Can be dynamic (e.g DataKey("is_visible")).

  • on_select_action (pywa.types.flows.Action | None) – The action to perform when a date is selected.

class pywa.types.flows.Image#

Image component allows users to pick multiple selections from a list of options.

  • Read more at developers.facebook.com.

  • Supported images formats are JPEG PNG

  • Recommended image size is up to 300kb

  • Max number of images per screen is 3

Variables:
class pywa.types.flows.ScaleType#

The scale type of the image.

Variables:

  • COVER – Image is clipped to fit the image container.

  • CONTAIN – Image is contained within the image container with the original aspect ratio.

class pywa.types.flows.DataSource#

The data source of a component.

Variables:

  • id (str) – The ID of the data source.

  • title (str) – The title of the data source. Limited to 30 characters.

  • description (str | None) – The description of the data source. Limited to 300 characters.

  • metadata (str | None) – The metadata of the data source. Limited to 20 characters.

  • enabled (bool | None) – Whether the data source is enabled or not. Default to True.

class pywa.types.flows.Action#

Action component allows users to trigger asynchronous actions handled by a client through interactive UI elements.

Variables:
class pywa.types.flows.FlowActionType#

Flow JSON provides a generic way to trigger asynchronous actions handled by a client through interactive UI elements.

Variables:

  • COMPLETE –

    Triggers the termination of the Flow with the provided payload (Read more at developers.facebook.com).

  • DATA_EXCHANGE –

    Sending Data to WhatsApp Flows Data Endpoint (Read more at developers.facebook.com).

  • NAVIGATE –

    Triggers the next screen with the payload as its input. The CTA button will be disabled until the payload with data required for the next screen is supplied. (Read more at developers.facebook.com).

class pywa.types.flows.ActionNext#

The next action

Variables:
class pywa.types.flows.ActionNextType#

The type of the next action

Variables:

  • SCREEN – Navigate to the next screen

  • PLUGIN – Trigger a plugin

class pywa.types.flows.DataKey#
class pywa.types.flows.FormRef#
Contents