Send WhatsApp messages with Content Templates

Before you begin, make sure you have the following:

• An approved WhatsApp sender: To register one, see Register WhatsApp senders using Self Sign-up.
• An approved Content Template: WhatsApp requires template approval for outbound messages.

To send a WhatsApp message, reference an approved Content Template by its Content SID (starts with HXXXXXX) in the content object. Set the recipient's channel to WHATSAPP, and provide a value for each template variable in the variables object.

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

The Content Template expects the same variable names you use in Programmable Messaging. Reference each variable by its positional index (1, 2, and so on) rather than by a named variable, as described in Using Variables with Content Templates.

1
"variables": {
2
    "1": "Darth",
3
    "2": "Vader"
4
}

You can combine WhatsApp with RCS, SMS, or both so that Twilio attempts delivery on a fallback channel when WhatsApp delivery fails. To do this, send from a Sender Pool that includes a WhatsApp sender along with your other senders.

Include the recipient's address for each channel in the fallback order. Because WhatsApp uses a distinct address, list it separately even when it matches the phone number used for SMS. For example, to fall back to SMS after a failed WhatsApp message, specify both the recipient's WhatsApp-enabled phone number and their phone number for SMS delivery.

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

When you use fallback, every channel must send the same content type. Use a single Content Template that has fallback content configured, so the template can render on each channel in the fallback order. You can't mix content types across channels within one message.

For details on building a template with fallback content, see Content Template dynamic content fallback.

Inline rich content isn't yet supported for WhatsApp. To send rich content, such as cards or media, over WhatsApp, use an approved Content Template. Define the rich content in the template rather than in the content object of your API request.

Inbound events through Bulk Messaging are in private beta and don't have a Service Level Agreement (SLA) yet. To receive replies to your WhatsApp messages, configure the webhook URL directly on your WhatsApp sender in the Twilio Console. Twilio delivers inbound WhatsApp events to that webhook.

To configure the webhook, navigate to Products & Services > Numbers and Senders > Overview in the console sidebar. Select the WhatsApp tab, choose your sender, click Edit Sender, and specify your inbound message webhook.

If your use case isn't covered by the webhook approach, reach out to Twilio Support.

• Learn about Channel Fallback across all channels.
• See how to manage senders with Sender Pools.
• Explore Rich Content options for other channels.