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 "${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 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="${data init values}" error messages \<key, value> object where key field name in component value error message type string or dynamic error messages= "${data 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 ${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