Components

Components are like building blocks. They allow you to build complex UIs and display business data using attribute models. The maximum number of components per screen is 50. Please refer to best practices for components.

The following components are supported:

• Basic Text (Heading, Subheading, Caption, Body)

• RichText

• TextEntry

• CheckboxGroup

• RadioButtonsGroup

• Footer

• OptIn

• Dropdown

• EmbeddedLink

• DatePicker

• CalendarPicker

• Image

• If

• Switch

• Media upload

• NavigationList

Text Components

Heading

This is the top level title of a page.

Subheading

Body

Caption

Limits and Restrictions

Additional capabilities for Text components

In Flow JSON V5.1 TextBody and TextCaption also supports a limited markdown syntax. In order to enable this capability, set the property markdown=true; this will instruct Whatsapp Flows to enable markdown syntax within these components.

{
   "type": "TextBody",
   "markdown": true,
   "text": [
     "This text is ~~***really important***~~",
   ]
}

{
   "type": "TextCaption",
   "markdown": true,
   "text": [
     "This text is ~~***really important***~~",
   ]
}

For comparison purposes, we show how the text components look like next to one another:

Rich Text

Flow JSON 5.1 introduces a new component - RichText. 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.

Supported Syntax

Headings

The current syntax supports only Heading (h1) and Subheading (h2). Other heading levels will be parsed but rendered as normal text - TextBody.

{
   "type": "RichText",
   "text": [
     "# Heading level 1",
   ]
}

{
   "type": "RichText",
   "text": [
     "## Heading level 2",
   ]
}

{
       "type": "RichText",
       "text": [
         "### Heading level 3",
        "#### Heading level 4",
         "##### Heading level 5",
        "###### Heading level 6",
       ]
    }

Paragraphs

To create paragraphs, split your text into different array items:

{
       "type": "RichText",
       "text": [
         "Paragraph 1",
        "Paragraph 2",
       ]
    }

or add a blank line in your markdown document that you bind using dynamic binding syntax ${data.your_dynamic_field}

# Heading 1    
Paragraph 1
  
Paragraph 2

{
       "type": "RichText",
       "text": "${data.text}"
    }

Text Formatting

{
   "type": "RichText",
   "text": [
     "Let’s make a **bold** statement",
   ]
}

{
   "type": "RichText",
   "text": [
     "Let's make this text *italic*",
   ]
}

{
   "type": "RichText",
   "text": [
     "Let's make this text ~~Strikethrough~~",
   ]
}

{
   "type": "RichText",
   "text": [
     "This text is ~~***really important***~~",
   ]
}

Lists

You can organize items into ordered and unordered lists. At the moment, only single level lists are supported.

{
   "type": "RichText",
   "text": [
     "1. Item 1",
     "2. Item 2",
     "3. Item 3"
   ]
}

{
   "type": "RichText",
   "text": [
     "- Item 1",
     "- Item 2",
     "- Item 3"
   ]
}

{
   "type": "RichText",
   "text": [
     "+ Item 1",
     "+ Item 2",
     "+ Item 3"
   ]
}

Images

You can also include images in the content. Please note, external URIs are not supported and you can only include base64 inline images

{
   "type": "RichText",
   "text": ["![Image alt text](data:image/png;base64,<base64 content>)"]
}

Recommended image formats:

1. png
2. jpg / jpeg
3. webp (please note, webp is only supported starting from IOS 14.6+, that corresponds to ~98% of IOS devices)

Links

To create a link, enclose the link text in brackets and then follow it immediately with the URL in parentheses

{
   "type": "RichText",
   "text": [
     "[Whatsapp Flows are awesome](https://business.whatsapp.com/products/whatsapp-flows)",
   ]
}

Tables

To add a table, use three or more hyphens (---) to create each column’s header, and use pipes (|) to separate each column. For compatibility, you should also add a pipe on either end of the row.

Cell content can be combined with the following syntax:

1. Italic, bold, strikethrough
2. Images
3. Links

{
   "type": "RichText",
   "text": [
     "| Column Header 1     | Column Header 2                                             |",
     "| -------------       |  -------------                                              |",
     "| **Bold** text 1     | [Link](<URI>)                                               |",
     "| **Bold** text 1     | ![Image alt text](data:image/png;base64,<base64 content>)   |",
   ]
}

Width of the columns:

Width of the column is based on the Header content size. Markdown specification doesn’t provide a specific syntax for controlling a column width. If you want to make a certain column wider, simply add additional content to the header:

{
   "type": "RichText",
   "text": [
     "| Column Header 1 - Extended width  | Column Header 2       |",
     "| -------------                     |  -------------        |",
     "| **Bold** text 1                   | Cell text 2           |",
   ]
}

Working with large texts

If your text content for markdown has a limited size, you can incorporate it as a static text as shown in all examples above, however if your text is large and you expect to update it often on your server, we recommend sending it as a part of dynamic data, this will improve overall readability of the JSON and allow to load always up to date text from your server.

Syntax cheatsheet

Here is the quick overview of the syntax that’s supported by RichText, TextBody and TextCaption components

+ Item 1
+ Item 2

1. Item 1
2. Item 2

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Row 1    | Data 1   | More Data |
| Row 2    | Data 2   | More Data |
| Row 3    | Data 3   | More Data | 

Usage example

Text Entry Components

TextInput

TextArea

Limits and Restrictions

Together, the text entry components look like as shown:

CheckboxGroup

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

Example

For the data-source field, you can declare it dynamically or statically.

Static Example

This static example hardcodes the respective id's and title's for the data-source field.

Dynamic Example

In this dynamic example, you can see that data-source references the days_per_week_options of type array defined before it using days_per_week_options. When defining such a structure, you need to specify items in the array, which will be of type object. Then inside the items object, you have a properties dictionary with id and title just like in the static declaration. Both id and title will always be of type String. Within the days_per_week_options array, you must define concrete examples in the __example__ field.

Limits and Restrictions

RadioButtonsGroup

Example

For the data-source field, you can declare it dynamically or statically.

Static Example

This static example hardcodes the respective id's and title's for the data-source field.

Dynamic Example

In this dynamic example, you can see that data-source references the experience_level_options of type array defined before it using data.experience_level_options. When defining such a structure, you need to specify items in the array, which will be of type object. Then inside the items object, you have a properties dictionary with id and title just like in the static declaration. Both id and title will always be of type String. Within in the experience_level_options array you must define concrete examples in the __example__ field.

Limits and Restrictions

Footer

Limits and Restrictions

OptIn

Example

Limits and Restrictions

Dropdown

Example

Limits and Restrictions

For the data-source field, you can declare it dynamically or statically.

Static Example

This static example hardcodes the respective id's and title's for the data-source field.

Dynamic Example

In this dynamic example, you can see that data-source references the experience_level_options of type array defined before it using experience_level_options. When defining such a structure, you need to specify items in the array, which will be of type object. Then inside the items object, you have a properties dictionary with id and title just like in the static declaration. Both id and title will always be of type String. Within the experience_level_options array you must define concrete examples in the __example__ field.

Embedded Link

Limits and Restrictions

DatePicker

The DatePicker component allows users to input dates through an intuitive date selection interface.

Payload that is sent to a data channel business endpoint is a string which shows the timestamp in milliseconds.

Flow JSON version 4.0

Flow JSON version 5.0

Guidelines for Usage

Before flow JSON version 5.0

Due to current system limitations, the DatePicker functions correctly and as intended(that is, correct selection range is shown to the User, and accurate user-selection value is returned to the Business) as long as

• The guidelines in this section are followed
• Both the business sending the Flow and its end-users are in the same time zone.

Handling of Dates for Businesses and Users in the Same Time Zone

DatePicker allows setting of date range for user selection through min-dates and max-dates fields, and also prevents selection of specific dates using the unavailable-dates field. If you have not supplied the date range , then by default, the component allows the user to select dates from 1 January 1900 to 31 December 2100.

Setting Date Parameters in the Component

When you specify the date range or set unavailable dates, you should convert your local dates with midnight (00:00:00) as a base time to UTC timestamps.

For example, if you are a business based in India who wants to collect a date in the range 21 March 2024 to 25 March 2024, then you should set min-dates and max-dates as 1710958020000 and 1711303620000, respectively.

21 March 2024, 00:00:00.000 IST converts to 20 March 2024, 18:30:00.000 UTC which is represented by timestamp 1710958020000.

25 March 2024, 00:00:00.000 IST converts to 24 March 2024, 18:30:00.000 UTC which is represented by timestamp 1711303620000.

Component Integration

DatePicker will read the timestamps in min-dates, max-dates and unavailable-dates fields and convert it to the end user's local date for displaying on the UI. In the example we discussed above, a user in India will see dates from 21 March 2024 to 25 March 2024 in the DatePicker component.

Processing User Selection

Businesses will receive a UTC timestamp, which should be converted back to the business's local time zone. Importantly, businesses should focus solely on the date portion of the resulting timestamp , disregarding the time portion. This ensures that the date remains consistent with the user's selection. Unfortunately, this conversion will only work correctly when the business and user are in the same time zone.

For example, if you receive a timestamp 1711013400000 then convert it to your local timezone and extract the date. If you are in IST, the timestamp will convert to 21 March 2024 15:00 IST, and you should treat 21st March 2024 as the user selected date.

Recommendation for navigating Time Zone differences

If you need to send flow messages to users in time zones different from yours despite reviewing the above guidelines, follow these steps to overcome the limitation:

• If you are a business based in Brazil and want to serve flows to your users across the country, then your time zone range will be UTC-2 (Fernando de Noronha) to UTC-5 (Rio Branco).
• Add a Dropdown component within your Flow that allows users to select their current time zone.
• Identify the westernmost time zone from your time zone range. In our example, it is UTC-5.
• Provide the dates you want to collect in the westernmost time zone, using midnight as the reference time. For example, if you want to collect dates from March 20th, 2024 to March 25th, 2024, then provide the timestamp in milliseconds for March 20th, 2024 at 5 AM UTC and March 25th, 2024 at 5 AM UTC.
• Convert the timestamps received from the user to their respective time zone and use the corresponding date. For example, if a user is in Sao Paulo(UTC-3) and you receive a timestamp of 1710910800000, then convert it to UTC-3 to get March 20th, 2024.

Start from flow JSON version 5.0

DatePicker component has been updated to use a formatted date string in the format "YYYY-MM-DD", such as "2024-10-21", for setting and retrieving date values. This update makes the date values of the date picker unrelated to time zones, allowing businesses to send messages and collect dates from users in any time zone in a consistent manner.

Limits and Restrictions

CalendarPicker

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

Examples

CalendarPicker single mode example

CalendarPicker range mode example

Limits and Restrictions

Image

Image Scale Types

Example

Limits and Restrictions

If

Supported Operators

Example

Rules

Condition

• Should have at least one dynamic value (e.g. ${data...} or ${form...}).
• 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

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

Limitations and restrictions

The table below show examples of limitations and validation errors that will be shown for certain cases.

Switch

Example

Rules

Cases

• Should have at least one value. It cannot be empty (e.g. "cases": {})

Limitations and restrictions

The table below show examples of limitations and validation errors that will be shown for certain cases.

Media upload

Please refer to the specific page for media upload components.

Navigation List

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.

Each item in the list of items supports the following properties:

The on-click-action is required for the component, and it can be defined either:

• Once at component-level and it will apply the same action for all items in the list.
• Individually, on each item in the list to allow for different actions to be triggered.

Example

Dynamic Example

In this dynamic example, you can see that list-items references the insurances of type array defined before it using insurances. When defining such a structure, you need to specify items in the array, which will be of type object. Then inside the items object, you have a properties dictionary with id and main-content just like in the static declaration. Both id will always be of type string and main-content will always be of type object, and accompanied by a definition of its structure. Within the insurances array, you must define concrete examples in the __example__ field.

Limits and Restrictions

• The `Navigation List` component cannot be used on a terminal screen.
• There can be at most 2 `Navigation List` components per screen.
• The `Navigation List` components cannot be used in combination with any other components in the same screen.
• 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.

Component restrictions

List items restrictions

Dynamic components

Here's a corrected version:

If you check the attribute model of certain components (Dropdown, DatePicker, RadioGroup and CheckboxGroup), you will find that some of them accept the on-xxxx-action attribute. This attribute allows the component to trigger a data-exchange action. It can be used in the following scenarios:

1. When a user selects a date in the DatePicker component.
2. When the business needs to fetch available data (such as table slots, tickets, etc.) for this selected date by calling a data_exchange action.
3. Once the data is received, the user will see an updated screen with new data.

{
   "on-select-action":{
      "name":"data_exchange",
      "payload":{
         "date":"${form.date}",
         "component_action":"update_date"
      }
   }
}

{
    "available_slots": {
        "type": "array",
        "items": {
            "type": "object",
            "properties": { "id": {"type": "string"}, "title": {"type": "string"} }
        },
        "__example__": [ {"id": "1", "title": "08:00"}, {"id": "2", "title": "09:00"} ]
    }
}

{
    "version": "3.0",
    "screen": "BOOKING",
    "data": {
       "available_slots": [ {"id": "1", "title": "08:00"}, {"id": "2", "title": "09:00"} ]
    }
}

Summary

That's it! Now you have a dynamic component set up. If you're facing any challenges, feel free to ask a question on the developer forum. We'll be happy to help!