Skip to contentSkip to navigationSkip to topbar

twilio/flows



Overview

overview page anchor

Flows is an in-app, multi-screen experience available on WhatsApp. A business can send a Flow as part of an approved content template. End users start the Flow by selecting a Flow button, which opens the multi-screen experience. Within the Flow, you can add text, images, and several input components. End users can provide input through single-choice, multi-choice, toggles, short-text answers, long-text answers, and date pickers. You can organize these components across as many as 10 screens.

(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

supported-options-for-end-users page anchor
  • Send a multi-screen form that includes several questions.
  • Collect text input, selections, and picker answers.
  • Include images, links, and clarifying text on each screen.

WhatsApp


Flow content template 1: chat conversation with Twilio Demo that shows a helpful link and response notification.
Flow content template 2: survey form with questions and an option to complete the survey.

To create a Flow:

  1. Create a twilio/flows content template.
  2. Submit the content template for approval. Choose the appropriate category (UTILITY or MARKETING).
  3. When you submit the twilio/flows content template, WhatsApp publishes the Flow. You can view the publishing status in the content template approvals list. Currently, you can't use Flows without an approved content template.
  4. Send the Flow. For instructions, see Send templates created with the Content Template Builder.

Receive a flow submission

receive-a-flow-submission page anchor
  1. Prepare the follow-up experience for the end user.
  2. Review the incoming webhook that contains the user's answers.

ParameterTypeRequiredVariable supportDescription
bodystringYesYesText of the templated message that delivers the Flow.
Maximum length: 1,024 characters
subtitlestringNoNoFooter of the message.
Maximum length: 1,024 characters
media_urlstringNoYesMedia on the initial Flow message. Supports .png, .jpeg, .mp4, and .pdf. The domain must be static; the path can be variable.
typeenumYesNoFlow category.
Valid values:
  • SIGN_UP
  • SIGN_IN
  • APPOINTMENT_BOOKING
  • LEAD_GENERATION
  • CONTACT_US
  • CUSTOMER_SUPPORT
  • SURVEY
  • OTHER
button_textstringYesNoText displayed on the button that starts the Flow.
pagesarrayYesNoDefinitions of each page's components. Maximum: 10 pages.
PropertyTypeRequiredVariable supportDescription
idstringYesNoIdentifier returned in the webhook.
Maximum length: 20 characters
titlestringNoNoTitle text that appears above the Flow page.
subtitlestringNoNoSubtitle text that appears at the top of the Flow page.
layoutarrayYesNoComponents shown on the page. Each component must be one of the following:
  • SHORT_TEXT
  • LONG_TEXT
  • SINGLE_SELECT
  • MULTI_SELECT
  • DATE_PICKER
  • LIST
  • TEXT_HEADING
  • TEXT_SUBHEADING
  • TEXT_CAPTION
  • TEXT_BODY
  • RICH_TEXT
  • MEDIA
  • FOOTER

SHORT_TEXT object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be SHORT_TEXT.
textYesstringYes (entire string must be variable or static)Helper text.
labelYesstringYes (entire string must be variable or static)Question displayed to the user.
requiredNoBooleanNoDefaults to false. Whether the user must answer the question.
input_typeNoenumNoDefaults to TEXT. Valid values: TEXT, NUMBER, EMAIL, PASSWORD, PASSCODE, PHONE.

LONG_TEXT object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be LONG_TEXT.
textYesstringYes (entire string must be variable or static)Helper text.
labelYesstringYes (entire string must be variable or static)Question displayed to the user.
requiredNoBooleanNoDefaults to false. Whether the user must answer the question.

SINGLE_SELECT object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be SINGLE_SELECT.
textYesstringYes (entire string must be variable or static)Helper text.
labelYesstringYes (entire string must be variable or static)Question displayed to the user.
optionsYesstringYes (entire string must be variable or static)Stringified array that contains title and id pairs. If you use a variable, the variable must replace the entire string.
Example: "[{\"id\":\"ff\",\"title\":\"Friends and family\"}]"
options.titleYesstringYesDisplay title for the option. Can be a variable.
options.idYesstringYesOption identifier returned in the webhook. Can be a variable.

MULTI_SELECT object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be MULTI_SELECT.
textYesstringYes (entire string must be variable or static)Helper text.
labelYesstringYes (entire string must be variable or static)Question displayed to the user.
optionsYesstringYes (entire string must be variable or static)Stringified array that contains title and id pairs. If you use a variable, the variable must replace the entire string.
Example: "[{\"id\":\"ff\",\"title\":\"Friends and family\"}]"
options.titleYesstringYesDisplay title for the option. Can be a variable.
options.idYesstringYesOption identifier returned in the webhook. Can be a variable.

DATE_PICKER object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be DATE_PICKER.
labelYesstringYes (entire string must be variable or static)Question displayed to the user.
min_dateYesstringYes (entire string must be variable or static)Start date in YYYY-MM-DD format.
max_dateYesstringYes (entire string must be variable or static)End date in YYYY-MM-DD format.
unavailable_datesYesstringYes (entire string must be variable or static)Stringified array of unavailable dates in YYYY-MM-DD format.
nameNostringYes (entire string must be variable or static)Name of the date picker object.

LIST object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be LIST.
labelYesstringYes (entire string must be variable or static)Question displayed to the user.
optionsYesstringYes (entire string must be variable or static)Stringified array that contains title and id pairs. If you use a variable, the variable must replace the entire string.
Example: "[{\"id\":\"ff\",\"title\":\"Friends and family\"}]"
options.titleYesstringYesDisplay title for the option. Can be a variable.
options.idYesstringYesOption identifier returned in the webhook. Can be a variable.

TEXT_HEADING object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be TEXT_HEADING.
textYesstringYes (entire string must be variable or static)Markdown-formatted text. Supports the syntax described in the WhatsApp Components syntax cheat sheet(link takes you to an external page).

TEXT_SUBHEADING object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be TEXT_SUBHEADING.
textYesstringYes (entire string must be variable or static)Markdown-formatted text. Supports the syntax described in the WhatsApp Components syntax cheat sheet(link takes you to an external page).

TEXT_BODY object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be TEXT_BODY.
textYesstringYes (entire string must be variable or static)Markdown-formatted text. Supports the syntax described in the WhatsApp Components syntax cheat sheet(link takes you to an external page).

TEXT_CAPTION object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be TEXT_CAPTION.
textYesstringYes (entire string must be variable or static)Markdown-formatted text. Supports the syntax described in the WhatsApp Components syntax cheat sheet(link takes you to an external page).

RICH_TEXT object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be RICH_TEXT.
text_listYesarrayYes (entire string must be variable or static)Array of Markdown-formatted strings. Supports the syntax described in the WhatsApp Components syntax cheat sheet(link takes you to an external page).

MEDIA object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be MEDIA.
urlYesstringYesImage URL. Supports .jpeg and .png formats.

FOOTER object

PropertyRequiredTypeVariable supportDescription
typeYesenumNoMust be FOOTER.
labelYesstringYesText displayed in the button used to continue the Flow.

Code examples and responses

code-examples-and-responses page anchor
Content Templates API - Create a Flow TemplateLink to code sample: Content Templates API - Create a 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",
7
"types": {
8
"twilio/flows": {
9
"body": "Wow do we have something super cool for you! Thanks for your interest. we have a helpful link there too.",
10
"button_text": "See flow",
11
"subtitle": "Finish flow",
12
"pages": [
13
{
14
"id": "id_one",
15
"next_page_id": "id_two",
16
"title": "Page 1",
17
"layout": [
18
{
19
"label": "Name",
20
"type": "SHORT_TEXT",
21
"text": "Question 1",
22
"required": true
23
},
24
{
25
"label": "Email",
26
"type": "SHORT_TEXT",
27
"text": "Question 2",
28
"input_type": "EMAIL"
29
},
30
{
31
"label": "Address",
32
"type": "LONG_TEXT",
33
"text": "Question 3"
34
}
35
]
36
},
37
{
38
"id": "id_two",
39
"next_page_id": null,
40
"title": "Page 2",
41
"subtitle": "Subtitle of Page 2",
42
"layout": [
43
{
44
"label": "How did you find us?",
45
"type": "SINGLE_SELECT",
46
"options": "[{\"id\":\"ff\",\"title\":\"Friends and family\"},{\"id\":\"oo\",\"title\":\"Online\"},{\"id\":\"ip\",\"title\":\"In person\"}]"
47
},
48
{
49
"label": "What is your favorite number?",
50
"type": "MULTIPLE_SELECT",
51
"options": "[{\"id\":\"one\",\"title\":\"one one\"},{\"id\":\"two\",\"title\":\"two two\"},{\"id\":\"three\",\"title\":\"three three\"}]"
52
},
53
{
54
"type": "TEXT_BODY",
55
"text": "Go to [Google](https://www.google.com/) if you have any questions"
56
},
57
{
58
"type": "TEXT_CAPTION",
59
"text": "No seriously, go to [Google](https://www.google.com/) if you have any questions"
60
},
61
{
62
"label": "If other, tell us where",
63
"type": "SHORT_TEXT",
64
"text": "Question 6"
65
}
66
]
67
}
68
],
69
"type": "OTHER"
70
}
71
}
72
}'

Output

1
{
2
"account_sid": "ACXXXXXXXXXXXXX",
3
"date_created": "2025-01-22T22:35:25Z",
4
"date_updated": "2025-01-22T22:35:25Z",
5
"friendly_name": "info_flow",
6
"language": "en",
7
"links": {
8
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXX/ApprovalRequests/whatsapp",
9
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXX/ApprovalRequests"
10
},
11
"sid": "HXXXXXXXXXXXX",
12
"types": {
13
"twilio/flows": {
14
"body": "Wow do we have something super cool for you! Thanks for your interest. we have a helpful link there too.",
15
"button_text": "See flow",
16
"media_url": null,
17
"pages": [
18
{
19
"id": "id_one",
20
"layout": [
21
{
22
"input_type": "TEXT",
23
"label": "Name",
24
"name": null,
25
"required": true,
26
"text": "Question 1",
27
"type": "SHORT_TEXT"
28
},
29
{
30
"input_type": "EMAIL",
31
"label": "Email",
32
"name": null,
33
"required": null,
34
"text": "Question 2",
35
"type": "SHORT_TEXT"
36
},
37
{
38
"input_type": null,
39
"label": "Address",
40
"name": null,
41
"required": null,
42
"text": "Question 3",
43
"type": "LONG_TEXT"
44
}
45
],
46
"next_page_id": "id_two",
47
"subtitle": null,
48
"title": "Page 1"
49
},
50
{
51
"id": "id_two",
52
"layout": [
53
{
54
"label": "How did you find us?",
55
"name": null,
56
"options": "[{\"id\":\"ff\",\"title\":\"Friends and family\"},{\"id\":\"oo\",\"title\":\"Online\"},{\"id\":\"ip\",\"title\":\"In person\"}]",
57
"required": null,
58
"type": "SINGLE_SELECT"
59
},
60
{
61
"label": "What's your favorite number?",
62
"name": null,
63
"options": "[{\"id\":\"one\",\"title\":\"one one\"},{\"id\":\"two\",\"title\":\"two two\"},{\"id\":\"three\",\"title\":\"three three\"}]",
64
"required": null,
65
"type": "MULTIPLE_SELECT"
66
},
67
{
68
"text": "Go to [Google](https://www.google.com/) if you have any questions",
69
"type": "TEXT_BODY"
70
},
71
{
72
"text": "No seriously, go to [Google](https://www.google.com/) if you have any questions",
73
"type": "TEXT_CAPTION"
74
},
75
{
76
"input_type": "TEXT",
77
"label": "If other, tell us where",
78
"name": null,
79
"required": null,
80
"text": "Question 6",
81
"type": "SHORT_TEXT"
82
}
83
],
84
"next_page_id": null,
85
"subtitle": "Subtitle of Page 2",
86
"title": "Page 2"
87
}
88
],
89
"subtitle": "Finish flow",
90
"type": "OTHER"
91
}
92
},
93
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXX",
94
"variables": {}
95
}

Send your message template

send-your-message-template page anchor

Sending a Flow template works the same way as sending any other content template. For step-by-step instructions, see Send templates created with the Content Template Builder.


Flow-specific webhook fields

flow-specific-webhook-fields page anchor
FieldDescription
FlowDataRaw data string from the channel provider.
InteractiveDataUser-provided information in JSON format.