Send templates created with the Content Template Builder

To send messages from templates created using the Content Template Builder, you will need two new fields in your API request. You will also need to first configure a Messaging Service and create your content template.

New content fields used to send messages

You will utilize the existing messaging endpoint with an additional field, ContentSid. You may also include the ContentVariables field to substitute any placeholder values in your templates.

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

Field	Required	Description
`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. Content templates support up to 100 key-value pairs per send request.

(information)

Info

If you are sending a WhatsApp message outside the 24-hour free-form session, you need to use a template approved by WhatsApp. To learn more, see Content API quick start.

Send content templates

(warning)

Warning

Body and MediaUrl should be excluded. They are both not required. They are both superseded by the ContentSid. You might need to update your library to use the ContentSid parameter.

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  "tags": {
23    "campaign_name": "Spring Sale 2022",
24    "message_type": "cart_abandoned"
25  },
26  "to": "whatsapp:+18551234567",
27  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28}

The primary method of sending a content template is to replace the body field with ContentSid and ContentVariables fields:

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 are 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. Messaging Services are also a great tool to organize your account and reduce complexity as your messaging application grows. To learn more Messaging Services features, see Messaging Services.

To create a Messaging Service, head to the Messaging > Services section of the Twilio Console. See Content API quick start for a detailed guide.

Now grab your Messaging Service's Sid by going to the Twilio Console > Services and finding the Sid.

Next, we will review the two ways to send a template created with the Content Template Builder:

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

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

(warning)

Warning

Body and MediaUrl should be excluded. They are both not required. They are both superseded by the ContentSid.

The body in the response will be empty. Since this is a templated message, the body is in the template. If you would like to see the body that was delivered they can view it in the Twilio logs in 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  "tags": {
23    "campaign_name": "Spring Sale 2022",
24    "message_type": "cart_abandoned"
25  },
26  "to": "whatsapp:+18551234567",
27  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28}

This method requires adding a Sender to a Messaging Service. This approach is recommended if you plan to scale your traffic with multiple senders.

How to add senders to a your sender pool

Each Messaging Service has a "Sender Pool" that contains all the senders that can access that service's configurations.

To add a sender to a Messaging Service, you need to add it to its Sender Pool:

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

Messaging Services support the following:

Phone numbers
Short codes
Alpha senders
WhatsApp Senders
Facebook Messenger Senders.

(information)

Info

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

Here is a summary of 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 are sending the message to. Use the following format: Phone numbers: E.164 format WhatsApp: `whatsapp:E.164` Facebook Messenger: `messenger:{messenger_id}`
`ContentSid` new	-	String field used to identify the preconfigured content. Required to send templates created using Content Template Builder.
`ContentVariables` new	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 a `MessagingServiceSid` field and a `From` field

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  "tags": {
23    "campaign_name": "Spring Sale 2022",
24    "message_type": "cart_abandoned"
25  },
26  "to": "whatsapp:+18551234567",
27  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28}

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 (more on this later). This may be an easier way to get started if you are new to Messaging Services.

Here are 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 are sending the message to. Use the following format: Phone numbers: E.164 format WhatsApp: `whatsapp:E.164` Facebook Messenger: `messenger:{messenger_id}`
`MessagingServiceSid` new	Yes	The Messaging Service SID, `MGXXXXXXXX`.
`ContentSid` new	Yes	String field used to identify the preconfigured content. Required to send templates created using the Content Template Builder.
`ContentVariables` new	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

New content fields used to send messages

Info

Send content templates

Warning

Response

Use Messaging Services to send content templates

Send messages with a Messaging Service in the From field

Warning

Response

How to add senders to a your sender pool

Info

Send Messages with a MessagingServiceSid field and a From field

Response

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

Send Messages with a `MessagingServiceSid` field and a `From` field