Skip to content Skip to navigation Skip to topbar

On this page

Send Rich Content Messages with Conversations

Overview

In this tutorial, you will learn how to send rich messages to WhatsApp using Conversations and the Content Template Builder. The Content Template Builder lets users build rich content templates programmatically through an API or with no code in a graphical user interface in the console. "Rich content" or "Rich messaging" refers to messages with additional visual or interactive elements such as buttons or selectable lists.

The Content Template Builder

With Twilio's Content Template Builder, you can create message templates to send over any Twilio-supported messaging channel. It supports text and media as well as richer content types like location, quick-replies, and list-pickers. The templates also support variables, so you can leverage the same content across multiple conversations while personalizing each message.

Below is an overview of the content types currently supported by Conversations. See the individual content type documentation for additional details about each type's parameters and input requirements.

Content Type	Data parameter	Type	Description
twilio/text	body [required]	string	The text of the message you want to send. Maximum 1,600 characters.
twilio/media	body [required]	string	The text of the message you want to send. Maximum 1,600 characters.
	media [optional]	string[]	The URL of the media you want to send. - The URL must resolve to a publicly accessible media file. - The media URL must contain a valid file type.
twilio/location	longitude [required]	numbers	The longitude value of the location pin you want to send.
	latitude [required]	numbers	The latitude value of the location pin you want to send.
	label [optional]	string	Label to be displayed alongside the location pin.
twilio/quick-reply	body [required]	string	The text of the message you want to send. Maximum 1,024 characters.
	actions [required]	array[actions]	Predefined buttons that a customer could use as the response. It needs the "type", "title", and "id" fields.
twilio/call-to-action	body [required]	string	The text of the message you want to send. Maximum 640 characters.
	actions [required]	array[actions]	Buttons that recipients can tap to act on the message. It requires the "type" and "title" actions.
twilio/list-picker	body [required]	string	The text of the message you want to send. Maximum 1,024 characters.
	button [required]	string	Display value for the primary button.
	items [required]	array[list items]	Array of list item objects.
twilio/card	title [required]	string	Title of the card. Maximum 1,024 characters.
	subtitle [optional]	string	Subtitle of the card. Maximum 60 characters.
	media [optional]	string[]	The URL of the media to send with the message.
	actions [optional]	array[actions]	Buttons that recipients can tap on to act on the message.

Step 1: Create Content Template via Content API

(information)

Info

The Content Template Builder supports an unlimited number of templates, however, WhatsApp limits users to 6000 approved templates across all languages.

To send a rich message, you'll first need to create a content template using the Content Template Builder.

In the following example, we'll use the "quick-reply" template, which allows the recipient to respond by clicking on one of the options that you pre-define in the template. To see how the template layout looks, please navigate to Step 4.

After creating your template, please note down the ContentSid (HXXXXXX) found in the response as we'll be using that SID throughout this tutorial.

POST API

Request:

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": "flight_replies",
6    "language": "en",
7    "variables": {"1":"name"},
8    "types": {
9        "twilio/quick-reply": {
10                    "body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?",
11                    "actions": [
12                        {
13                            "title": "Check flight status",
14                            "id": "flightid1"
15                        },
16                        {
17                            "title": "Check gate number",
18                            "id": "gateid1"
19                        },
20                        {
21                            "title": "Speak with an agent",
22                            "id": "agentid1"
23                        }
24                    ]
25                },
26        "twilio/text": {
27            "body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?."
28        }
29    }
30}'
31

Response:

1{
2  "language": "en",
3  "date_updated": "2022-08-29T10:43:20Z",
4  "variables": {
5    "1": "name"
6  },
7  "friendly_name": "flight_replies",
8  "account_sid": "ACXXXXXXXXXXXXXXXXXXX",
9  "url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
10  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
11  "date_created": "2022-08-29T10:43:20Z",
12  "types": {
13    "twilio/text": {
14      "body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?."
15    },
16    "twilio/quick-reply": {
17      "body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?",
18      "actions": [
19        {
20          "id": "flightid1",
21          "title": "Check flight status"
22        },
23        {
24          "id": "gateid1",
25          "title": "Check gate number"
26        },
27        {
28          "id": "agentid1",
29          "title": "Speak with an agent"
30        }
31      ]
32    }
33  },
34  "links": {
35    "approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests",
36    "approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp"
37  }
38}
39

Optional: Retrieve a Content Template SID from the Content Template Builder

You can make a GET request to the Content API to fetch a list of all the content templates that you have created.

GET API

Request:

1curl -X GET "https://content.twilio.com/v1/Content?PageSize=2" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response:

1{
2   "meta": {
3       "page": 0,
4       "page_size": 2,
5       "first_page_url": "https://content.twilio.com/v1/Content?PageSize=2&Page=0",
6       "previous_page_url": null,
7       "url": "https://content.twilio.com/v1/Content?PageSize=2&Page=0",
8       "next_page_url": "https://content.twilio.com/v1/Content?PageSize=2&Page=1&PageToken=PAHXXXXXXXXXXXX",
9       "key": "contents"
10   },
11   "contents": [
12       {
13           "language": "en",
14           "date_updated": "2023-03-07T14:46:13Z",
15           "variables": {
16               "1": "flight_number",
17               "3": "departure_time",
18               "2": "arrival_city",
19               "5": "url_suffix",
20               "4": "gate_number"
21           },
22           "friendly_name": "flight_departure_update",
23           "account_sid": "ACXXXXXXXXXX",
24           "url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXX",
25           "sid": "HXXXXXXXXXXXX",
26           "date_created": "2023-03-07T14:46:13Z",
27           "types": {
28               "twilio/call-to-action": {
29                   "body": "Owl Air: We will see you soon! Flight {{ 1 }} to {{ 2 }} departs at {{ 3 }} from Gate {{ 4 }}.",
30                   "actions": [
31                       {
32                           "url": "https://owlair.com/{{ 5 }}",
33                           "type": "URL",
34                           "title": "Check Flight Status"
35                       },
36                       {
37                           "phone": "+18005551234",
38                           "type": "PHONE_NUMBER",
39                           "title": "Call Support"
40                       }
41                   ]
42               }
43           },
44           "links": {
45               "approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXX/ApprovalRequests",
46               "approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXX/ApprovalRequests/whatsapp"
47           }
48       },
49       {
50           "language": "en",
51           "date_updated": "2023-02-24T14:25:37Z",
52           "variables": {
53               "1": "name"
54           },
55           "friendly_name": "flight_replies",
56           "account_sid": "ACXXXXXXXXXX",
57           "url": "https://content.twilio.com/v1/Content/HXXXXXXXXXX",
58           "sid": "HXXXXXXXXXXX",
59           "date_created": "2023-02-24T14:25:37Z",
60           "types": {
61               "twilio/text": {
62                   "body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?."
63               },
64               "twilio/quick-reply": {
65                   "body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?",
66                   "actions": [
67                       {
68                           "id": "flightid1",
69                           "title": "Check flight status"
70                       },
71                       {
72                           "id": "gateid1",
73                           "title": "Check gate number"
74                       },
75                       {
76                           "id": "agentid1",
77                           "title": "Speak with an agent"
78                       }
79                   ]
80               }
81           },
82           "links": {
83               "approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXX/ApprovalRequests",
84               "approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXX/ApprovalRequests/whatsapp"
85           }
86       }
87   ]
88}

Step 2: Create a Conversation

Now, let's create a Conversation that we'll use in the next step to send a rich content message. In the sample code below, replace the Account SID and Auth Token with the values from your Twilio Console. Copy down the Conversation SID (It starts with CHXXXXX). We'll be using this value in the next step when we add a WhatsApp participant to the Conversation you just created.

POST API

Request:

1curl -X POST "https://conversations.twilio.com/v1/Conversations" \
2--data-urlencode "FriendlyName=Send Rich content messages with Conversations" \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response:

1{
2   "unique_name": null,
3   "date_updated": "2023-02-13T12:31:50Z",
4   "friendly_name": "Send rich content messages with Conversations",
5   "timers": {},
6   "account_sid": "ACXXXXXXXXXXXXX",
7   "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXX",
8   "state": "active",
9   "date_created": "2023-02-13T12:31:50Z",
10   "messaging_service_sid": "MGXXXXXXXXXXXX",
11   "sid": "CHXXXXXXXXXXXXX",
12   "attributes": "{}",
13   "bindings": null,
14   "chat_service_sid": "ISXXXXXXXXXX",
15   "links": {
16       "participants": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXX/Participants",
17       "messages": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXX/Messages",
18       "webhooks": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXX/Webhooks"
19   }
20}

Step 3: Add a WhatsApp Participant to the Conversation

Let's add a WhatsApp Participant to the Conversation. For the code sample below, replace the placeholder values for:

CHXXXXXXX: use the Conversation SID you just copied
YOUR_WHATSAPP_NUMBER: your WhatsApp phone number, in E.164 format
TWI_WA_NUMBER: Your Twilio enabled WhatsApp phone number, in E.164 format
TWILIO_ACCOUNT_SID: Your Twilio Account SID
TWILIO_AUTH_TOKEN: Your Twilio Auth Token

POST API

Request:

1curl -X POST "https://conversations.twilio.com/v1/Conversations/CHxxxx/Participants" \
2--data-urlencode "MessagingBinding.Address=whatsapp:YOUR_WHATSAPP_NUMBER" \
3--data-urlencode "MessagingBinding.ProxyAddress=whatsapp:TWI_WA_NUMBER" \
4-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response:

1{
2   "last_read_message_index": null,
3   "date_updated": "2023-02-17T16:45:32Z",
4   "last_read_timestamp": null,
5   "conversation_sid": "CHXXXXXXXXX",
6   "account_sid": "ACXXXXXXXXXX",
7   "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXX/Participants/MBXXXXXXXXX",
8   "date_created": "2023-02-17T16:45:32Z",
9   "role_sid": "RLXXXXXXXXXX",
10   "sid": "MBXXXXXXXXXXX",
11   "attributes": "{}",
12   "identity": null,
13   "messaging_binding": {
14       "proxy_address": "whatsapp:TWI_WA_NUMBER",
15       "type": "whatsapp",
16       "address": "whatsapp:YOUR_WHATSAPP_NUMBER"
17   }
18}

Step 4: Send a Rich Message via the Conversations API

(information)

Info

If the customer representative wants to send rich content messages prior to the end user messaging them on WhatsApp, then this content template will need to be approved before it can be sent out. Some content types (e.g., Cards and CTA buttons) require prior approval regardless of whether the template is sent in the context of a session or not.

So far you've created a content template, and a Conversation with a WhatsApp participant. Now we're ready to send a rich message to the participant. This example uses the Conversations API, but content templates are also available through the Conversations SDKs for JavaScript, Android, and iOS.

In our POST request example, you'll pass the ContentVariables parameter (optional), which allows you to customize the message content with dynamic values. For this example, "name" will be replaced with the value ("Alice").

Replace:

CHXXXXXXXXXXXXXXXXXXX with the Conversation SID in the request URL
HXXXXXXXXXXXXXXXXXXXX value in the Content SID parameter

Request parameters:

Parameter	Required	Description
ContentSid	Yes	The unique ID of the multi-channel Content template, required for template-generated message. Note that if this field is set, the Body and MediaSid parameters are ignored.
ContentVariables	Optional	A structurally valid JSON string that contains values to determine Content template variables.

POST API

Request:

1curl -X POST "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXX/Messages" \
2--data-urlencode 'ContentSid=HXXXXXXXXXXXXXXXXXXXX' \
3--data-urlencode 'ContentVariables={ "1": "Alice" }' \
4-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
5

Response:

1{
2   "body": "Hi, Alice. \n Thanks for contacting Owl Air Support. How can I help?",
3   "index": 0,
4   "author": "system",
5   "date_updated": "2023-02-09T17:44:30Z",
6   "media": null,
7   "participant_sid": null,
8   "conversation_sid": "CHXXXXXXXXXXXXXXXXXXX",
9   "account_sid": "ACXXXXXXXXXXXXXXXXXXX",
10   "delivery": null,
11   "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXX0/Messages/IMXXXXXXXXXXXXXXXXXXX",
12   "date_created": "2023-02-09T17:44:30Z",
13   "content_sid": "HXXXXXXXXXXXXXXXXXXXX",
14   "sid": "IMXXXXXXXXXXXXXXXXXXX",
15   "attributes": "{}",
16   "links": {
17       "delivery_receipts": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXX/Messages/IMXXXXXXXXXXXXXXXXXXX/Receipts"
18   }
19}

WhatsApp Conversation screenshot showing interactive elements in the form of buttons.

Well done! You've successfully sent your first rich content message to your WhatsApp Participant using Twilio Conversations.

What's Next?

As a following step, you can:

Check out our Conversations Quickstart
Learn more about the Content Template Builder