Send templates created with the Content Template Builder

This guide explains how to send messages using templates created with the Content Template Builder. Learn how to configure the required fields in your API request and use Messaging Services to send content templates.

To send messages with a template you created in the Content Template Builder, include two fields in your API request. First, configure a Messaging Service and create the content template.

Content fields used to send messages

Use the existing messaging endpoint with an additional ContentSid parameter. You can also include the ContentVariables field to substitute any placeholder values in your templates.

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages

The following table describes the fields used to send content templates:

Field	Required	Description
`ContentSid`	Yes	String that identifies the preconfigured content. Required to send templates created using the Content Template Builder.
`ContentVariables`	No	JSON string that defines values for placeholder variables in the template. Key-value pairs of placeholder variable names and substitution values. You can include up to 100 key-value pairs per request.

(information)

You must use a WhatsApp-approved template

If you send a WhatsApp message outside the 24-hour free-form session, you must use a WhatsApp-approved template. To learn more, see Content API quick start.

Send content templates

The following example shows how to send a message with a content template:

(warning)

Exclude Body and MediaUrl parameters

Exclude Body and MediaUrl. ContentSid replaces both parameters. You might need to update your library to support ContentSid.

Send messages with a content template

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    contentSid: "HXXXXXXXXX",
13    contentVariables: JSON.stringify({ 1: "Name" }),
14    from: "whatsapp:+15551234567",
15    to: "whatsapp:+18551234567",
16  });
17
18  console.log(message.body);
19}
20
21createMessage();

Response

1{
2  "account_sid": "ACXXXXXXXXX",
3  "api_version": "2010-04-01",
4  "body": "Hello! 👍",
5  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8  "direction": "outbound-api",
9  "error_code": null,
10  "error_message": null,
11  "from": "whatsapp:+15551234567",
12  "num_media": "0",
13  "num_segments": "1",
14  "price": null,
15  "price_unit": null,
16  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "queued",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21  },
22  "to": "whatsapp:+18551234567",
23  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24}

To send a content template, replace the Body field with ContentSid and, optionally, ContentVariables. The following table describes the required fields for this method:

Field	Required	Description
`From`	Yes	The sender initiating the message. Use the following format: Phone numbers: E.164 format WhatsApp: `whatsapp:E.164` Facebook Messenger: `messenger:{messenger_id}`
`To`	Yes	The identifier of the recipient you're sending the message to. Use the following format: Phone numbers: E.164 format WhatsApp: `whatsapp:E.164` Facebook Messenger: `messenger:{messenger_id}`
`ContentSid`	Yes	String field used to identify the preconfigured content. Required to send templates created using the Content Template Builder.
`ContentVariables`	No	JSON string used to define the values of any placeholder variables found in the preconfigured content. Key-value pairs of placeholder variable names and substitution values.

Use Messaging Services to send content templates

You can also use a Messaging Service to send content templates. Using Messaging Services can help you organize your account and manage complexity as your messaging application grows. To learn more about Messaging Services features, see Messaging Services.

Twilio ConsoleLegacy Twilio Console

To create a Messaging Service:

Go to the Products & Services > Messaging > Services.
Click Create a Messaging Service, enter a name, select what you want to use the service for and click Create.
The service's overview page appears. From there, copy the Messaging Service SID, which starts with MGXXXXXXXX.

You can send a template created with the Content Template Builder using two methods:

Use the From field to specify the Messaging Service SID
Include a MessagingServiceSid field

Send messages with a Messaging Service in the `From` field

The following example shows how to send a message using a Messaging Service in the From field:

(warning)

Exclude Body and MediaUrl parameters

Exclude Body and MediaUrl; ContentSid replaces both parameters.

The body in the response is empty because the body resides in the template. To view the delivered body, open the Twilio logs in the Console.

Send messages with a Messaging Service in the From field

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    contentSid: "HXXXXXXXXX",
13    contentVariables: JSON.stringify({ 1: "Name" }),
14    from: "MGXXXXXXXX",
15    to: "whatsapp:+18551234567",
16  });
17
18  console.log(message.body);
19}
20
21createMessage();

Response

1{
2  "account_sid": "ACXXXXXXXX",
3  "api_version": "2010-04-01",
4  "body": "Hello! 👍",
5  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8  "direction": "outbound-api",
9  "error_code": null,
10  "error_message": null,
11  "from": "MGXXXXXXXX",
12  "num_media": "0",
13  "num_segments": "1",
14  "price": null,
15  "price_unit": null,
16  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "queued",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21  },
22  "to": "whatsapp:+18551234567",
23  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24}

This method requires adding a sender to a Messaging Service. Use this approach if you plan to scale your traffic with multiple senders.

How to add senders to the sender pool

Each Messaging Service has a sender pool that contains all the senders associated with the service. You can view your senders in the Senders tab of your Messaging Service.

(information)

Add a sender to a Messaging Service in the legacy Twilio Console

Go to the Messaging Service.
In the Develop tab, click on Sender Pool.
Click Add Senders.

Messaging Services support the following sender types:

Phone numbers
Short codes
Alphanumeric senders
WhatsApp senders
Facebook Messenger senders

(information)

Facebook Messenger senders

If you don't see an option for Facebook Messenger, file a support ticket to activate the "Facebook Messenger with Messaging Services feature." For more information, see our Facebook Messenger with Twilio documentation.

The following table summarizes all the fields used in the API request:

Field	Required	Description
`From`	Yes	The Messaging Service SID, `MGXXXXXXXX`.
`To`	Yes	The identifier of the recipient you're sending the message to. Use the following format: Phone numbers: E.164 format WhatsApp: `whatsapp:E.164` Facebook Messenger: `messenger:{messenger_id}`
`ContentSid`	Yes	String field used to identify the preconfigured content. Required to send templates created using Content Template Builder.
`ContentVariables`	No	JSON string used to define the values of any placeholder variables found in the preconfigured content. Key-value pairs of placeholder variable names and substitution values.

Send messages with `MessagingServiceSid` and `From` fields

The following example shows how to send a message using both MessagingServiceSid and From fields:

Send messages with a MessagingServiceSid field

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    contentSid: "HXXXXXXXXX",
13    contentVariables: JSON.stringify({ 1: "Name" }),
14    from: "whatsapp:+15551234567",
15    messagingServiceSid: "MGXXXXXXXX",
16    to: "whatsapp:+18551234567",
17  });
18
19  console.log(message.body);
20}
21
22createMessage();

Response

1{
2  "account_sid": "ACXXXXXXXXX",
3  "api_version": "2010-04-01",
4  "body": "Hello! 👍",
5  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8  "direction": "outbound-api",
9  "error_code": null,
10  "error_message": null,
11  "from": "whatsapp:+15551234567",
12  "num_media": "0",
13  "num_segments": "1",
14  "price": null,
15  "price_unit": null,
16  "messaging_service_sid": "MGXXXXXXXX",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "queued",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21  },
22  "to": "whatsapp:+18551234567",
23  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24}

This method lets you keep using the From field to specify the sender ID. You need to reference a Messaging Service by including a new MessagingServiceSid field. Note that while a Messaging Service is required, you don't have to add the sender to its sender pool. This method may be simpler if you're getting started with Messaging Services.

The following table describes all the fields used in the API request:

Field	Required	Description
`From`	Yes	The sender that's initiating the message. Use the following format: Phone numbers: E.164 format WhatsApp: `whatsapp:E.164` Facebook Messenger: `messenger:{messenger_id}`
`To`	Yes	The identifier of the recipient you're sending the message to. Use the following format: Phone numbers: E.164 format WhatsApp: `whatsapp:E.164` Facebook Messenger: `messenger:{messenger_id}`
`MessagingServiceSid`	Yes	The Messaging Service SID, `MGXXXXXXXX`.
`ContentSid`	Yes	String field used to identify the preconfigured content. Required to send templates created using the Content Template Builder.
`ContentVariables`	No	JSON string used to define the values of any placeholder variables found in the preconfigured content. Key-value pairs of placeholder variable names and substitution values.

Send templates created with the Content Template Builder

Content fields used to send messages

You must use a WhatsApp-approved template

Send content templates

Exclude Body and MediaUrl parameters

Response

Use Messaging Services to send content templates

Send messages with a Messaging Service in the From field

Exclude Body and MediaUrl parameters

Response

How to add senders to the sender pool

Add a sender to a Messaging Service in the *legacy* Twilio Console

Facebook Messenger senders

Send messages with MessagingServiceSid and From fields

Response

Send messages with a Messaging Service in the `From` field

Add a sender to a Messaging Service in the legacy Twilio Console

Send messages with `MessagingServiceSid` and `From` fields