​

Flow JSON

1. Choose your business
2. Click on All tools in the left side navigation
3. Open WhatsApp Manager and select your WABA
4. On the left side navigation, go to Account tools > Flows

​

Introduction

​

Top-level Flow JSON Properties

​

Required properties

• version - represents the version of Flow JSON to use during the compilation. Please refer to the list of versions for more details.
• screens - represents an array or screen as part of the user experience. This is like a set of different pages on your website.

​

Optional properties

• routing_model - represents a routing ruling system. The routing model is generated automatically if your Flow doesn’t use a Data Endpoint. If it does, the validation system will ask you to provide a routing model.
• data_api_version - represents the version to use during communication with the WhatsApp Flows Data Endpoint. Currently, it is 3.0. If flow uses the data-channel capability, the validation system will ask to provide this property.
• data_channel_uri - represents the URL of the WhatsApp Flows Data Endpoint. If a Flow uses the data-channel capability, the validation system will ask to provide this property.

\{
 "version": "2.1",
 "data_api_version": "3.0",
 "routing_model": {"MY_FIRST_SCREEN": ["MY_SECOND_SCREEN"] },
 "screens": [...],
 "data_channel_uri": "https://example.com"
}

\{
 "version": "3.1",
 "data_api_version": "3.0",
 "routing_model": {"MY_FIRST_SCREEN": ["MY_SECOND_SCREEN"] },
 "screens": [...]
}

​

Screens

"screen" : {
  "id": string,
  "terminal": ?boolean,
  "success": ?boolean,
  "title": ?string,
  "refresh_on_back": ?boolean,
  "data": ?object,
  "layout": object
}

​

Required properties

• id - 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 - associated screen UI Layout that is shown to the user. Layout can be predefined or it can represent a container with fully customizable content built using WhatsApp Flows Library.

​

Optional properties

• terminal (optional) - 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.
• data (optional) - 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. Below you can find the simple example.

\{
  "data": {
    "first_name": {
      "type": "string",
      "__example__": "John"
    }
  }
}

• title (optional) - screen level attribute that is rendered in the top navigation bar.
• success - (optional, only applicable on terminal screens) - 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.
• refresh_on_back (optional, and only applicable for Flows with a Data Endpoint) - Defaults to false. This property defines whether to trigger a data exchange request with the WhatsApp Flows Data Endpoint when using 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 (example below).
• sensitive - (optional, only applicable for Flows version 5.1 and above) - Defaults to an empty array. When a Flow is completed, users will see a new message UI, which can be clicked and users will be able to view the responses submitted by them. This array contains the names of the fields in the screen that contain sensitive data, and should be hidden in the response summary for the consumers.

​

Additional information on refresh_on_back

1. User chooses an Appointment Type.
2. User selects Appointment Time.
3. User Confirms an appoinment.

​

refresh_on_back=false (default)

​

refresh_on_back=true

​

Flow Data Endpoint Request payload in case of refresh_on_back=true

​

Additional information on sensitive fields

​

Layout

1. type - the layout identifier that’s used in the template. In the current version of Flow JSON, there is only one layout available - "SingleColumnLayout" which represents a vertical flexbox container.
2. children - represents an array of components from the WhatsApp Flows Library.

​

Routing Model

1. Item Catalog => [Item Details Page]
2. Item Details Page => [Item Catalog, Checkout]
3. Checkout => []

​

When to define routes

​

How to define routes

​

Routing rules

1. Route cannot be the current screen, but the route can be “refreshed” for validation purposes.
2. If there is an edge between two screens, then the user can go back and forth between them using the BACK button.
3. Only forward routes should be specified in the routing model. For example, if you have specified an edge from Screen_A to Screen_B then you shouldn’t specify another edge from Screen_B to Screen_A.
4. Routes can be empty for a screen if there is no forward route from it.
5. There should be an entry screen in the routing model. A screen is eligible to be an entry screen if has no inbound edge.

6. All routes must end at the terminal screen.

​

Routing Model Flow JSON Example (Endpoint)

​

Properties

​

Static properties

​

This is a static heading

​

Dynamic properties

• string
• number
• boolean
• object
• array

• Form properties - "${form.field_name}" (data entered by the user in input fields). This is used to provide access to information that the user entered on the screen.
• Screen properties - "${data.field_name}" (data provided for the screen). This is used to provide access to information that is passed down by the server or the navigate action from the previous screen.

​

Nested Expressions

• Equality comparisons (==, !=)
• Math comparisons (<, <=, >, >=)
• Logical comparisons (&&, ||)
• String concatenation
• Math operations (+, -, /, %)

\{
  "type": "TextBody",
  "text": "`'This is an example for Ana\\`s house.'`"
}

​

Equality comparisons

\{
  "type": "TextBody",
  "text": "Your first name should be different from your last name.",
  "visible: "`${form.first_name} == ${form.last_name}`"
}

\{
  "type": "TextBody",
  "text": "You have not accepted the T&C!",
  "visible: "`${form.accept} != true`"
}

\{
  "type": "TextBody",
  "text": "You are 18!",
  "visible: "`${form.age} == 18`"
}

​

Math comparisons

\{
  "type": "TextBody",
  "text": "You are above 18!",
  "visible: "`${form.age} > 18`"
}

  {
  "type": "TextBody",
  "text": "You are above or at 18!",
  "visible: "`${form.age} >= 18`"
}

​

Logical comparisons

\{
  "type": "TextBody",
  "text": "You have accepted the T&C and subscribed for our newsletter!",
  "visible: "`${form.accept} && ${form.subscribe}`"
}

\{
  "type": "TextBody",
  "text": "You are above 18 and have accepted our T&C!",
  "visible: "`(${form.age} > 18) && ${form.accept}`"
}

\{
  "type": "TextBody",
  "text": "You provided at least your first or last name.",
  "visible: "`(${form.first_name} != '') || (${form.last_name} != '')`"
}

​

String Concatenation

\{
  "type": "TextBody"
  "text": "`'Hello ' ${form.first_name}`"
}

\{
  "type": "TextBody"
  "text": "`${form.first_name} ' you are ' ${form.age} ' years old.'`"
}

​

Math operations

\{
  "type": "TextBody",
  "text": "`'You were born on either ' (2024 - ${form.age}) ' or ' (2023 - ${form.age})`"
}

\{
  "type": "TextBody",
  "text": "`'The amount per person is: ' ${data.total} / ${form.group_size}`"
}

​

Declaring screen properties (No endpoint example)

​

Hello World

1. Inside MY_FIRST_SCREEN we declared a data field
2. Inside the data field we declared hello_world_text. This is the data that we expect to receive for screen.
   • hello_world_text follows the JSON Schema specification to declare the expected type, in this example it is a string.
   • __example__ field serves as mock data for the template, which is useful while you’re developing your template without WhatsApp Flows Data Endpoint integration. This field is mandatory.
3. In TextHeading we’ve referenced the data via dynamic data reference syntax. $ represents an object that came from the WhatsApp Flows Data Endpoint or navigate actions in case of Flow without endpoint. You can treat it as a screen state that was set after the response is received.
4. Property of the state can be accessed using the following pattern - "${data.property_name}"

​

Declaring screen properties (Endpoint powered example)

1. We’ve added data_api_version, routing_model and data_channel_uri to indicate that the flow is connected to server.
2. We’ve added data_api_version and routing_model to indicate that the flow is connected to server. data_channel_uri should also be added if the Flow JSON version is less than 3.0.
3. Flow expects to receive a payload from flow data server containing hello_world_text field.

​

Hello World

​

Forms and Form properties

<form>
  <label for="first_name">First name</label><br />
  <input type="text" id="first_name" name="first_name"><br />
  <label for="last_name">Last name</label><br />
  <input type="text" id="last_name" name="last_name">

  <input type="radio" id="html" name="fav_language" value="HTML">
  <label for="html">HTML</label><br />

  <input type="radio" id="css" name="fav_language" value="CSS">
  <label for="css">CSS</label><br />

  <input type="radio" id="javascript" name="fav_language" value="JavaScript">
  <label for="javascript">JavaScript</label>
</form>

​

First name

​

Second name

• Javascript
• CSS
• HTML

​

First name

​

Second name

• Javascript
• CSS
• HTML

​

Using Form properties

​

Passing data to the next screen:

\{
  "type": "Footer",
  "label": "Submit data",
  "on-click-action": {
    "name": "navigate",
    "next": { "type": "screen", "name": "NEXT_SCREEN" },
    "payload": {
      "name": "${form.first_name}",
      "lang": "${form.favourite_language}"
    }
  }
}

​

Submitting data to the server:

\{
  "type": "Footer",
  "label": "Submit data",
  "on-click-action": {
    "name": "data_exchange",
    "payload": {
      "name": "${form.first_name}",
      "lang": "${form.favourite_language}"
    }
  }
}

​

Building forms guidelines

• In order to build Forms in Flow JSON you need to use Form components then provide the name and children properties
• Children properties must be an array of Form components
• Each Form component has its own property model, however the name property is required in all of them

​

Form configuration

​

First name

​

Second name

​

First name

​

Second name

​

Global dynamic and form properties

${screen.<screen_name>.(form | data).<field-name>}

1. screen - global variable that gives access to screen storage
2. screen_name - name of the screen to refer
3. (form | data) - type of storage you want to reference - Form / Dynamic data
4. field-name - name of the field you want to reference

​

Where it can be used

1. Component properties that support dynamic data
2. Action payloads
3. Screen titles
4. Conditional components

​

Example 1 - Carrying data forward

"on-click-action": {
  "name": "navigate",
  "next": {
           "type": "screen",
           "name": "SCREEN_TWO"
          },
   "payload": {
      "field1": "${data.field_one}",
      "field2": "${form.field_two}"
    }
}

"on-click-action": {
  "name": "navigate",
  "next": {
           "type": "screen",
           "name": "SCREEN_TWO"
          },
   "payload": {}
}

\{
  "type": "TextBody",
  "text": "${screen.SCREEN_ONE.data.field1}"
}

​

Example 2 - No screen data declaration for global fields

​

Enter your name

​

(optional)

​

Example 3 - Forward references

1. SELECT_SERVICES screen references the data from SELECT_INSURANCE
2. When value from SELECT_INSURANCE screen is empty - we display You haven't selected any insurance type
3. When value is not empty, based on selected value - we display different text via Switch statement

​

Select insurance type

​

Actions

​

navigate action

​

When to use

​

Example

\{
  "type": "Footer",
  "label": "Continue",
  "on-click-action": {
    "name": "navigate",
    "next": { "type": "screen", "name": "NEXT_SCREEN" },
    "payload": {
      "name": "${form.first_name}",
      "lang": "${form.favourite_language}"
    }
  }
}

​

complete action

​

When to use

​

Example

\{
  "type": "Footer",
  "label": "Submit data",
  "on-click-action": {
    "name": "complete",
    "payload": {
      "discount_code": "${data.discount_code}",
      "items": "${form.selected_items}"
    }
  }
}

​

Example of flow using navigate and complete actions

​

Name

​

Second name

​

data_exchange action

​

When to use

​

Example

\{
  "type": "Footer",
  "label": "Submit data",
  "on-click-action": {
    "name": "data_exchange",
    "payload": {
      "discount_code": "${data.discount_code}",
      "items": "${form.selected_items}"
    }
  }
}

​

update_data action

​

When to use

1. Immediate Response Required: You need to update elements on the same screen in response to user inputs. In the provided example, selecting a country from the dropdown triggers an immediate update to the state dropdown. This ensures that users experience no delay in seeing relevant options, enhancing the responsiveness of the application.
2. Dynamic Data Handling: This action excels in scenarios where data relationships are dynamic yet predefined within the components data-source. In the example, each country object includes its related states, allowing the state dropdown to update seamlessly based on the country selected without additional data requests. This efficient handling of data reduces load times and server dependency.
3. Reusable Templates: Utilizing update_data promotes the reuse of flow components across different data contexts. The state dropdown in the example is a single component that is repopulated with different data depending on the country selected. This approach minimizes the need for multiple distinct templates, simplifying the application structure and reducing development effort.

​

Examples

​

RadioButtonsGroup Example

• USA
• Canada

​

open_url action

​

When to use

​

EmbeddedLink Example

\{
   "type": "EmbeddedLink",
   "text": "This is an external link.",
   "on-click-action": {
   "name": "open_url",
   "url": "https://www.whatsapp.com/"
   }
},

​

OptIn Example

\{
   "type": "OptIn",
   "label": "I agree to the terms.",
   "name": "T&Cs",
   "on-click-action": {
   "name": "open_url",
   "url": "https://www.whatsapp.com/"
   }
},

​

Components

​

Static Validation Errors

​

Limitations