WhatsApp Flows: A detail guide for dynamic WhatsApp flows

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 "$ " 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 \<key, value> object where key field name in component value field initial value type string, array< string > or dynamic init values="$ " error messages \<key, value> 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 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 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 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 create the flow on meta business manager 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 design the flow use meta's ui builder or json editor to add screens and components (text, inputs, lists, buttons) 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 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 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 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 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 create or open the bot in exochatbot ensure the whatsapp channel is configured and the number is integrated with the bot in the bot, go to workflow > under flows, open the node that will trigger the whatsapp form click add more on the node > navigate to whatsapp flows under bot prompts enter all the flow details in the "whatsapp flows" prompts (refer to the table below) and click save save the node for static forms, the mapping is complete for dynamic flows, additional middleware logic may be required in the exoflow connect app save the node 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/} store and use responses inside the chatbot create/select a variable in the select variable to store response field select the type as string on form submission, the full response json sent from meta will be saved in that variable you can reference values in downstream nodes, webhook payloads, or make decisions inside flows (e g , route to different nodes based on answers) 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