Skip to contentSkip to navigationSkip to topbar
Page toolsOn this page
Looking for more inspiration?Visit the

whatsapp/flows



Overview

overview page anchor

Flows allow you to create an in-app, multi-screen experience that a user receives and submits all within WhatsApp.

A business sends a Flow as part of an approved Content Template. The templated message contains a button to open the attached Flow in the WhatsApp UI. Within the Flow, you can include text, images, and several input components. End users respond with single-choice, multi-choice, toggle, short-text, long-text, and date-picker inputs.

whatsapp/flows versus twilio/flows

whatsappflows-versus-twilioflows page anchor

If you build your Flows in WhatsApp, use Flows outside of an approved template, or use endpoint functionality, you'll need to use the whatsapp/flows content type. To do this, create your Flows in the Meta UI and send using the Twilio Content API. Compare with twilio/flows that you create with the Twilio Content Template Builder.

(warning)

Flows limitations

Flows aren't designed to transmit HIPAA Eligible Service or PCI data. Don't use them in workflows that require HIPAA or PCI compliance.

If you need to transmit sensitive information, use Message Redaction. Message Redaction isn't yet compatible with Studio, Proxy Service, or Functions. Don't send Flows that contain sensitive information through these products or services.

Supported options for end users

supported-options-for-end-users page anchor

WhatsApp


Twilio Demo chat showing a response with a helpful link and notification.
Survey form with questions on finding method and favorite number, includes options and a complete button.

To create Flows with Meta, you'll need the following:

You can create a Flow with the WhatsApp Manager UI or programmatically with Meta's Flow API.

Tip: Use the Flow playground in the Meta developer docs(link takes you to an external page) to preview and configure your Flow. You can copy the JSON for use with either the WhatsApp Manager UI or the the Flows API below.

WhatsApp ManagerFlow API
  1. Follow the steps to open WhatsApp Manager(link takes you to an external page).
  2. In the Account Tools menu, click Flows.
  3. Click Create Flow.
  4. Follow the steps to create a new Flow(link takes you to an external page). Record the id of the first screen that you want to display.
  5. To publish your new Flow, click Publish.
  6. In the Account Tools menu, click Flows.
  7. Copy the Flow ID of the Flow that you've just created.

Attach a Flow to a whatsapp/flows Content Template

attach-a-flow-to-a-whatsappflows-content-template page anchor

To send a Flow that you made with Meta, you need to create a whatsapp/flows Content Template with the Flow's ID using the Twilio Content API.

From the creation steps above, ensure you've recorded the following values:

  • The unique ID of the Flow
  • The ID of the first screen (page) of the Flow

You'll need these for the call to the Content API to create the whatsapp/flow Content Template.

Your call to the Content API must contain the following parameters to create a whatsapp/flows Content Template.

ParameterTypeRequiredVariable supportDescription
bodystringYesYesText of the templated message that launches the Flow. Maximum length: 1,024 characters
subtitlestringNoNoOptional subtitle shown in the message footer. Maximum length: 80 characters
media_urlstringNoYesMedia included in the initial Flow message. Supports .png, .jpeg, .mp4, and .pdf. The domain must be static; the path can be a variable.
flow_idstringYesNo (approved templates) Yes (in-session without approval)Identifier for the Flow in WhatsApp.
flow_tokenstringNoYes (must be a variable)Unique identifier for the specific Flow interaction. Provide a new value for each send request.
flow_first_page_idstringNoNoIdentifier of the first page to display in the Flow interaction.
is_flow_first_page_endpointBooleanNoNoSet to true if an endpoint determines the first page. Defaults to false.

Create and submit a whatsapp/flows Content Template for approval

create-and-submit-a-whatsappflows-content-template-for-approval page anchor
Content Templates API - Create a WhatsApp Flow TemplateLink to code sample: Content Templates API - Create a WhatsApp Flow Template
1
curl -X POST 'https://content.twilio.com/v1/Content' \
2
-H 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4
-d '{
5
"friendly_name": "info_flow",
6
"language": "en","variables": {
7
"1": "abcd1234"
8
},
9
"types": {
10
"whatsapp/flows": {
11
"body": "Please take five minutes to answer this survey",
12
"button_text": "Begin survey",
13
"flow_id": "1232445823264765",
14
"flow_token": "{{1}}",
15
"flow_first_page_id": "QUESTION_ONE"
16
}
17
}
18
}'

Output

1
{
2
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
"date_created": "2025-09-12T23:49:53Z",
4
"date_updated": "2025-09-12T23:49:53Z",
5
"friendly_name": "info_flow",
6
"language": "en",
7
"links": {
8
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp",
9
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests"
10
},
11
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
"types": {
13
"whatsapp/flows": {
14
"body": "Please take five minutes to answer this survey",
15
"button_text": "Begin survey",
16
"flow_first_page_id": "QUESTION_ONE",
17
"flow_id": "1232445823264765",
18
"flow_token": "{{1}}",
19
"is_flow_first_page_endpoint": false,
20
"media_url": null,
21
"subtitle": null
22
}
23
},
24
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
25
"variables": {
26
"1": "abcd1234"
27
}
28
}

Create a WhatsApp approval request for a whatsapp/flows Content Template

create-a-whatsapp-approval-request-for-a-whatsappflows-content-template page anchor

After creating your whatsapp/flows Content Template, you'll need to send it for WhatsApp approval before sending it to your users outside of a messaging window.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createApprovalCreate() {
11
const approvalCreate = await client.content.v1
12
.contents("HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.approvalCreate.create({
14
name: "my_whatsapp_flow_template",
15
category: "MARKETING",
16
});
17
18
console.log(approvalCreate.name);
19
}
20
21
createApprovalCreate();

Response

Note about this response
1
{
2
"name": "my_whatsapp_flow_template",
3
"category": "MARKETING",
4
"content_type": "twilio/location",
5
"status": "unsubmitted",
6
"rejection_reason": "",
7
"allow_category_change": true
8
}

Fetch an approval status for a whatsapp/flows Content Template

fetch-an-approval-status-for-a-whatsappflows-content-template page anchor

You can check the status of a Content Template submitted for WhatsApp approval:

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function listContentAndApprovals() {
11
const contentAndApprovals = await client.content.v1.contentAndApprovals.list({
12
limit: 20,
13
});
14
15
contentAndApprovals.forEach((c) => console.log(c.dateCreated));
16
}
17
18
listContentAndApprovals();

Response

Note about this response
1
{
2
"contents": [],
3
"meta": {
4
"page": 0,
5
"page_size": 10,
6
"first_page_url": "https://content.twilio.com/v1/ContentAndApprovals?PageSize=10&Page=0",
7
"previous_page_url": null,
8
"next_page_url": null,
9
"url": "https://content.twilio.com/v1/ContentAndApprovals?PageSize=10&Page=0",
10
"key": "contents"
11
}
12
}

Send your whatsapp/flows Content Template

send-your-whatsappflows-content-template page anchor

Sending a whatsapp/flows Content Template is the same process as sending other Content Templates using the Programmable Messaging APIs. For detailed steps, see Send templates created with the Content Template Builder.

Send a WhatsApp Flow Content Template messageLink to code sample: Send a WhatsApp Flow Content Template message
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createMessage() {
11
const message = await client.messages.create({
12
contentSid: "HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13
from: "whatsapp:+14155238886",
14
to: "whatsapp:+15017122661",
15
});
16
17
console.log(message.sid);
18
}
19
20
createMessage();

Response

Note about this response
1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"api_version": "2010-04-01",
4
"body": "Hello! 👍",
5
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
"direction": "outbound-api",
9
"error_code": null,
10
"error_message": null,
11
"from": "whatsapp:+14155238886",
12
"num_media": "0",
13
"num_segments": "1",
14
"price": null,
15
"price_unit": null,
16
"messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17
"sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
"status": "queued",
19
"subresource_uris": {
20
"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
},
22
"to": "whatsapp:+15017122661",
23
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24
}

Receive a Flow submission

receive-a-flow-submission page anchor

When a user submits a Flow in WhatsApp, Twilio sends a webhook request to the messaging endpoint that you've configured on your WhatsApp sender. The InteractiveData field contains the names and user-submitted values for the Flow's structured data components.

You can also prepare a follow-up experience for the user, such as a message to indicate that you have received the completed flow.

Flow-specific webhook fields

flow-specific-webhook-fields page anchor
FieldDescription
InteractiveDataUser-provided information in JSON format.