Flows is a feature of the WhatsApp Business Platform that allows you to swiftly develop and deploy native, task-centric workflows on WhatsApp. This results in enhanced interactions between customers and businesses.
With WhatsApp Flows businesses can design, build and customize their own journeys, which can make chatbot and AI agent solutions better, as well as offer end-to-end experiences.
For users, Flows can improve interactions with businesses on WhatsApp, leading to better task completion and fewer drop offs than alternative channels.
For businesses, Flows can improve engagement and completion rates, resulting in improved business outcomes.
Flows are linked from a CTA in a message. Flows are composed of:
Screens: When tapping on the Flows CTA in a message, the user will access the initial screen of the Flow. The user can then interact with the Flow to move through multiple screens until completion.
Layouts: These define how components are presented within a Flow, providing a structured look and feel.
Components: You can use components to display information, and to create input fields for your users. You can display information with Text, Images, and Embedded links. You can create input fields for your users to complete using Text Inputs, Dropdowns, Checkboxes, Radio Buttons, Opt-in, and Date Pickers.
Lifecycle of a Flow
Flows can exist in a variety of states during their lifetime, with each state conveying different requirements, abilities, and limitations. This article outlines the different states that exist, how a Flow transitions into each state, and what each state means for developers building and sending Flows.
Draft
When a Flow is initially created, it enters the "Draft" state which indicates that the Flow is actively being modified.
While in the Draft state, the Flow is only able to be sent for testing, and also has the ability to be fully deleted if no longer needed.
Deleted
Technically this is not a "state" of a Flow because this represents a Flow that no longer exists. However, it's important to note that Flows may be deleted, but only if they are in the Draft state.
Published
Once a Flow is ready to be sent, it transitions from the Draft state to the Published state. This allows it to be sent to real users rather than just for testing.
Now that the Flow is visible to real users, it can no longer be modified or deleted. This is to prevent inconsistency from Flows changing over time (or errors from missing Flows).
Instead, alternatives exist for these actions:
Since you cannot modify the Flow, create a new Flow that clones the existing one (using the clone_flow_id field)
Since you cannot delete the Flow, deprecate it instead using the /deprecate API call.
Throttled
In the case that WhatsApp monitoring detects that the endpoint for your Flow is unhealthy, it transitions the Flow to a Throttled state. A throttled Flow can still be opened and sent, however sending is limited to 10 messages per hour.
If your Flow enters the Throttled state and you need help diagnosing the issue, start by opening a support case using the Support Portal.
If WhatsApp monitoring detects an improvement in the health of the Flow's endpoint, the Flow will be transitioned out of the Throttled state and back into the Published state.
Blocked
If a Flow has entered the Throttled state and WhatsApp monitoring detects that the health of the provided endpoint has deteriorated even further, the Flow will be transitioned into the Blocked state. This is to prevent a degraded user experience for WhatsApp Flows.
While in the Blocked state, the Flow cannot be sent by the business and cannot be opened by users. WhatsApp monitoring will continue to check the health of the endpoint, and upon improvement the Flow will be transitioned back to Throttled and then to Published state.
Flow JSON
Flow JSON enables businesses to create workflows in WhatsApp by accessing the features of WhatsApp Flows using a custom JSON object.
These workflows are initiated and run entirely inside WhatsApp. It can include multiple screens, data flows, and response messages.
Flow JSON defines the following:
Screen
Layout
Routing Model
Components
Forms
Actions
Top-level Flow JSON Properties
Flow JSON has several required and optional properties that are used in the process of compilation and validation of the Flow.
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 the 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.
Screens
Screens are the main unit of a Flow. Each screen represents a single node in the state machine you define.
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.
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.
title (optional) - screen level attribute that is rendered in the top navigation bar.
refresh_on_back (optional) - By default, it is always set to false. This property defines whenever the Flow needs to trigger a data exchange call with WhatsApp Flows Data Endpoint when clicking on the back button on a screen. The property is useful when you need to reevaluate the screen data when user returns to the screen.
Additional information on refresh_on_back
Given a simple Flow example:
User chooses an apponment type.
User selects available time.
User confirms an appoinment.
The user can go back to re-select an appoinment time. Based on the value of refresh_on_back, the behavior of the Flow will be different.
refresh_on_back=false (default)
If refresh_on_back=false when the user goes back to the Appointment Time screen, the Flow will not request the Flow Data Endpoint and the user will see the previously selected value. This is the preferred behavior in most cases, but if you need to revalidate the data for the screen, consider setting refresh_on_back=true to allow the Flow Data Endpoint to provide updated data for the screen.
refresh_on_back=true
As described above, if the value is set to true, when the user goes back to Appointment Time screen, the Flow will re-request a Flow Data endpoint to provide updated data for the screen
Layout
Layout represents screen UI Content. It can be predefined by the WhatsApp Flows team, or the business can use empty containers and build custom experience using the WhatsApp Flows Library.
Layout has the following properties:
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.
children - represents an array of components from the WhatsApp Flows Library.
Routing Model
Routing model configuration is needed only when you use an Endpoint to power your Flow.
You can define the routing model, which is a directed graph, as each screen can go to multiple other screens. There can be up to a maximum of 10 "branches", or connections, within the routing model.
Routing rules
Route cannot be the current screen, but the route can be "refreshed" for validation purposes.
If there is an edge between two screens, then the user can go back and forth between them using the BACK button.
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.
Routes can be empty for a screen if there is no forward route from it.
All routes must end at the terminal screen.
Properties
Properties can be static or dynamic. In Flow JSON the property is static if it is not a type binded to a data or form object.
Static properties
Static properties are simple. You set static properties once and they never change. Here is an example (see text and label properties of TextHeading and Footer components). Static properties is the simplest way to start building your Flow. You can always replace them later with dynamic content.
Dynamic properties
Dynamic properties enables you to set the content dynamically based on the server / screen data via the dynamic data reference mechanism, like so: "${data.username}". If you attempt to use the dynamic and static variant of the property together, you will get a compilation error. The dynamic data reference mechanism works with the following data types:
string
number
boolean
object
array
You can dynamically reference these data types in all the components of Flow JSON. There are two types of dynamic properties:
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.
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
Initial values of inputs can be initiased using init-values property. error-messages property allows you to set custom error for input. This is useful when you use Flow Data Endpoint to receive user data and you want to indicate that certain fields are incorrect.
You set init-values by specifying the field name in the respective component, then mapping it to your desired value.
The data type for init-values must match that of the component as outlined below.
Actions
Flow JSON provides a generic way to trigger asynchronous actions handled by a client through interactive UI elements. A limited set of actions are described below:
navigate action
This action is a primary way to navigate between the screens on the Flow. The data that's passed as payload of this action will be available on the next screen through dynamic data referencing - ${data.field_name}
When to use
You need to transition to a new screen without requesting a Flow Data Endpoint.
For static Flows, it's mandatory to transition through this action.
For endpoint powered Flows, it's optional to use this action.
complete action
Terminates the Flow and sends the response message to the chat thread. The business will receive the termination message bubble on the webhook, together with the flow_token and all of the other parameters from the payload. More information can be found here.
When to use
Your Flow is static and doesn't use Flow Data Endpoint to submit the data.
Use this action on terminal screen as a last interaction of the user. Once triggered, the Flow will be terminated and entered data will be submitted via webhook.
data_exchange action
Sends data to WhatsApp Flows Data Endpoint.
When to use
You build a WhatsApp Flows Data Endpoint-powered Flow.
You want to submit the data from screen to your server and transition to the next screen.
You want to update the screen content based on a selected value.