On this page, we will explore the different ways of sending a Flow to users.
All the API requests mentioned below are documented in the Flows API postman collection which you can use to make API requests and generate code in different languages.
To send a business initiated message with a Flow, you can create and send a message template with a WhatsApp Flow attached to it. We introduced a new button type called FLOW. Use this type to specify the Flow to be sent with the message template.
To send Flow message template you need to:
You can quickly build a Flow in the playground and pass the Flow JSON in the message template creation request. Or you can specify the ID or name of an already published Flow.
Below is an example request to create a message template with a Flow, see this page for full reference:
curl -i -X POST \ https://graph.facebook.com/v16.0/<waba-id>/message_templates \ -H 'Authorization: Bearer TOKEN' \ -H 'Content-Type: application/json' \ -d' { "name": "example_template_name", "language": "en_US", "category": "MARKETING", "components": [ { "type": "body", "text": "This is a flows as template demo" }, { "type": "BUTTONS", "buttons": [ { "type": "FLOW", "text": "Open flow!", "navigate_screen": "WELCOME_SCREEN", "flow_action": "navigate", "flow_id" : "<flow_id>", // or "flow_name" : "<flow_name>", // or "flow_json" : "{\"version\":\"5.0\",\"screens\":[{\"id\":\"WELCOME_SCREEN\",\"layout\":{\"type\":\"SingleColumnLayout\",\"children\":[{\"type\":\"TextHeading\",\"text\":\"Hello World\"},{\"type\":\"Footer\",\"label\":\"Complete\",\"on-click-action\":{\"name\":\"complete\",\"payload\":{}}}]},\"title\":\"Welcome\",\"terminal\":true,\"success\":true,\"data\":{}}]}" } ] } ] }'
Parameter | Description |
---|---|
buttons | |
↳ flow_id string |
The unique ID of the Flow. Cannot be used if flow_name or flow_json parameters are provided. Only one of these parameters is allowed.
|
↳ flow_name string |
The name of the Flow. Cannot be used if flow_id or flow_json parameters are provided. Only one of these parameters is allowed. Supported in Cloud API only. The Flow ID is stored in the message template, not the name, so changing the Flow name will not affect existing message templates.
|
↳ flow_json string |
The Flow JSON encoded as string with escaping. The Flow JSON specifies the content of the Flow.
Cannot be used if flow_id or flow_name parameters are provided. Only one of these parameters is allowed. Supported in Cloud API only.
|
↳ nagivate_screen string |
Required if flow_action is navigate .
The unique ID of the Screen in the Flow.
|
↳ flow_action string |
Either navigate or data_exchange .
(Default value: navigate ) |
Message templates can be created and sent in these languages.
{ "id": "<template-id>", "status": "PENDING", "category": "MARKETING" }
Ensure that your template passes all required reviews so that status
is APPROVED
instead of PENDING
.
Now you can send a message template with a Flow using the request below
curl -X POST \ 'https://graph.facebook.com/v16.0/FROM_PHONE_NUMBER_ID/messages' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "PHONE_NUMBER", "type": "template", "template": { "name": "TEMPLATE_NAME", "language": { "code": "LANGUAGE_AND_LOCALE_CODE" }, "components": [ { "type": "button", "sub_type": "flow", "index": "0", "parameters": [ { "type": "action", "action": { "flow_token": "FLOW_TOKEN", //optional, default is "unused" "flow_action_data": { ... } // optional, json object with the data payload for the first screen } } ] } ] } }'
{ "messaging_product": "whatsapp", "contacts": [ { "input": "<phone-number>", "wa_id": "<phone-number>" } ], "messages": [ { "id": "<message-id>" } ] }
You are able to send your WhatsApp Flow once you have created it. You can send a Message with a Flow in a user-initiated conversation using a Message with a Call To Action (CTA). You send this message either through the On-Prem client or Cloud API with information specific to the Flow. The Flow is triggered when the user taps the CTA button.
Go here to read more about message types, limits, and timing.
As mentioned earlier, a message with a Flow is not much different from other types of messages. It uses the existing APIs, which are described on the following pages:
To send a message with a Flow, we have introduced a new type of the Interactive Object named flow
with the following properties.
Parameter | Description | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
interactive object | The interactive message configuration | ||||||||||||||||||||||||||||
↳ type (required) string |
Value must be "flow" .
| ||||||||||||||||||||||||||||
↳ action (required) object |
|
*See Flow JSON reference for entry screen details.
Now let's consider what a message sending request might look like using Cloud API:
Sample Request
curl -X POST \ 'https://graph.facebook.com/v18.0/FROM_PHONE_NUMBER/messages' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "recipient_type": "individual", "messaging_product": "whatsapp", "to": "whatsapp-id", "type": "interactive", "interactive": { "type": "flow", "header": { "type": "text", "text": "Flow message header" }, "body": { "text": "Flow message body" }, "footer": { "text": "Flow message footer" }, "action": { "name": "flow", "parameters": { "flow_message_version": "3", "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.", "flow_name": "appointment_booking_v1", //or "flow_id": "123456", "flow_cta": "Book!", "flow_action": "navigate", "flow_action_payload": { "screen": "<SCREEN_NAME>", "data": { "product_name": "name", "product_description": "description", "product_price": 100 } } } } } }'
Sample Response
{ "contacts": [ { "Input": "+447385946746", "wa_id": "47385946746" } ], "messages": [ { "id": "gHTRETHRTHTRTH-av4Y" } ], "meta": { "api_status": "stable", "version": "2.44.0.27" } }