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.
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
New 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. |
If you are sending a WhatsApp message outside the 24-hour free-form session, you need to use a template approved by WhatsApp. Learn more.
Body and MediaUrl should be excluded. They are both not required. They are both superseded by the ContentSid
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createMessage() {11const message = await client.messages.create({12contentSid: "HXXXXXXXXX",13contentVariables: JSON.stringify({ 1: "Name" }),14from: "whatsapp:+15551234567",15to: "whatsapp:+18551234567",16});1718console.log(message.body);19}2021createMessage();
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 that is initiating the message. Use e.164 format for phone numbers, "whatsapp:e.164 " for WhatsApp, and "messenger:{messenger_id} " for FB Messenger. |
To | Yes | The identifier of the recipient you are sending the message to. Use e.164 format for phone numbers, whatsapp:e.164 for WhatsApp, and messenger:messenger_id for FB Messenger. |
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. |
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. Learn more about Messaging Services features here.
To create a messaging service, head to the Messaging > Services section of the Twilio Console. Check out the 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:
MessagingServiceSid
field, or
From
field to specify the Messaging Service Sid
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createMessage() {11const message = await client.messages.create({12contentSid: "HXXXXXXXXX",13contentVariables: JSON.stringify({ 1: "Name" }),14from: "MGXXXXXXXX",15to: "whatsapp:+18551234567",16});1718console.log(message.body);19}2021createMessage();
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.
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, find the "Sender Pool" Section on the left and click "Add Sender".
Messaging Services support Phone Numbers, Short Codes, Alpha Senders, WhatsApp Senders and Facebook Messenger Senders. If you do not see an option for FB Messenger, file a support ticket asking to enable the "FBM with messaging services feature". Read our Facebook Messenger with Twilio documentation for more information.
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 e.164 format for phone numbers, "whatsapp:e.164 " for WhatsApp, and "messenger:{messenger_id} " for FB Messenger. |
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. |
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createMessage() {11const message = await client.messages.create({12contentSid: "HXXXXXXXXX",13contentVariables: JSON.stringify({ 1: "Name" }),14from: "whatsapp:+15551234567",15messagingServiceSid: "MGXXXXXXXX",16to: "whatsapp:+18551234567",17});1819console.log(message.body);20}2122createMessage();
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 do not 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 is initiating the message. Use e.164 format for phone numbers, "whatsapp:e.164 " for WhatsApp, and "messenger:{messenger_id} " for FB Messenger. |
To | Yes | The identifier of the recipient you are sending the message to. Use e.164 format for phone numbers, whatsapp:e.164 for WhatsApp, and messenger:{messenger_id} for FB Messenger. |
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. |