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 of the flow (Read more at developers.facebook.com).

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

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

  • data_api_version (str | float | Literal[<Version.FLOW_DATA_API: '3.0'>] | None) – The version to use during communication with the WhatsApp Flows Data Endpoint. Use utils.Version.FLOW_DATA_API to get the latest version

  • 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.

Example

>>> from pywa.types.flows import Screen
>>> screen = Screen(
...     id='START',
...     title='Welcome',
...     data=[ScreenData(key='welcome', example='Welcome to my store!')],
...     terminal=True,
...     layout=Layout(children=[Form(children=[...])]),
...     refresh_on_back=True
... )
Variables:

  • id (str) – Unique identifier of the screen for navigation purposes. SUCCESS is a reserved keyword and should not be used as a screen id.

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

  • data (Iterable[pywa.types.flows.ScreenData] | dict[str, dict] | None) – Declaration of dynamic data that this screen should get from the previous screen or from the data endpoint. In the screen children and in Action .payload, you can use the .data_key or DataKey to reference this data.

  • 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 on the terminal screen.

  • refresh_on_back (bool | None) –

    Whether to trigger a data exchange request with the data endpoint when the user presses the back button while on this screen (Read more at developers.facebook.com).

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

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

  • success (bool | None) – To indicate whether terminating on that screen results in a successful flow completion.

class pywa.types.flows.ScreenData#

Represents a screen data that a screen should get from the previous screen or from the data endpoint.

  • You can use the .data_key property or the DataKey to reference this data in the screen children or in the action payloads.

  • Read more at developers.facebook.com.

Example

>>> from pywa.types.flows import ScreenData
>>> dynamic_welcome = ScreenData(key='welcome', example='Welcome to my store!')
>>> is_email_required = ScreenData(key='is_email_required', example=False)
>>> screen = Screen(
...     id='START',
...     data=[dynamic_welcome, is_email_required],
...     layout=Layout(children=[Form(children=[
...         TextHeading(text=dynamic_welcome.data_key, ...),
...         TextInput(required=is_email_required.data_key, input_type=InputType.EMAIL, ...)
...     ])])
... )
Variables:
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.

  • Currently, only LayoutType.SINGLE_COLUMN is supported.

Variables:

SINGLE_COLUMN – A single column layout.

class pywa.types.flows.Form#

The form component is a container for other components that collects user input.

Variables:
class pywa.types.flows.TextHeading#

Represents text that is displayed as a heading.

Example

>>> from pywa.types.flows import TextHeading
>>> heading = TextHeading(text='Heading', visible=True)
Variables:
class pywa.types.flows.TextSubheading#

Represents text that is displayed as a subheading.

Example

>>> from pywa.types.flows import TextSubheading
>>> subheading = TextSubheading(text='Subheading', visible=True)
Variables:
class pywa.types.flows.TextBody#

Represents text that is displayed as a body.

Example

>>> from pywa.types.flows import TextBody, FontWeight
>>> body = TextBody(
...     text='Body',
...     font_weight=FontWeight.BOLD,
...     visible=True
... )
Variables:
class pywa.types.flows.TextCaption#

Represents text that is displayed as a caption.

Example

>>> from pywa.types.flows import TextCaption, FontWeight
>>> caption = TextCaption(
...     text='Caption',
...     font_weight=FontWeight.ITALIC,
...     strikethrough=True,
... )
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.

Example

>>> from pywa.types.flows import TextInput, InputType
>>> text_input = TextInput(
...     name='email',
...     label='Email',
...     input_type=InputType.EMAIL,
...     required=True,
...     min_chars=5,
...     max_chars=50,
...     helper_text='Enter your email address',
... )
Variables:
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 (for multi-line text use TextArea).

  • NUMBER – A number (keyboard layout is numeric, with a decimal separator).

  • EMAIL – An email address (keyboard layout is alphanumeric, with a special character for the @ symbol).

  • PASSWORD – A password (the input is masked).

  • PASSCODE – A passcode (keyboard layout is numeric, the input is masked).

  • PHONE – A phone number (keyboard layout is numeric, with a special character for the + symbol).

class pywa.types.flows.TextArea#

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

Example

>>> from pywa.types.flows import TextArea
>>> text_area = TextArea(
...     name='description',
...     label='Description',
...     required=True,
...     max_length=100,
...     helper_text='Enter your description',
... )
Variables:
class pywa.types.flows.CheckboxGroup#

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

Example

>>> from pywa.types.flows import CheckboxGroup, DataSource
>>> checkbox_group = CheckboxGroup(
...     name='options',
...     data_source=[
...         DataSource(id='1', title='Option 1'),
...         DataSource(id='2', title='Option 2'),
...         DataSource(id='3', title='Option 3'),
...     ],
...     label='Options',
...     min_selected_items=1,
...     max_selected_items=2,
...     required=True,
...     init_value=['1', '2']
... )
Variables:
class pywa.types.flows.RadioButtonsGroup#

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

Example

>>> from pywa.types.flows import RadioButtonsGroup, DataSource
>>> radio_buttons_group = RadioButtonsGroup(
...     name='options',
...     data_source=[
...         DataSource(id='1', title='Option 1'),
...         DataSource(id='2', title='Option 2'),
...         DataSource(id='3', title='Option 3'),
...     ],
...     label='Options',
...     required=True,
...     init_value='1'
... )
Variables:
class pywa.types.flows.Footer#

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

Example

>>> from pywa.types.flows import Footer, Action, FlowActionType, ActionNext
>>> submit_footer = Footer(
...     label='Submit',
...     on_click_action=Action(
...         name=FlowActionType.COMPLETE,
...         payload={'data': 'value'}
...     )
... )

>>> navigation_footer = Footer(
...     label='Next',
...     on_click_action=Action(
...         name=FlowActionType.NAVIGATE,
...         next=ActionNext(name='NEXT_SCREEN'),
...         payload={'data': 'value'}
...     )
Variables:

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

  • 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.

  • 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.

  • 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.

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

class pywa.types.flows.OptIn#

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

Example

>>> from pywa.types.flows import OptIn
>>> opt_in = OptIn(
...     name='opt_in',
...     label='I agree to the terms and conditions',
...     required=True,
...     init_value=True
... )
Variables:
class pywa.types.flows.Dropdown#

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

Example

>>> from pywa.types.flows import Dropdown, DataSource
>>> dropdown = Dropdown(
...     name='options',
...     data_source=[
...         DataSource(id='1', title='Option 1'),
...         DataSource(id='2', title='Option 2'),
...         DataSource(id='3', title='Option 3'),
...     ],
...     label='Options',
...     required=True,
...     init_value='1'
... )
Variables:

EmbeddedLink component allows users to navigate to another screen.

  • 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.

Example

>>> from pywa.types.flows import EmbeddedLink, Action, ActionNext
>>> embedded_link = EmbeddedLink(
...     text='Sign up',
...     on_click_action=Action(
...         name=FlowActionType.NAVIGATE,
...         next=ActionNext(name='SIGNUP_SCREEN'),
...         payload={'data': 'value'}
...     )
... )
Variables:
class pywa.types.flows.DatePicker#

DatePicker component allows users to select a date

Example

>>> from pywa.types.flows import DatePicker
>>> date_picker = DatePicker(
...     name='date',
...     label='Appointment Date',
...     min_date='1577829600000',
...     max_date='1704060000000',
...     unavailable_dates=[
...         '1609452000000',
...         '1640988000000'
...     ],
...     helper_text='Select a date',
...     required=True
... )
Variables:
class pywa.types.flows.Image#

Image component that displays an image.

  • 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

Example

>>> from pywa.types.flows import Image, ScaleType
>>> image = Image(
...     src='iVBORw0KGgoAAAANSUhEUgAAAlgAAAM...',
...     width=100,
...     height=100,
...     scale_type=ScaleType.CONTAIN,
...     aspect_ratio=1,
...     alt_text='Image of a cat'
... )
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.

Example

>>> from pywa.types.flows import DataSource
>>> option_1 = DataSource(id='1', title='Option 1')
>>> option_2 = DataSource(id='2', title='Option 2')
>>> checkbox_group = CheckboxGroup(data_source=[option_1, option_2], ...)
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 that are handled by a client through interactive UI elements.

Example

>>> from pywa.types.flows import Action, FlowActionType, ActionNext
>>> complete_action = Action(
...     name=FlowActionType.COMPLETE,
...     payload={'data': 'value'}
... )
>>> data_exchange_action = Action(
...     name=FlowActionType.DATA_EXCHANGE,
...     payload={'data': 'value'}
... )
>>> navigate_action = Action(
...     name=FlowActionType.NAVIGATE,
...     next=ActionNext(name='NEXT_SCREEN'),
...     payload={'data': 'value'}
... )
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