twilio/carousel

Overview

Twilio/carousel is a low friction, yet highly rich way to send an end user a selection of your services, products, or any options that fit the conversation.

What is supported for end users

Send a horizontally scrolling list of carousel cards.
Send media, text, call to action buttons, and quick reply buttons in each carousel card.
Send any combination of quick reply, url, and phone call buttons in each card. Multiple of the same type of buttons are also allowed so long as there are 1 to 2 buttons in each card.
Media can be images or videos.

Supported channels

WhatsApp, RCS

(information)

Info

Carousels sent over RCS do not support body text. Defined body text will be dropped when sending carousel over RCS.

Message preview

Getting started

To send carousels, you will need to:

Have media URLs for each card ready prior to template creation.
Create twilio/carousel content template.
If it will be used on WhatsApp, approve the template.
Send the Content Template containing the carousel.

To send a Carousel to open a business initiated session or to reply within a 24 hour user initiated session, template approval is required.

Creating your content template

Data parameters

twilio/carousel

body:

Type: string
Required: Yes
Variable Support: Yes
Description: Content of the initial message delivered to the end user above the carousel.

cards:

Type: array
Required: Yes
Variable Support: No
Description: Array of Carousel cards to be sent

Cards

title:

Type: string
Required: No
Variable Support: Yes
Description: Header text of each carousel card. Max character limit is 160 combined with body text.

body:

Type: string
Required: Yes
Variable Support: Yes
Description: Body text of each carousel card. Max character limit is 160 combined with body text.

media:

Type: string
Required: Yes
Variable Support: Yes
Description: The URL of the media appearing as the header of each card. Variables are only supported after the domain. For example: www.twilio.com/images/{{1}}. Only images and videos are supported within carousels.

actions:

Type: array
Required: Yes
Variable Support: Yes
Description: All Carousels must contain at least 1 button and at most 2 buttons. Buttons are defined using the actions array.

(information)

Info

The order of quick reply, url, and phone number buttons in a card must appear in the same order for every card.

Actions

QUICK_REPLY:

parameters
- type: QUICK_REPLY
- title: Button text of quick reply button. Appears in Body and ButtonText fields in inbound when selected by end user.
- id: Not visible to end user. Appears in ButtonPayload fields in inbound when selected by end user.

URL:

parameters
- type: URL
- title: Button text of URL redirect button. Variables are not supported. Max 25 chars.
- url: URL opened when end user clicks the button. Variables are supported at the end of the url string.

PHONE_NUMBER:

parameters
- type: PHONE_NUMBER
- title: Button text of URL redirect button. Variables are not supported. Max 25 chars.
- phone: Phone number to call when the recipient taps the button. E.164 formatted. Variables are not supported.

Content creation request

Create twilio carousel content 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": "twilio_deal",
6    "language": "en",
7    "variables": {
8        "1": "Twilio"
9    },
10    "types": {
11        "twilio/carousel": {
12                 "body": "New {{1}} merch just dropped! 👀",
13                 "cards": [
14                     {
15      "title":"Twilio Hoodie",
16      "body":"Warm as owl feathers.",
17      "media":"https://sienna-grasshopper-3262.twil.io/assets/hoodie.jpeg",
18      "actions":[
19        {
20          "type":"QUICK_REPLY",
21          "title":"I want it!",
22          "id":"want_hoodie"
23        },
24        {
25          "type":"URL",
26          "title":"I am taking this!",
27          "url":"https://sienna-grasshopper-3262.twil.io/assets/hoodie.jpeg"
28        }
29      ]
30    },
31    {
32      "title":"Twilio Tote",
33      "body":"Carry a little more.",
34      "media":"https://sienna-grasshopper-3262.twil.io/assets/tote.jpeg",
35      "actions":[
36        {
37          "type":"QUICK_REPLY",
38          "title":"I want it!",
39          "id":"want_tote"
40        },
41        {
42          "type":"URL",
43          "title":"Take the tote!",
44          "url":"https://sienna-grasshopper-3262.twil.io/assets/tote.jpeg"
45        }
46      ]
47    },
48    {
49      "title":"Twilio Bucket Hat",
50      "body":"Stay in the shade.",
51      "media":"https://sienna-grasshopper-3262.twil.io/assets/hat.jpeg",
52      "actions":[
53        {
54          "type":"QUICK_REPLY",
55          "title":"I want it!",
56          "id":"want_hat"
57        },
58        {
59          "type":"URL",
60          "title":"Hand me the hat!",
61          "url":"https://sienna-grasshopper-3262.twil.io/assets/hat.jpeg"
62        }
63      ]
64    },
65    {
66      "title":"Twilio Mug",
67      "body":"Sip a little.",
68      "media":"https://sienna-grasshopper-3262.twil.io/assets/mug.jpeg",
69      "actions":[
70        {
71          "type":"QUICK_REPLY",
72          "title":"I want it!",
73          "id":"want_mug"
74        },
75        {
76          "type":"URL",
77          "title":"Make me a mug!",
78          "url":"https://sienna-grasshopper-3262.twil.io/assets/mug.jpeg"
79        }
80      ]
81    }
82]
83        }
84    }
85}'

Output

1{
2  "account_sid": "ACXXXXXXXX",
3  "date_created": "2024-07-24T20:35:59Z",
4  "date_updated": "2024-07-24T20:35:59Z",
5  "friendly_name": "twilio_deal",
6  "language": "en",
7  "links": {
8    "approval_create": "https://content.twilio.com/v1/Content/HXxxxxxxxxx/ApprovalRequests/whatsapp",
9    "approval_fetch": "https://content.twilio.com/v1/Content/HXxxxxxxxxx/ApprovalRequests"
10  },
11  "sid": "HXxxxxxxx",
12  "types": {
13    "twilio/carousel": {
14      "body": "New {{1}} merch just dropped! 👀",
15      "cards": [
16        {
17          "actions": [
18            {
19              "id": "want_hoodie",
20              "index": 0,
21              "title": "I want it!",
22              "type": "QUICK_REPLY"
23            },
24            {
25              "title": "I'm taking this!",
26              "type": "URL",
27              "url": "https://sienna-grasshopper-3262.twil.io/assets/hoodie.jpeg"
28            }
29          ],
30          "body": "Warm as owl feathers.",
31          "media": "https://sienna-grasshopper-3262.twil.io/assets/hoodie.jpeg",
32          "title": "Twilio Hoodie"
33        },
34        {
35          "actions": [
36            {
37              "id": "want_tote",
38              "index": 0,
39              "title": "I want it!",
40              "type": "QUICK_REPLY"
41            },
42            {
43              "title": "Take the tote!",
44              "type": "URL",
45              "url": "https://sienna-grasshopper-3262.twil.io/assets/tote.jpeg"
46            }
47          ],
48          "body": "Carry a little more.",
49          "media": "https://sienna-grasshopper-3262.twil.io/assets/tote.jpeg",
50          "title": "Twilio Tote"
51        },
52        {
53          "actions": [
54            {
55              "id": "want_hat",
56              "index": 0,
57              "title": "I want it!",
58              "type": "QUICK_REPLY"
59            },
60            {
61              "title": "Hand me the hat!",
62              "type": "URL",
63              "url": "https://sienna-grasshopper-3262.twil.io/assets/hat.jpeg"
64            }
65          ],
66          "body": "Stay in the shade.",
67          "media": "https://sienna-grasshopper-3262.twil.io/assets/hat.jpeg",
68          "title": "Twilio Bucket Hat"
69        },
70        {
71          "actions": [
72            {
73              "id": "want_mug",
74              "index": 0,
75              "title": "I want it!",
76              "type": "QUICK_REPLY"
77            },
78            {
79              "title": "Make me a mug!",
80              "type": "URL",
81              "url": "https://sienna-grasshopper-3262.twil.io/assets/mug.jpeg"
82            }
83          ],
84          "body": "Sip a little.",
85          "media": "https://sienna-grasshopper-3262.twil.io/assets/mug.jpeg",
86          "title": "Twilio Mug"
87        }
88      ]
89    }
90  },
91  "url": "https://content.twilio.com/v1/Content/HXxxxxxxxxx",
92  "variables": {
93    "1": "Twilio"
94  }
95}

Sending your message template

Sending a carousel template using content templates is the same as sending other types of Content Templates. Click here to see an in-depth guide for how to send Content templates.

Receiving webhooks

Carousel specific webhook fields:

Component	Description
Body	The button text of the quick reply button that the end user selected
ButtonText	The button text of the quick reply button that the end user selected
ButtonPayload	The ID of the button that the end user selected