whatsapp/flows

Overview

Flows is an in-app, multi-screen experience available on WhatsApp. A business sends a Flow as part of an approved content template. When an end user taps the Flow button, the multi-screen experience opens. Within the Flow, you can include text, images, and several input components. End users can respond with single-choice, multi-choice, toggle, short-text, long-text, and date-picker inputs.

With whatsapp/flows, you pre-define the Flow in WhatsApp and send it through Twilio to use the full WhatsApp functionality for this feature.

(warning)

Flows limitations

Flows isn't designed to transmit HIPAA Eligible Service or PCI data and shouldn't be used 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

Send Flows with any component that WhatsApp supports.
Send Flows with an endpoint integration to pass data between your back-end services and WhatsApp during the interaction.

Supported channel

Message preview

Create a Flow

Create a Flow with WhatsApp Manager or programmatically with the Flow API from Meta.

WhatsApp ManagerFlow API

Follow the steps to open WhatsApp Manager.
In the Account Tools menu, click Flows.
Click Create Flow.
Follow the steps to create a new Flow. Record the id of the first screen that you want to display.
To Publish your new Flow, click Publish.
In the Account Tools menu, click Flows.
Copy the Flow ID of the Flow that you've just created.

Data parameters

Parameter	Type	Required	Variable support	Description
`body`	string	Yes	Yes	Text of the templated message that launches the Flow. Maximum length: 1,024 characters
`subtitle`	string	No	No	Optional subtitle shown in the message footer. Maximum length: 80 characters
`media_url`	string	No	Yes	Media included in the initial Flow message. Supports `.png`, `.jpeg`, `.mp4`, and `.pdf`. The domain must be static; the path can be a variable.
`type`	enum	Yes	No	Flow category. Valid values: `SIGN_UP` `SIGN_IN` `APPOINTMENT_BOOKING` `LEAD_GENERATION` `CONTACT_US` `CUSTOMER_SUPPORT` `SURVEY` `OTHER`
`flow_id`	string	Yes	No (approved templates) Yes (in-session without approval)	Identifier for the Flow in WhatsApp.
`flow_token`	string	Yes	Yes (must be a variable)	Unique identifier for the specific Flow interaction. Provide a new value for each send request.
`flow_first_page_id`	string	Yes	Yes	Identifier of the first page to display in the Flow interaction.
`is_flow_first_page_endpoint`	Boolean	No	No	Set to `true` if an endpoint determines the first page. Defaults to `false`.

Code examples and responses

Content Templates API - Create a WhatsApp Flow Template

1curl -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": "ACXXXXXXXXXXXX",
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/HXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp",
9        "approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXX/ApprovalRequests"
10    },
11    "sid": "HXXXXXXXXXXXXXXXXX",
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/HXXXXXXXXXXXXXXXXX",
25    "variables": {
26        "1": "abcd1234"
27    }
28}

Send your message template

Sending a Flow template is the same process as sending any other content template. For detailed steps, see Send templates created with the Content Template Builder.

Receiving webhooks

Flow-specific webhook fields

Field	Description
`InteractiveData`	User-provided information in JSON format.