Channel Fallback

When sending messages, you can specify a primary channel and one or more fallback channels. If the message fails to deliver on the primary channel, Twilio will automatically attempt to send it via the fallback channel.

Fallback with inline rich content

You can define rich content and fallback content directly within your API request without needing to create a template. The following example shows a card message that falls back to SMS when RCS is unavailable.

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

Request body parameters:

1{
2  "from": {
3       "senderPoolId": "comms_senderpool_xxxx"
4   },
5   "to": [
6       {
7           "address": "+14155550102",
8           "channel": "PHONE"
9       }
10   ],
11   "content": {
12       "modules": [
13           {
14               "rcs": {
15                   "richCard": {
16                       "standaloneCard": {
17                           "cardContent": {
18                               "title": "Delivery arriving soon!",
19                               "suggestions": [
20                                   {
21                                       "action": {
22                                           "text": "Track package",
23                                           "postbackData": "tracked_package",
24                                           "openUrlAction": {
25                                               "url": "https://u.r.l/track/20997"
26                                           }
27                                       }
28                                   }
29                               ]
30                           }
31                       }
32                   }
33               }
34           },
35           {
36               "sms": {
37                   "text": "Track your delivery here: https://u.r.l/track/20997!"
38               }
39           }
40       ]
41   }
42}

Fallback with text or Content Templates (RCS to SMS)

If you have an approved RCS sender and an SMS/MMS capable phone number, you can configure Twilio to attempt delivery over RCS and fall back to SMS when RCS isn't available. To enable this behavior, create a Sender Pool that includes both the phone number and the RCS sender.

When your Sender Pool includes both a text-capable phone number and an RCS sender, Twilio automatically attempts to deliver via RCS first. If the recipient's device or carrier doesn't support RCS, the message falls back to SMS.

When sending rich content, use a Content Template that contains both the RCS elements and the corresponding SMS/MMS text or media.

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

Specify channel mix and fallback order

In some cases, you might want to limit the channels that can be used when using Sender Pools. Specify optional properties in the from parameter to control this behavior. In the following example, the filterIn property prevents Twilio from sending messages over WhatsApp, even when your Sender Pool contains active WhatsApp senders. The priority array sets the order in which Twilio attempts each channel.

1curl -X POST 'https://comms.twilio.com/preview/Messages' \
2--header 'Content-Type: application/json' \
3--data '{
4   "from": {
5       "senderPoolId": "comms_senderpool_dk2n984h",
6       "channels": {
7           "filterIn": ["RCS", "SMS"],
8           "priority": [
9               { "channel": "RCS", "priority": 0 },
10               { "channel": "SMS", "priority": 1 }
11           ]
12       }
13   },
14   "to": [
15       {
16           "address": "+19143188062",
17           "channel": "PHONE"
18       }
19   ],
20   "content": {
21       "text": "Hello there, I'\''m trying RCS first and failing over to SMS!"
22   }
23}' \
24-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Include multiple addresses per recipient

When you configure fallback across channels other than RCS and SMS, include the recipient's address for every channel involved.

For example, to fall back to SMS after a failed WhatsApp message, specify both of the following:

The recipient's phone number (for SMS delivery).
The recipient's WhatsApp-enabled phone number (for WhatsApp delivery).

1curl -X POST 'https://comms.twilio.com/preview/Messages' \
2--header 'Content-Type: application/json' \
3--data '{
4   "from": {
5       "senderPoolId": "comms_senderpool_dk2n984h"
6   },
7   "to": [
8       {
9           "addresses": [
10               { "address": "+12223334455", "channel": "PHONE" },
11               { "address": "+13334445566", "channel": "WHATSAPP"}
12           ],
13           "variables": {
14               "name": "Harry"
15           }
16       }
17   ],
18   "content": {
19       "text": "Hello {{name}}, your order has been shipped!"
20   }
21}' \
22-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN