--- title: WhatsApp Flows: A detail guide for dynamic WhatsApp flows slug: messaging-apis/whatsapp-flows-a-detail-guide-for-dynamic-whatsapp-flows docTags: createdAt: 2025-10-06T15:13:12.076Z --- 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: 1. **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. 2. **Layouts**: These define how components are presented within a Flow, providing a structured look and feel. 3. **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: 1. User chooses an apponment type. 2. User selects available time. 3. 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: 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 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 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. 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: "$". 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** - "$" (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 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. | Attribute | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | init-values | \ object where
key - Field Name in Component
value - Field Initial Value
type - String, Array\< String > or Dynamic init-values="$" | | error-messages | \ object where
key - Field Name in Component
value - Error Message
type - String or Dynamic error-messages= "$" | 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. | Component | init-values data type | | ----------------- | --------------------- | | CheckboxGroup | Array of Strings | | RadioButtonsGroup | String | | Text Entry | String | | Dropdown | String | ### 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: | Flow JSON Reference | Description | Payload Type | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | data\_exchange | Sending Data to WhatsApp Flows Data Endpoint | Customizable JSON payload on data exchanges \{ \[key\:string]: any } | | 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. When flow\_message\_version is 3, the Flow initiation happens without a data channel | Static JSON payload | | complete | Accepts the termination parameters upon completion of a Flow | Static JSON payload | ### 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 - $ **When to use** 1. You need to transition to a new screen without requesting a Flow Data Endpoint. 2. For static Flows, it's mandatory to transition through this action. 3. 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** 1. Your Flow is static and doesn't use Flow Data Endpoint to submit the data. 2. 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** 1. You build a WhatsApp Flows Data Endpoint-powered Flow. 2. You want to submit the data from screen to your server and transition to the next screen. 3. You want to update the screen content based on a selected value. ## Using WhatsApp Flows on the Exotel Chatbot WhatsApp Flows (also called WhatsApp Forms) allow you to send interactive forms inside WhatsApp. Customers can fill details, browse options, book appointments, place orders, or provide feedback - all without leaving the conversation. ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/aq-LmPNU6tjxlcvyB_ypM-20260721-070917.png) On Exotel Chatbot, you can connect these forms to nodes in your bot journey. This guide explains: - What WhatsApp Flows are. - The difference between Static and Dynamic Flows. - How to create a Flow on Meta's WhatsApp Manager. - How to configure the Flow on Exotel Chatbot. - How to capture and use responses inside your bot. - Common troubleshooting steps. All flows must first be created in Meta's WhatsApp Business Manager → Flows section. ### Types of Flows: Static vs Dynamic Flows ### Static Flows Simple forms built fully in Meta's Flow Builder. No backend required. Great for surveys, lead capture, or sign-up forms. - Built in Meta's Flow Builder (choose Without Endpoint). - No backend or middleware required. - Supports all components except images. - Best for simple, one-way data collection. ### Dynamic Flows Advanced, backend-driven forms with real-time data exchange. Ideal for order management, scheduling, or personalized journeys. - Built for advanced use cases like product catalogs, payments, or scheduling. - Requires a backend endpoint (ExoFlow Connect) + encryption key pair. - Supports images, real-time validation, and conditional flows. - Managed by Exotel Developers (customers request setup, not self-serve today). - Dynamic requires you to set up an Endpoint - Mandatory. Think of Static flows like a fixed form, and Dynamic flows like a mini web app inside WhatsApp. ### Set up an Endpoint: ExoFlow Connect App (for Dynamic Forms) ExoFlow Connect is a middleware service that creates the Endpoint for you and space to write your Flow's logic. This generates a unique endpoint for each flow, automatically links it with your bot, and securely manages real-time data exchange with WhatsApp. To enable this, please reach out to your respective Account Manager for more details. Important context (Dynamic Forms): The Exotel middleware (ExoFlow Connect) that hosts dynamic Flow endpoints is an internal feature managed by Exotel Delivery Developers. Customers must reach out to their Exotel Delivery Team / Account Manager for provisioning, endpoint setup, key management, and any middleware logic. This guide assumes that Exotel Developers will perform Dynamic Flow endpoint work on behalf of the customer. This involves additional cost to the system. ### Create and Configure WhatsApp Flow on the Chatbot Now, let us understand how to create and configure a WhatsApp Flow on the Chatbot. This can be divided into 2 steps: 1. Create the Flow on Meta Business Manager 2. Configure the WhatsApp Flow on the Chatbot (this needs to be done by the Exotel Team) ### Prerequisites Before you begin, ensure you have: - Access to Exotel Chatbot with permissions to create/edit workflows - You can create your first bot and test the flows here - [Exotel Chatbot Platform](https://bots.exotel.com/bot/chat/bots/) - A WhatsApp number integrated with WhatsApp API (Onboarded with Exotel preferred). - Access to Meta Business Manager (for Flow creation). - (For Dynamic flows) Support from Exotel Developers to enable ExoFlow Connect App. ### Step A - Create the Flow on Meta Business Manager ### Create the Flow on Meta's Flow Builder - For Static Flow - This can be created by the business, CX, or the Exotel Delivery Team as per the required use case. - For Dynamic Flow - This needs to be done by the Exotel Team as it requires providing dynamic details in the Form while creating it. - Go to WhatsApp Manager → Account Tools → Flows → Start Building Flows. - Select: - Without Endpoint → Static flow. - With Endpoint → Dynamic flow. ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/hdpfAggeMS4NH0KMSKkIR-20260721-070920.png) ### Design the Flow - Use Meta's UI builder or JSON editor to add screens and components (text, inputs, lists, buttons). ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/4u7cslfbUo-LdNRWlptaD-20260721-070857.png) Or - To simplify: - You can start from Meta's Templates section → Marketing → Flows - To quickly create forms. - This will also create a linked Flow in the Flows section for reuse. - Click Run Preview to test. ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/gyFJ9-yO0PZcxZ_ftKFLV-20260721-070924.png) ### Endpoint Setup on Meta console - Required Only for Dynamic Flow To be handled by Exotel Developers: - Set Endpoint URL (from ExoFlow Connect). - Upload Public Key for secure data exchange. - Connect Meta App to your Flow ID + WABA ID. - Run Health Check to validate the connection. ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/18u2m2BKUVxMtL8S1bcBi-20260721-070936.png) After the Flow is created, you will need these details to Configure the Flow on the Chatbot Console: - Flow ID - WABA ID - Flow Mode (Status): - Draft - Draft if the Flow is still being built or tested. - Published - Use Published if it's live on WhatsApp. ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/M-XBZGAftR0JdMaahaUyA-20260721-070905.png) - Flow Action: - Navigate (for Static & Dynamic) - Data Exchange (only for Dynamic) - Screen Name: The name/id of the screen that you want to open on the Flows button click. Refer to the image below ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/5c871Jkc_R7x-t4ho9WfA-20260721-070932.png) ### Step B - Configure Flow in Exotel Chatbot Console *Note: These configuration steps in Exotel Chatbot need to be performed by the Exotel Team (Delivery Developers/admins) for versioning reasons. The steps below are a reference from version 8, and they may vary for some customer based on their versions.* 1. Create or open the Bot in ExoChatbot. 2. Ensure the WhatsApp channel is configured and the number is integrated with the bot. 3. In the bot, go to Workflow > under Flows, open the node that will trigger the WhatsApp Form. 4. Click Add More on the node > navigate to WhatsApp Flows under Bot Prompts. ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/EAc5bvJ0t8fGYHyhjNeGk-20260721-070908.png) 5. Enter all the Flow details in the "WhatsApp Flows" Prompts (refer to the table below) and click Save. ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/cCaarkEb2Vcf86u5B8oML-20260721-070928.png) 6. Save the node. For Static forms, the mapping is complete. For Dynamic flows, additional middleware logic may be required in the ExoFlow Connect App. 7. Save the node. 8. Test the flow in a WhatsApp conversation. ### Field-by-field Explanation This explains what to enter on the WhatsApp Flows prompt. | Field | Description | Example / Notes | | -------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | Language | The language of the flow copy. Each language needs a separate Flow ID and entry. | English (default); If you need 3 languages, upload 3 flows. | | Header | Optional header text displayed above the form. | Short title or brand line (optional). | | Body | Mandatory. Message text shown above the Form CTA. | "Please fill this short form to book your slot." | | Footer | Optional footer text beneath the form. | Legal or brief instruction. | | Flow ID | Numeric unique Flow ID from Meta (WhatsApp Manager → Flows). | e.g., 1234567890 | | Flow Type | Static or Dynamic. It must match how the flow was created on Meta. | Static - Flow Action auto-set to Navigate. Dynamic - action editable. | | Flow Mode | Draft or Published. If mode mismatches from Meta, the message will fail. | Use Published for live usage. | | Screen Name | ID of the first screen to open on flow trigger (found in Meta preview/JSON). | E.g - start\_screen | | Button Name | Text to display on CTA button. Max 20 characters, no emojis. | E.g - Signup | | Flow Action | Navigate or Data Exchange. Static only supports Navigate. Dynamic flows can be Navigate or Data Exchange. | Choose per JSON metadata. | | Flow Data | (Optional) JSON object used to pre-fill fields on the first screen. Must be a non-empty object if provided. | \{/name/} | | Store Response in Variable | Create/select a variable to store the entire form response payload for further use in the bot. | The response will be available in bot webhooks and variables. | *Note: The Chatbot console enforces the Flow Type / Action rules, if you configure a static flow with a Dynamic action, the message will fail.* ### How to pass existing data (pre-fill) - Use the Flow Data field to pass all the required details to the WhatsApp Form using the Chatbot Variables. Example: - Use bot variables using " \{ } " and select the variable from the dropdown to pass the values. Example: \{/name/} ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/F4SRCfRbg3w9vnCPK8SFK-20260721-070901.png) ### Store and use responses inside the Chatbot 1. Create/select a variable in the Select Variable to Store Response field. 2. Select the type as String. 3. On Form submission, the full response JSON sent from Meta will be saved in that variable. 4. You can reference values in downstream nodes, webhook payloads, or make decisions inside flows (e.g., route to different nodes based on answers). ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/aIKFiQ8MHODlGTDBfrR6L-20260721-070912.png) ### Testing Checklist - Preview flow in Meta before publishing. - For Dynamic flows, confirm Health Check passes. - In Exotel Chatbot, test sending the flow message. - Verify: - CTA button appears. - Pre-filled values work. Response is captured in your variable. ### Common Errors & Fixes - Flow Mode mismatch: Ensure you configure the correct flow mode. Set both the Meta & Chatbot node to "Draft" or "Published" based on the required setup. - Static vs Dynamic mismatch: Ensure you configure the correct flow type. - Empty variable after submission: Check "Store Response in Variable" is enabled. - Health check fails (Dynamic): The Endpoint that hosts the Dynamic Logic for your form is having some errors. - If the Endpoint is owned by the customer: Check and fix the error if the endpoint and retry again. - If the Endpoint is owned by Exotel Middlware: Raise to your respective Account Manager (endpoint setup needed). ### Best Practices - Keep your form short, with minimal typing for users. - Use pre-filled data (via Flow Data JSON) to reduce friction. - For multilingual bots, create one Flow per language. - Monitor performance metrics (delivery, clicks, completions, drop-offs). - For business-critical flows, ask Exotel Developers to enable extra API logging. ### Support - For Static flows: You can set up directly via Meta + Exotel Chatbot. - For Dynamic flows: Please reach out to your Account Manager.