WhatsApp Flows Integration with Exotel

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 with flows, you can present simple input forms (in order to schedule an appointment, for example) create workflows that guide users through multiple screens (for ordering products, for example) create endpoints that exchange data across screens to enable more complex interactions (such as guiding a user through a process with multiple potential outcomes) an example of appointment booking flow is shown below in this documentation, you'll find easy to follow guides for flows integration, api references, explanations of common terminology, and much more leveraging flows flows is built for form based use cases you can create flows to achieve a range of tasks with your customers, including lead generation appointment booking registration, sign up, and sign in customer support and feedback and many more how are flows configured and used? flows are linked from a call to action (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 flows can be attached and sent as business initiated messages (template messages), as well as standard messages (session messages) lifecycle of a flow on meta dashboard flows on the whatsapp business platform undergo various states, each signifying different functionalities and restrictions here's a breakdown business set flow states these states are the default states through which the flow passes draft state a flow is actively being modified capabilities can be sent for testing; can be deleted if no longer needed next states deleted (if in draft state), published published state ready for deployment to real users capabilities cannot be modified or deleted to maintain consistency actions create a new flow based on the existing one (using clone flow id) or deprecate it using the /deprecated api call next states deprecated, throttled deprecated state no longer sent to real users; still visible on users' devices actions none (terminal state) system set flow states these states are internal states set by the system businesses don’t have any control on these states throttled state flow limited to 10 messages/hour due to endpoint issues actions open a support case via the support portal for assistance next states published, deprecated, blocked (upon further deterioration) blocked state flow cannot be sent or opened due to severe endpoint issues actions none (terminal state) understanding these states is crucial for developers, ensuring smooth interactions between businesses and customers on whatsapp steps to be followed pre requisites the whatsapp business number should be onboarded to the exotel console the whatsapp number should be hosted either on on premise or cloud api you have configured the webhook for the phone number to receive the callbacks an example webhook is shown in the figure below in case you are using our whatsapp apis, you need to integrate the updated flows request and response for the send message api (for sending new type of session message and template message) with the new callback formats please refer to the developer documentation here note you can now configure a chatbot and start using the whatsapp flow feature to send automated flow messages create flow there are 2 ways to create whatsapp flows use whatsapp manager use the flows api we are currently using the first approach above to create flows whatsapp manager contains two options to create flows inclusion of flows while creating message templates using flows builder under the account tools section option 1 inclusion of flows while creating message templates step 1 create your flow template login to your exotel account and click on the whatsapp option from the left side menu navigate to the whatsapp flows option from the left side menu and click on meta dashboard link for the template with flows section it will open the whatsapp business manager portal in the new tab, search and open your valid waba account from top right corner in the whatsapp manager of your whatsapp business account, select account tools on the left side menu and then click flows click on the create template button and select the category as marketing and the type as form fill the basic information details for the template, the steps remain the same as the exotel console like template name, and select language click on continue fill the other template details like header, body, footer with samples and navigate to the buttons section where you need to provide the button text and select the type of the form (you can select the relevant use case to get a pre filled form) and click on create it will open an ui and within this ui you can create flows using the drag and drop form editor, without having to write any flow json code yourself after you create and submit a message template with a flow attached using this ui, you can send it to your users once it is approved by meta below is the reference video for a lead generation use case form with the template which will help you! creating flows in message template creation step 2 sync the exotel template console go to the template management section on the messaging console select the same waba from the dropdown on which this template was created click on the sync icon to update the newly created template on our console to start using the template option 2 using flows builder under the account tools section in this section, we'll walk you through creating your very first flow at the end of this tutorial, you'll have a completed and published demonstration flow, ready to be sent to other whatsapp users to do this, we'll use the flows builder ui in whatsapp manager remember, if you haven't already gone through the prerequisites, be sure to read through it before starting this guide step 1 create your flow login to your exotel account and click on the whatsapp option from the left side menu navigate to the whatsapp flows option from the left side menu and click on meta dashboard link for the free form message it will open the whatsapp business manager portal in the new tab, search and open your valid waba account from top right corner in the whatsapp manager of your whatsapp business account, select account tools on the left side menu and then click flows on the top right of the page, click the button titled create flow a dialog will open where you can enter some details about your flow what do these fields mean? name the name is a unique identifier for your flow across your business account generally, try to choose a name that describes your flow and its purpose in this case, enter my first flow categories choose any categories that match the purpose of your flow from the list of options if none of the categories listed make sense for your flow, just check "other" in our case, choose "other" template whatsapp flows has a few template flows pre created to make it easier for you to get started if any of the templates are similar to what you'd like your flow to do, use a template as a starting point for your flow or leave this blank step 2 build your flow json to help you move quickly, here's a very simple demonstration ("hello world") flow you can edit it here and then copy and paste it over to the flows builder ui when you're ready (you can also preview it inside the builder ) once you've pasted the json into the flows builder ui, click run to preview the flow if you're happy with the demonstrated flow, click save { "version" "2 1", "screens" \[ { "id" "hello world", "title" "hello world", "terminal" true, "layout" { "type" "singlecolumnlayout", "children" \[ { "type" "form", "name" "form", "children" \[ { "type" "textheading", "text" "hello world" }, { "type" "textbody", "text" "welcome to whatsapp flows" }, { "type" "footer", "label" "complete", "on click action" { "name" "complete", "payload" {} } } ] } ] } } ] } step 3 test your flow the easiest way to test a flow is by using the interactive preview option which simulates the real experience you can click on the flow's green complete button to see the flow in action step 4 publish your flow when you first created your flow, it entered the draft state and as you edited and saved the modified flow json content, it remained in the draft state you are able to send the flow while it's in the draft state, but only for testing purposes if you want to send the flow to a larger audience, you'll need to publish the flow note remember, once a flow has been published it can no longer be modified see flow status lifecycle for more information on the different flow states to publish your flow, open the menu to the right of the save button and click publish once published, the flow can be sent to anyone! what's next? congratulations! ? your flow can now be sent to real users to learn how you can actually send your flow, read the next section to send the flows build data channel setup and consume webhook notifications you will have to set up the webhook to receive the whatsapp flows callbacks for your whatsapp phone number setup the webhook you can set up the webhook for whatsapp phone numbers from the exotel messaging console go to the webhooks section and navigate to the phone number click on the edit icon on the right hand side of the table paste your callback url and click on save (this will take 10 15 mins to be active) consume the webhook notifications upon flow completion, a response message will be sent to the whatsapp chat you will receive it in the same way as you receive all other messages from the user via message webhook response json field will contain flow specific data as you have configured the webhook for the number on the exotel message console, you will receive the callbacks with the flow details as the sample response present below { "whatsapp" { "messages" \[ { "callback type" "incoming message", "sid" "4743da54fb78365cb640caab9b2f17al", "from" "+918871206831", "to" "+912248931479", "timestamp" "2023 10 21t12 35 00 +05 30 ", "profile name" "javed", "content" { "type" "interactive", "context" { "sid" "f317c729f41c3e25d00d0b51c6ac17am" }, "interactive" { "type" "nfm reply", "nfm reply" { "body" "sent", "name" "galaxy message", "response json" "{\\"terms and conditions\\"\ true,\\"flow token\\" \\"flows builder 97dca41f\\",\\"vehicle number\\" \\"74785\\",\\"name\\" \\"javed ansari\\",\\"phone number\\" \\"918111101011\\",\\"email\\" \\" abcd\@gmail com \\",\\"cover type\\" \\"0\\"}" } } } } ] } } sending a flow you are able to send your whatsapp flow once you have created it on this page, we will explore the existing apis for sending a message, as well as the modifications required for sending a message with a flow there are two types of messages with which you can attach a flow template messages from the business in reply to user initiated conversations details of how a flow can be attached to these message types is explained below template messages from the business you can send a template message with a whatsapp flow only the approved templates with the flow buttons can be sent to the users via campaigns or apis we have introduced a new button type called flow use this type to specify the flow to be sent with the template message please follow the steps below to send a flow via template messages step 1 create and sync the template with flows given that the template is created on the meta dashboard and you have synced the templates on the exotel dashboard you can refer to this section to complete this step step 1 create your flow template step 2 send the template via exotel campaign console let us see how to send a campaign with the template flows cta button login to the exotel dashboard and navigate to the campaign console from the left sided menu select whatsapp and click on the create button from the top right corner provide the campaign name, select the correct waba id where this new template with flow button was created on the meta dashboard select the phone number, and attach the audience list details to the campaign to whom you would want to send the message and click on next select the correct template name which has the ‘form’ present in the button and click on next templates with a flow attached to them will be shown as ‘marketing form’ to differentiate the flows templates with the other marketing category templates (see below) review the selected template with the flow button with the preview screen present on the rhs on the third step and click on next schedule your campaign as per your requirement and click on create campaign button to send the template messages alternative to step 2 send the template message via api please follow step 1 for creating the template with flow on the meta dashboard you can then use the send template message api (business message) to send the flow message via api you need to configure the endpoint in a similar way how you use to send other messages post https //\<your api key> \<your api token>\<subdomain>/v2/accounts/\<your sid>/messages you can get the api credentials and details from your exotel account under the api credentials section following are the key parameters related to flow that you need to pass (along with the other mandatory/optional parameters in the send template message api) postman api collection to and from number template name language code flow token optional (this can be passed any static value) property type description buttons flow id string id of a flow buttons navigate screen string flows json screen name required if flow action is navigate buttons flow action enum navigate or data exchange default value is navigate hit the send message api to send and test your template message containing the flow in reply to user initiated conversations you can send a message with a flow in a user initiated conversation using a message with a call to action (cta) you can send this message either through send message api with information specific to the flow the flow is triggered when the user clicks on the cta button please follow the steps below to send a flow via user initiated conversation message types step 1 create the json flow on meta given that the required json flow is created on the meta dashboard and you have successfully published the flow you are good to go you can refer to this section to complete this step create free form flows step 2 send the json flow you can use the send template message api (user initiated message) to send the flow message via api you need to configure the endpoint in a similar way how you use to send other messages post https //\<your api key> \<your api token>\<subdomain>/v2/accounts/\<your sid>/messages you can get the api credentials and details from your exotel account under the api credentials section following are the key parameters related to flow that you need to pass (along with the other mandatory/optional parameters in the send message api) postman api collection to and from number content type interactive header, body and footer text for the message below are more details action > name flow message version flow id flow token flow cta flow action flow action payload > screen name property type description interactive type string value must be flow interactive action name string value must be flow for cloud api number and galaxy message for on premise number interactive action parameters mode string the flow can be in either draft or published mode published is the default value for this field interactive action parameters flow message version string value must be 3 interactive action parameters flow token string flow token that is generated by the business to serve as an identifier interactive action parameters flow id string unique flow id of the flow provided by whatsapp interactive action parameters flow cta string text on the cta button for example "signup" character limit 20 characters (no emoji) interactive action parameters flow action string navigate or data exchange default value is navigate interactive action parameters flow action payload string required if flow action is navigate should be omitted otherwise interactive action parameters flow action payload screen string the screen name of the first screen interactive action parameters flow action payload data string optional the input data for the first screen of the flow must be a non empty object flow token copy it from the meta dashboard from the flows section, click on the manage option on the right hand side it will open the modal which will provide you the flow token and other details for that published flow configure the api payload and hit the send message api to send and test your message make sure an active conversation is present to send a free form session message note you can also configure a chatbot and send an automated reply with flow cta button using the chatbot ui please contact your csm for more details to understand how to configure and use the chatbot with your whatsapp number currently, we support static flows in whatsapp i e flows where the questions shown in the subsequent flow screens are not dependent on the data provided in the previous screens if your use case is around dynamic flows, e g displaying the available seats for a movie show is dependent on the date and time of the show selected, please contact hello\@exotel com with the subject of the email as mentioned below, and we’ll be happy to assist you