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[pywa.utils.Version.FLOW_JSON]) –

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

  • data_api_version (str | float | Literal[pywa.utils.Version.FLOW_DATA_API] | 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

>>> 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 which works as a page url. 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 flow endpoint. In the screen children and in DataExchangeAction .payload, you can use the ref or ScreenDataRef to reference this data.

  • terminal (bool | None) – The business flow is the end state machine. It means that 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. 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 FlowRequest (action will be FlowRequestActionType.BACK) with the flow endpoint when the user presses the back button while on this screen. The property is useful when you need to reevaluate the screen data when returning to the previous 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) – Defaults to true. A Flow can have multiple terminal screens with different business outcomes. This property marks whether terminating on a terminal screen should be considered a successful business outcome.

  • sensitive (Iterable[str] | None) – This array contains the names of the fields in the screen that contain sensitive data, and should be hidden in the response summary displayed to the user. (added in v5.1)

class pywa.types.flows.ScreenData#

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

Example

>>> Screen(
...     id='START',
...     data=[
...         dynamic_welcome := ScreenData(key='welcome', example='Welcome to my store!')
...         is_email_required := ScreenData(key='is_email_required', example=False)
...     ],
...     layout=Layout(children=[Form(children=[
...         TextHeading(text=dynamic_welcome.ref, ...),
...         TextInput(required=is_email_required.ref, input_type=InputType.EMAIL, ...)
...     ])])
... )
property ref: ScreenDataRef#
The refernece for this data to use in the same screen children.

  • Use this property to reference this data in the screen children. Use the ref_in(screen)() to reference this data in ANOTHER screen children.

Example

>>> FlowJSON(
...     screens=[
...         Screen(
...             id='START',
...             data=[dynamic_welcome := ScreenData(key='welcome', example='Welcome to my store!')],
...             layout=Layout(children=[TextHeading(text=dynamic_welcome.ref, ...)])  # Use the .ref here
...         )
...     ],
...     ...
... )
ref_in(screen: Screen | str) → ScreenDataRef#
The key for this data to use in ANOTHER screen children.

  • If you want to reference this data in the same screen children, use the ref() property.

  • A shortcut for ScreenDataRef with this key and screen.

  • You can also use screen / data.ref to reference this data in other screens.

  • Added in v4.0.

Example

>>> FlowJSON(
...     screens=[
...         start := Screen(
...             id='START',
...             data=[dynamic_welcome := ScreenData(key='welcome', example='Welcome to my store!')],
...             layout=Layout(children=[...])
...         ),
...         Screen(
...             id='END',
...             layout=Layout(
...                 children=[
...                     TextHeading(text=dynamic_welcome.ref_in("START"), ...),  # using the `.ref_in(screen)` method
...                     TextHeading(text=start/dynamic_welcome.ref, ...)  # using the `screen / data.ref` syntax
...                 ]
...             )
...         )
...     ],
...     ...
... )
Parameters:

screen – The screen id to reference this data in its children.

update(new_value: str | int | float | bool | dict | date | DataSource | Iterable[str | int | float | bool | dict | date | DataSource | NavigationItem]) → ScreenDataUpdate#

Update the value of this data. Use this inside the UpdateDataAction .payload.

Example:

>>> is_visible = ScreenData(key='is_visible', example=True)
>>> UpdateDataAction(payload=[is_visible.update(False)])
Parameters:

new_value – The new value of the data.

Returns:

The update action for this data.

class pywa.types.flows.ScreenDataUpdate#

Represents an update action for a screen data.

 1Screen(
 2    id="DEMO_SCREEN",
 3    data=[
 4        is_txt_visible := ScreenData(
 5            key="is_txt_visible",
 6            example=False,
 7        ),
 8    ],
 9    layout=Layout(
10        children=[
11            OptIn(
12                label="Show the text",
13                name="show_txt",
14                on_select_action=UpdateDataAction(
15                    payload=[is_txt_visible.update(True)]  # a much cleaner way
16                ),
17                on_unselect_action=UpdateDataAction(
18                    payload=[ScreenDataUpdate(key="is_txt_visible", new_value=False)]  # only when you don't have access to the `ScreenData` object
19                ),
20            ),
21            TextBody(
22                text="You clicked the button!",
23                visible=is_txt_visible.ref,
24            ),
25        ]
26    )
27)
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 vertical flexbox container that stacks the components in a single column.

class pywa.types.flows.Form#

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

Variables:
class pywa.types.flows.FormComponent#

Base class for all components that must be inside a form (if FlowJSON version is below 4.0)

property ref: ComponentRef#
The reference variable for this component.

  • Use this when the reference is in the same screen. Use .ref_in(screen) when the reference is in another screen.

  • A shortcut for ComponentRef with this component name.

Example

>>> FlowJSON(
...     screens=[
...         Screen(
...             id='START',
...             layout=Layout(children=[
...                 Form(children=[
...                     text_input := TextInput(name='email', ...),
...                     TextHeading(text="Your email is:", ...)
...                     TextCaption(text=text_input.ref, ...)
...                 ]),
...                 Footer(label='Submit', action=Action(payload={'email': text_input.ref}))
...         ])
...     ]
... )
ref_in(screen: Screen | str) → ComponentRef#
The component reference variable for this component in another screen.

  • Use .ref property when the reference is in the same screen.

  • You can also use screen/component.ref to get the reference variable in another screen.

  • Added in v4.0.

Example

>>> FlowJSON(
...     screens=[
...         other := Screen(
...             id='OTHER',
...             layout=Layout(children=[Form(children=[email := TextInput(name='email', ...), ...])])
...         ),
...         Screen(
...             id='START',
...             layout=Layout(children=[
...                 TextCaption(text=email.ref_in('OTHER'), ...)  # using the `.ref_in(screen)` method
...                 TextCaption(text=other/email.ref, ...)  # using the screen/component.ref syntax
...             ])
...         )
...     ]
... )
Parameters:

screen – The screen that contains the component.

class pywa.types.flows.TextHeading#

Represents text that is displayed as a heading.

Example

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

Represents text that is displayed as a subheading.

Example

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

Represents text that is displayed as a body.

Example

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

Represents text that is displayed as a caption.

Example

>>> TextCaption(
...     text='Caption',
...     font_weight=FontWeight.ITALIC,
...     strikethrough=True,
... )
Variables:
class pywa.types.flows.RichText#

Represents text that is displayed as a rich text.

  • Read more at developers.facebook.com.

  • The goal of the component is to provide a rich formatting capabilities and introduce the way to render large texts (Terms of Condition, Policy Documents, User Agreement and etc) without facing limitations of basic text components (TextHeading, TextSubheading, TextBody and etc)

  • RichText component utilizes a select subset of the Markdown specification. It adheres strictly to standard Markdown syntax without introducing any custom modifications. Content created for the RichText component is fully compatible with standard Markdown documents.

  • Added in v5.1.

Example

>>> RichText(
...     text=[
...         "# Heading 1",
...         "## Heading 2",
...         "Let’s make a **bold** statement",
...         "Let's make this text *italic*",
...         "Let's make this text ~~Strikethrough~~",
...         "This text is ~~***really important***~~",
...         "This is a [pywa docs](https://pywa.readthedocs.io/)",
...         "This is a ordered list:",
...         "1. Item 1",
...         "2. Item 2",
...         "This is a unordered list:",
...         "- Item 1",
...         "- Item 2",
...         "![image](data:image/png;base64,<base64 content>)",
...         "| Tables        | Are           | Cool  |",
...         "| ------------- | ------------- | ----- |",
...         "| col 3 is      | right-aligned | $1600 |",
...         "| col 2 is      | centered      |   $12 |",
...     ],
... )
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

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

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

>>> 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.ChipsSelector#

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

Example

>>> ChipsSelector(
...     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

>>> 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.MediaSize#

The media size of the image.

Variables:

  • REGULAR – Regular size

  • LARGE – Large size

class pywa.types.flows.Footer#

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

Variables:
class pywa.types.flows.OptIn#

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

  • This component must be inside a Form (if FlowJSON version is below 4.0).

  • Max number of Opt-Ins Per Screen is 5.

  • Read more at developers.facebook.com.

Example

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

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

  • 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

>>> EmbeddedLink(
...     text='Sign up',
...     on_click_action=NavigateAction(
...         next=Next(name='SIGNUP_SCREEN'),
...         payload={'data': 'value'}
...     )
... )
Variables:
class pywa.types.flows.NavigationList#

The NavigationList component allows users to navigate effectively between different screens in a Flow, by exploring and interacting with a list of options. Each list item can display rich content such as text, images and tags.

  • Read more at developers.facebook.com.

  • Added in v6.2

  • The on_click_action is required for this component and can be defined either at the component level or in each NavigationItem.

  • There can be at most 2 NavigationList components per screen.

  • The NavigationList components cannot be used in combination with any other components in the same screen.

Example

>>> NavigationList(
...     name='navigation_list',
...     list_items=[
...         NavigationItem(
...             id='1',
...             main_content=NavigationItemMainContent(title='Title 1', description='Description 1'),
...             start=NavigationItemStart(image='base64image...'),
...             end=NavigationItemEnd(title="$100", description="/ month"),
...             badge='New',
...             on_click_action=NavigateAction(next=Next(name='SCREEN_1'))
...         ),
...         ...
...     ],
... )
Variables:
class pywa.types.flows.NavigationItem#

The NavigationItem represents an item in the NavigationList component.

  • There can be only one item with a badge per list.

  • The end add-on cannot be used in combination with media_size set to LARGE.

  • The on_click_action cannot be defined simultaneously on component-level and on item-level.

Variables:
class pywa.types.flows.NavigationItemStart#

The start content of the NavigationItem component.

Variables:

image (str) – The image of the item content (base64 encoded, limited to 100KB).

class pywa.types.flows.NavigationItemMainContent#

The main content of the NavigationItem component.

Variables:

  • title (str) – The title of the item content. Limited to 30 characters.

  • description (str | None) – The description of the item content. Limited to 20 characters.

  • metadata (str | None) – The metadata of the item content. Limited to 80 characters.

class pywa.types.flows.NavigationItemEnd#

The end content of the NavigationItem component.

Variables:

  • title (str | None) – The title of the end content. Limited to 10 characters.

  • description (str | None) – The description of the end content. Limited to 20 characters.

  • metadata (str | None) – The metadata of the end content. Limited to 80 characters.

class pywa.types.flows.DatePicker#

DatePicker component allows users to select a date

  • This component must be inside a Form (if FlowJSON version is below 4.0).

  • Starting from FlowJSON version 5.0, you can use date/datetime python objects or a formatted date string in the format “YYYY-MM-DD”, such as “2024-10-21” or

  • Read more at developers.facebook.com.

Example

>>> DatePicker(
...     name='date',
...     label='Appointment Date',
...     min_date=datetime.date(2024, 7, 21),
...     max_date=datetime.date(2024, 10, 21),
...     unavailable_dates=[
...         datetime.date(2024, 7, 25),
...         datetime.date(2024, 7, 26),
...     ],
...     helper_text='Select a date',
...     required=True
... )
Variables:
class pywa.types.flows.CalendarPicker#

CalendarPicker component allows users to select a single date or a range of dates from a full calendar interface.

Example

>>> CalendarPicker(
...     name='date',
...     label='Appointment Date',
...     mode=CalendarPickerMode.SINGLE,
...     min_date=datetime.date(2024, 7, 21),
...     max_date=datetime.date(2024, 10, 21),
...     unavailable_dates=[
...         datetime.date(2024, 7, 25),
...         datetime.date(2024, 7, 26),
...     ],
...     helper_text='Select a date',
...     required=True
... )
Variables:
class pywa.types.flows.CalendarPickerMode#

The mode of the calendar picker.

Variables:

  • SINGLE – Allows to select one date.

  • RANGE – Allows to select start and end dates.

class pywa.types.flows.CalendarDay#

The days of the week.

Variables:

  • MON – Monday

  • TUE – Tuesday

  • WED – Wednesday

  • THU – Thursday

  • FRI – Friday

  • SAT – Saturday

  • SUN – Sunday

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

>>> 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.PhotoPicker#

PhotoPicker component allows uploading media from camera or gallery

Example

>>> PhotoPicker(
...     name='photo',
...     label='Take a photo',
...     description='We need your photo for verification',
...     photo_source=PhotoSource.CAMERA,
...     max_file_size_kb=10_000,  # 10MB
...     min_uploaded_photos=1,
...     max_uploaded_photos=3,
)
Variables:
class pywa.types.flows.PhotoSource#

The source where the image can be selected from.

Variables:

  • CAMERA_GALLERY – User can select from gallery or take a photo

  • CAMERA – User can select only from gallery

  • GALLERY – User can only take a photo

class pywa.types.flows.DocumentPicker#

DocumentPicker component allows uploading files from the device

  • Read more at developers.facebook.com.

  • Added in v4.0

  • Only 1 DocumentPicker is allowed per screen

  • Using both PhotoPicker and DocumentPicker components on a single screen is not allowed.

  • Note: some old Android and iOS OS versions don’t understand all mime types above. As a result, a user might be able to select a file with a different mime type to the ones specified.

Example

>>> DocumentPicker(
...     name='document',
...     label='Upload your Driving License',
...     description='We need your document for verification',
...     max_file_size_kb=5_000,  # 5MB
...     min_uploaded_documents=1,
...     max_uploaded_documents=1,
...     allowed_mime_types=['application/pdf', 'image/jpeg', 'image/png'],
)
Variables:
class pywa.types.flows.If#

If component allows users to add components based on a condition.

  • Read more at developers.facebook.com.

  • It is allowed to nest up to 3 If components.

  • Should have at least one dynamic value (e.g. screen_data.ref / form_comp.ref) in the condition.

  • Should always be resolved into a boolean (i.e. no strings or number values).

  • Can be used with literals but should not only contain literals.

  • Footer can be added within If only in the first level, not inside a nested If.

  • If there is a Footer within If, it should exist in both branches (i.e. then and else). This means that else becomes mandatory.

  • If there is a Footer within If it cannot exist a footer outside, because the max count of Footer is 1 per screen.

Example

>>> age = ScreenData(key="age", example=20)
>>> opt_in = OptIn(name="opt_in", ...)
>>> If(
...     condition=(age.ref > 21) && opt_in.ref,
...     then=[
...         TextHeading(text="Welcome to the club!"),
...         TextInput(
...             name='email',
...             label='Email',
...         ),
...     ],
...     else_=[
...         TextHeading(text="You are not eligible!"),
...     ]
... )
Variables:

  • condition (pywa.types.flows.Condition | str) – Boolean expression, You can use both dynamic and static values. See Supported Operators.

  • then (Iterable[pywa.types.flows.Component | dict[str, Any]]) – The components that will be rendered when condition is True.

  • else (Iterable[pywa.types.flows.Component | dict[str, Any]] | None) – The components that will be rendered when condition is False.

class pywa.types.flows.Switch#

Switch component allows users to add components based on a value of a screen data ref or form component ref.

Example

>>> age = TextInput(name='age', label='Age')
>>> switch = Switch(
...     value=age.ref,
...     cases={
...         '10': [TextHeading(text='Under 18')],
...         ...
...         '20': [TextInput(name='email', label='Email')],
...     }
Variables:
class pywa.types.flows.DataSource#

The data source of a component.

Example

>>> 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:
class pywa.types.flows.DataExchangeAction#

Data Exchange Action. Sending Data to WhatsApp Flows Data Endpoint

Example

>>> DataExchangeAction(
...     payload={'data': 'value'}
... )
Variables:

payload (dict[str, str | bool | Iterable[pywa.types.flows.DataSource] | pywa.types.flows.ScreenDataRef | pywa.types.flows.ComponentRef]) – The payload of the action (Pass data to the WhatsApp Flows Data Endpoint). This payload can take data from form components or from the data of the screen.

class pywa.types.flows.NavigateAction#

Navigate Action. Triggers the next screen with the payload as its input.

Example

>>> NavigateAction(
...     next=Next(name='NEXT_SCREEN'),
...     payload={'data': 'value'}
... )
Variables:
class pywa.types.flows.CompleteAction#

Complete Action. Triggers the termination of the Flow with the provided payload

Example

>>> CompleteAction(
...     payload={'data': 'value'}
... )
Variables:

payload (dict[str, str | bool | pywa.types.flows.ScreenDataRef | pywa.types.flows.ComponentRef]) – The payload to include in the FlowCompletion .response attribute.

class pywa.types.flows.UpdateDataAction#

Update Data Action. Triggers an immediate update to the screen’s state, reflecting user input changes.

Example

>>> is_visible = ScreenData(key='is_visible', example=True)
>>> UpdateDataAction(
...     payload=[
...         is_visible.update(value=False)
...     ]
... )
Variables:

payload (Iterable[pywa.types.flows.ScreenDataUpdate] | dict[str, str | int | float | bool | dict | datetime.date | pywa.types.flows.DataSource | Iterable[str | int | float | bool | dict | datetime.date | pywa.types.flows.DataSource | pywa.types.flows.NavigationItem]]) – The data to update for the current screen.

class pywa.types.flows.OpenUrlAction#

Open URL Action. Triggers a link to open in the device’s default web browser.

Example

>>> OpenUrlAction(
...     url='https://example.com'
... )
Variables:

url (str) – The URL to open

class pywa.types.flows.Next#

The next action

Variables:
class pywa.types.flows.NextType#

The type of the next action

Variables:

  • SCREEN – Navigate to the next screen

  • PLUGIN – Trigger a plugin

class pywa.types.flows.FlowStr#

Dynamic string that uses variables and math expressions. This is a helper class to avoid all the escaping and wrapping with quotes when using string concatenation.

  • Added in v6.0.

Example:

>>> FlowJSON(
...     screens=[
...         Screen(
...             id='START',
...             layout=Layout(children=[
...                 age := TextInput(name='age', input_type=InputType.NUMBER),
...                 email := TextInput(name='email', input_type=InputType.EMAIL),
...                 TextHeading(text=FlowStr("Your age is {age} and your email is {email}", age=age.ref, email=email.ref), ...)
...             ])
...         )
...     ]
... )

>>> FlowJSON(
...     screens=[
...         Screen(
...             id='START',
...             layout=Layout(children=[
...                 bill := TextInput(name='bill', input_type=InputType.NUMBER),
...                 tip := TextInput(name='tip', input_type=InputType.NUMBER),
...                 TextHeading(text=FlowStr("Your total bill is {bill}", bill=bill.ref + (bill.ref * tip.ref / 100)), ...)
...             ])
...         )
...     ]
... )
class pywa.types.flows.ScreenDataRef#

Represents a ScreenData reference (converts to ${data.<key>} | ${screen.<screen>.data.<key>}).

Example

  • Hint: use this class directly only if you don’t have access to the ScreenData object.

  • Hint: use the .ref property of ScreenData to get reference to a ScreenData.

  • Hint: use the .ref_in(screen) method of ScreenData to get the data ref from another screen (or screen/ref).

>>> FlowJSON(
...     screens=[
...         other := Screen(id='OTHER', data=[is_visible := ScreenData(key='is_visible', example=True)]),
...         Screen(
...             id='START',
...             data=[welcome := ScreenData(key='welcome', example='Welcome to my store!')],
...             layout=Layout(children=[
...                 TextHeading(
...                     text=welcome.ref, # data in the same screen
...                     visible=is_visible.ref_in(other) # data from other screen
...                 ),
...                 TextBody(
...                     text=ScreenDataRef(key='welcome', screen='START'), # using the class directly
...             ])
...         )
...     ]
... )
Parameters:

  • key – The key to get from the Screen .data attribute.

  • screen – The screen that contains the data (needed if the data is from another screen). Added in v4.0.

class pywa.types.flows.ComponentRef#

Represents a componenent reference variable (converts to ${form.<child>} | ${screen.<screen>.form.<child>}).

Example

  • Hint: use this class directly only if you don’t have access to the component object.

  • Hint: use the .ref property of each component to get a reference to this component.

  • Hint: use the .ref_in(screen) method of each component to get the component reference variable of that component with the given screen name.

>>> FlowJSON(
...     screens=[
...         other := Screen(
...             id='OTHER',
...             layout=Layout(children=[Form(children=[email := TextInput(name='email', ...), ...])])
...         ),
...         Screen(
...             id='START',
...             layout=Layout(children=[
...                 phone := TextInput(name='phone', ...),
...                 TextBody(text=phone.ref, ...),  # component reference from the same screen
...                 TextCaption(text=email.ref_in(other), ...)  # component reference from another screen
...                 TextHeading(text=ComponentRef('phone', screen='START'), ...)  # using the class directly
...             ])
...         )
...     ]
... )
Parameters:

  • component_name – The name of the component to get the value from.

  • screen – The name of the screen that contains the form. Added in v4.0.

class pywa.types.flows.Condition#

This class automatically created when using the comparison operators on Ref objects.

Example:

>>> age = TextInput(name="age", input_type=InputType.NUMBER)
>>> opt_in = OptIn(name="opt_in")
>>> text = TextBody(text=..., visible=(age.ref > 20) & opt_in.ref)

Supported Operators:

Operator

Symbol

Types allowed

Python

Equal

==

str, int, float

age.ref == 20

Not Equal

!=

str, int, float

age.ref != 20

Greater

>

int, float

age.ref > 20

Greater Equal

>=

int, float

age.ref >= 20

Less

<

int, float

age.ref < 20

Less Equal

<=

int, float

age.ref <= 20

And

&&

<Condition>

(age.ref > 20) & opt_in.ref

Or

||

<Condition>

(age.ref > 20) | opt_in.ref

Not

!

<Condition>

~opt_in.ref
class pywa.types.flows.MathExpression#

This class automatically created when using the arithmetic operators on Ref objects.

Example:

# Display the year you born in by subtracting the age from 2025:
>>> age = TextInput(name="age", input_type=InputType.NUMBER)
>>> text = TextBody(text=FlowStr("You born in {year}", year=2025 - age.ref))

# Calculating tip:
>>> bill = TextInput(name="bill", input_type=InputType.NUMBER)
>>> tip_percent = TextInput(name="tip_percent", input_type=InputType.NUMBER)
>>> total = TextBody(text=FlowStr("Total: {total}", total=bill.ref + (bill.ref * tip_percent.ref / 100)))

Supported Operators:

Operator

Symbol

Types allowed

Python

Add

+

int, float

age.ref + 20

Subtract

-

int, float

age.ref - 20

Multiply

*

int, float

age.ref * 20

Divide

/

int, float

age.ref / 20

Modulus

%

int, float

age.ref % 20