Rich Content

The Twilio Communications API provides endpoints for managing rich content and follows the same API schema used by channel providers such as Google and Meta. You can use the API to send rich, interactive messages across multiple channels.

Send content using an existing template

The API provides full support for existing Content Templates created using the Content Template Builder in the Twilio Console or with the Content API. To send a message that uses a template, include the template's Content SID (starts with HXXXXXX) and specify variable values for each recipient in the to field. Use ordinal numbers to map variables to the template slots.

1curl -X POST 'https://comms.twilio.com/preview/Messages' \
2--header 'Content-Type: application/json' \
3--data '{
4   "from": {
5       "address": "<Your Purchased Twilio Phone Number>",
6       "channel": "SMS"
7   },
8   "to": [
9       {
10           "address": "+19143188062",
11           "channel": "PHONE",
12           "variables": {
13               "1": "Darth",
14               "2": "Vader"
15           }
16       },
17       {
18           "address": "+19143188063",
19           "channel": "PHONE",
20           "variables": {
21               "1": "Spongebob",
22               "2": "Squarepants"
23           }
24       }
25   ],
26   "content": {
27       "contentId": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
28   }
29}' \
30-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Content template dynamic content fallback

The API supports dynamic content fallback for Content Templates. You can define multiple content types within a single template, and Twilio will deliver the message in the richest format supported by the recipient's device. For example, a template might include both a Card type and a Text and Media type.

1curl -X POST 'https://comms.twilio.com/preview/Messages' \
2--header 'Content-Type: application/json' \
3--data '{
4   "from": {
5       "senderPoolId": "comms_senderpool_123",
6       "channels": {
7           "priority": [
8               { "channel": "RCS", "priority": 0 },
9               { "channel": "SMS", "priority": 1 }
10           ]
11       }
12   },
13   "to": [
14       {
15           "address": "+19143188062",
16           "channel": "PHONE",
17           "variables": {
18               "1": "Darth",
19               "2": "Vader"
20           }
21       },
22       {
23           "address": "+19143188063",
24           "channel": "PHONE",
25           "variables": {
26               "1": "Spongebob",
27               "2": "Squarepants"
28           }
29       }
30   ],
31   "content": {
32       "contentId": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
33   }
34}' \
35-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Rich Content without templates

You can also define rich content directly in your API request for cases where template approval isn't required (e.g., RCS, SMS, or WhatsApp when a session is already open). This approach allows you to send rich, interactive messages without relying on pre-approved templates.

POST https://comms.twilio.com/preview/Messages

Sample request body:

1{
2   "from": {
3       "senderPoolId": "comms_senderpool_123",
4       "channels": {
5           "priority": [
6               { "channel": "RCS", "priority": 0 },
7               { "channel": "SMS", "priority": 1 }
8           ]
9       }
10   },
11   "to": [
12       {
13           "address": "+19143188062",
14           "channel": "PHONE",
15           "variables": {
16               "firstName": "Darth",
17               "lastName": "Vader"
18           }
19       },
20       {
21           "address": "+19143188062",
22           "channel": "PHONE",
23           "variables": {
24               "firstName": "Spongebob",
25               "lastName": "Squarepants"
26           }
27       }
28   ],
29   "content": {
30       "modules": [
31           {
32               "rcs": {
33                   "richCard": {
34                       "standaloneCard": {
35                           "cardContent": {
36                               "title": "Delivery arriving soon!",
37                               "media": {
38                                   "contentInfo": {
39                                       "fileUrl": "https://u.r.l/media/20997"
40                                   }
41                               },
42                               "suggestions": [
43                                   {
44                                       "action": {
45                                           "text": "Track package",
46                                           "postbackData": "tracked_package",
47                                           "openUrlAction": {
48                                               "url": "https://u.r.l/track/20997"
49                                           }
50                                       }
51                                   }
52                               ]
53                           }
54                       }
55                   }
56               }
57           },
58           {
59               "sms": {
60                   "text": "Track your delivery here: https://u.r.l/track/20997!",
61                   "media": [
62                       {
63                           "url": "https://u.r.l/media/20997"
64                       }
65                   ]
66               }
67           }
68       ]
69   }
70}

Next steps

Learn about Scheduling to see how to select delivery times for each recipient.