Content API Public Endpoints


(information)

Info

While the Content API supports an unlimited number of content templates, WhatsApp limits users to 6000 approved templates. Large parts of this page refer to v1 of the Content API. Content template search only applies to v2.

Property nameTypeRequiredDescriptionChild properties
dateCreatedstring<date-time>

Optional

The date and time in GMT that the resource was created specified in RFC 2822(link takes you to an external page) format.


dateUpdatedstring<date-time>

Optional

The date and time in GMT that the resource was last updated specified in RFC 2822(link takes you to an external page) format.


sidSID<HX>

Optional

The unique string that that we created to identify the Content resource.

Pattern: ^HX[0-9a-fA-F]{32}$Min length: 34Max length: 34

accountSidSID<AC>

Optional

The SID of the Account that created Content resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

friendlyNamestring

Optional

A string name used to describe the Content resource. Not visible to the end recipient.


languagestring

Optional

Two-letter (ISO 639-1) language code (e.g., en) identifying the language the Content resource is in.


variables

Optional

Defines the default placeholder values for variables included in the Content resource. e.g. {"1": "Customer_Name"}.


types

Optional

The Content types (e.g. twilio/text) for this Content resource.


urlstring<uri>

Optional

The URL of the resource, relative to https://content.twilio.com.


linksobject<uri-map>

Optional

A list of links related to the Content resource, such as approval_fetch and approval_create


Create a Content API template

create-a-content-api-template page anchor
POST https://content.twilio.com/v1/Content
(information)

Info

We recommend that you save the Content SID that can be found in the API response to use for later. This SID is used during send time and in various other requests to identify the template.

1
// Install the C# / .NET helper library from twilio.com/docs/csharp/install
2
3
using System;
4
using Twilio;
5
using Twilio.Rest.Content.V1;
6
7
TwilioClient.Init(accountSid, authToken);
8
9
// define the twilio/text type for less rich channels (e.g. SMS)
10
var twilioText = new TwilioText.Builder();
11
twilioText.WithBody("Hi {{1}}. Thanks for contacting Owl Air Support. How can we help?");
12
13
// define the twilio/quick-reply type for more rich channels
14
var twilioQuickReply = new TwilioQuickReply.Builder();
15
twilioQuickReply.WithBody("Owl Air Support");
16
var quickreply1 = new QuickReplyAction.Builder()
17
.WithTitle("Contact Us")
18
.WithId("flightid1")
19
.Build();
20
var quickreply2 = new QuickReplyAction.Builder()
21
.WithTitle("Check gate number")
22
.WithId("gateid1")
23
.Build();
24
var quickreply3 = new QuickReplyAction.Builder()
25
.WithTitle("Speak with an agent")
26
.WithId("agentid1")
27
.Build();
28
twilioQuickReply.WithActions(new List<QuickReplyAction>() { quickreply1, quickreply2, quickreply3 });
29
30
// define all the content types to be part of the template
31
var types = new Types.Builder();
32
types.WithTwilioText(twilioText.Build());
33
types.WithTwilioQuickReply(twilioQuickReply.Build());
34
35
// build the create request object
36
var contentCreateRequest = new ContentCreateRequest.Builder();
37
contentCreateRequest.WithTypes(types.Build());
38
contentCreateRequest.WithLanguage("en");
39
contentCreateRequest.WithFriendlyName("owl_air_qr");
40
contentCreateRequest.WithVariables(new Dictionary<string, string>() { {"1", "John"} });
41
42
// create the twilio template
43
var contentTemplate = await CreateAsync(contentCreateRequest.Build());
44
45
Console.WriteLine($"Created Twilio Content Template SID: {contentTemplate.Sid}");

Output

1
{
2
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
"date_created": "2022-08-29T10:43:20Z",
4
"date_updated": "2022-08-29T10:43:20Z",
5
"friendly_name": "owl_air_qr",
6
"language": "en",
7
"links": {
8
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp",
9
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests"
10
},
11
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
"types": {
13
"twilio/text": {
14
"body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?."
15
},
16
"twilio/quick-reply": {
17
"body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?",
18
"actions": [
19
{
20
"id": "flightid1",
21
"title": "Check flight status"
22
},
23
{
24
"id": "gateid1",
25
"title": "Check gate number"
26
},
27
{
28
"id": "agentid1",
29
"title": "Speak with an agent"
30
}
31
]
32
}
33
},
34
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
35
"variables": {
36
"1": "Owl Air Customer"
37
}
38
}

Fetch information about templates

fetch-information-about-templates page anchor

Fetch a content resource

fetch-a-content-resource page anchor
GET https://content.twilio.com/v1/Content/{ContentSid}

Retrieve information about a single Content API template.

Property nameTypeRequiredPIIDescription
sidSID<HX>
required

The Twilio-provided string that uniquely identifies the Content resource to fetch.

Pattern: ^HX[0-9a-fA-F]{32}$Min length: 34Max length: 34
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchContent() {
11
const content = await client.content.v1
12
.contents("HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.fetch();
14
15
console.log(content.dateCreated);
16
}
17
18
fetchContent();

Response

1
{
2
"sid": "HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"friendly_name": "Some content",
5
"language": "en",
6
"variables": {
7
"name": "foo"
8
},
9
"types": {
10
"twilio/text": {
11
"body": "Foo Bar Co is located at 39.7392, 104.9903"
12
},
13
"twilio/location": {
14
"longitude": 104.9903,
15
"latitude": 39.7392,
16
"label": "Foo Bar Co"
17
}
18
},
19
"url": "https://content.twilio.com/v1/Content/HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
20
"date_created": "2015-07-30T19:00:00Z",
21
"date_updated": "2015-07-30T19:00:00Z",
22
"links": {
23
"approval_create": "https://content.twilio.com/v1/Content/HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ApprovalRequests/whatsapp",
24
"approval_fetch": "https://content.twilio.com/v1/Content/HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ApprovalRequests"
25
}
26
}

Template search (v2)

template-search-v2 page anchor
FiltersNumber of filtersBehavior
LanguageMultiplePick multiple options of supported languages that matches the template's language field.
ContentTypeMultiplePick multiple options of supported content types. This checks for the existence of contenttype fields e.g. twilio/text
ChannelEligibilityMultiplePick multiple options of the supported {channel}:{template_status} format which refers to the approval_content.channel.status field
ContentSingleCase-insensitive search pattern in the body, title, sub_title, friendly_name, approval_content.channel.name fields. Max character length: 1024. Max number of words: 30. Document will return with 100% match. Matches the order of words in friendly_name, approval_content.whatsapp.name.
ContentNameSinglePattern to search for in the friendly_name (content template name) and approval_content.channel.name fields. Max character length: 450. Max number of words allowed: 30.
DateCreatedBeforeSingleDate and time value before template creation to be used in your content templates search. Format example: DateCreatedBefore=YYYY-MM-DDThh:mm:ssZ
DateCreatedAfterSingleDate and time value after template creation to be used in your content templates search. Format example: DateCreatedAfter=YYYY-MM-DDThh:mm:ssZ
DateCreatedBefore, DateCreatedAfterSingleSpecify a datetime range for your content templates search. Format example: DateCreatedBefore=YYYY-MM-DDThh:mm:ssZ&DateCreatedAfter=YYYY-MM-DDThh:mm:ssZ
GET "https://content.twilio.com/v2/Content?PageSize=100&Content=hello"
GET "https://content.twilio.com/v2/ContentAndApprovals?ChannelEligibility=whatsapp:unsubmitted&Language=en"

Fetch all content resources

fetch-all-content-resources page anchor
GET "https://content.twilio.com/v1/Content"

Retrieve all content templates. Pagination is supported in this endpoint.

1
curl -X GET "https://content.twilio.com/v1/Content"
2
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Output

1
{
2
"meta": {
3
"page": 0,
4
"page_size": 50,
5
"first_page_url": "https://content.twilio.com/v1/Content?PageSize=50&Page=0",
6
"previous_page_url": null,
7
"url": "https://content.twilio.com/v1/Content?PageSize=50&Page=0",
8
"next_page_url": "https://content.twilio.com/v1/Content?PageSize=50&Page=1&PageToken=DNHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-1678723520",
9
"key": "contents"
10
},
11
"contents": [
12
{
13
"language": "en",
14
"date_updated": "2023-03-31T16:06:50Z",
15
"variables": {
16
"1": "07:00",
17
"3": "owl.jpg",
18
"2": "03/01/2023"
19
},
20
"friendly_name": "whatsappcard2",
21
"account_sid": "ACXXXXXXXXXXXXXXX",
22
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
23
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
24
"date_created": "2023-03-31T16:06:50Z",
25
"types": {
26
"twilio/card": {
27
"body": null,
28
"media": [
29
"https://twilio.example.com/{{3}}"
30
],
31
"subtitle": null,
32
"actions": [
33
{
34
"index": 0,
35
"type": "QUICK_REPLY",
36
"id": "Stop",
37
"title": "Stop Updates"
38
}
39
],
40
"title": "See you at {{1}} on {{2}}. Thank you."
41
}
42
},
43
"links": {
44
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests",
45
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp"
46
}
47
},
48
{
49
"language": "en",
50
"date_updated": "2023-03-31T15:50:24Z",
51
"variables": {
52
"1": "07:00",
53
"2": "03/01/2023"
54
},
55
"friendly_name": "whatswppward_01234",
56
"account_sid": "ACXXXXXXXXXXXXXXX",
57
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
58
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
59
"date_created": "2023-03-31T15:50:24Z",
60
"types": {
61
"twilio/card": {
62
"body": null,
63
"media": [
64
"https://twilio.example.com/owl.jpg"
65
],
66
"subtitle": null,
67
"actions": [
68
{
69
"index": 0,
70
"type": "QUICK_REPLY",
71
"id": "Stop",
72
"title": "Stop Updates"
73
}
74
],
75
"title": "See you at {{1}} on {{2}}. Thank you."
76
}
77
},
78
"links": {
79
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests",
80
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp"
81
}
82
}
83
]
84
}

Fetch content and approvals

fetch-content-and-approvals page anchor
GET https://content.twilio.com/v1/ContentAndApprovals

Retrieve information about templates and their approval status. The WhatsApp Flow publish status will be returned in the approvals object. Pagination is supported in this endpoint.

To learn more, see WhatsApp approval statuses.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function listContentAndApprovals() {
11
const contentAndApprovals = await client.content.v1.contentAndApprovals.list({
12
limit: 20,
13
});
14
15
contentAndApprovals.forEach((c) => console.log(c.dateCreated));
16
}
17
18
listContentAndApprovals();

Response

1
{
2
"contents": [],
3
"meta": {
4
"page": 0,
5
"page_size": 10,
6
"first_page_url": "https://content.twilio.com/v1/ContentAndApprovals?PageSize=10&Page=0",
7
"previous_page_url": null,
8
"next_page_url": null,
9
"url": "https://content.twilio.com/v1/ContentAndApprovals?PageSize=10&Page=0",
10
"key": "contents"
11
}
12
}

Fetch mapping between legacy WhatsApp and content templates

fetch-mapping-between-legacy-whatsapp-and-content-templates page anchor
GET https://content.twilio.com/v1/LegacyContent

For customers that have had their templates synced over from WA templates you can retrieve a mapping between all the templates, their language and body text and their new Content Sids.

  • Pagination is supported in this endpoint.
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function listLegacyContent() {
11
const legacyContents = await client.content.v1.legacyContents.list({
12
limit: 20,
13
});
14
15
legacyContents.forEach((l) => console.log(l.dateCreated));
16
}
17
18
listLegacyContent();

Response

1
{
2
"contents": [],
3
"meta": {
4
"page": 0,
5
"page_size": 10,
6
"first_page_url": "https://content.twilio.com/v1/LegacyContent?PageSize=10&Page=0",
7
"previous_page_url": null,
8
"url": "https://content.twilio.com/v1/LegacyContent?PageSize=10&Page=0",
9
"next_page_url": null,
10
"key": "contents"
11
}
12
}

For endpoints where pagination is supported you can append the following parameters to the request URL to paginate the results. The limit of page size is 1 MB of data. This is typically ~500 templates. If you aren't seeing some templates, please reduce your page size and pull the data in multiple pages.

  • PageSize: Recommended Limit 500
  • PageToken: Equivalent to page number starting with page=0. To navigate to the next page use the page token referenced the meta.next_page_url field at the bottom of the returned results. Entering the next page in a page= field won't work. Only PageToken is supported.

Delete a content template

delete-a-content-template page anchor
DELETE https://content.twilio.com/v1/Content/{ContentSid}
Property nameTypeRequiredPIIDescription
sidSID<HX>
required

The Twilio-provided string that uniquely identifies the Content resource to fetch.

Pattern: ^HX[0-9a-fA-F]{32}$Min length: 34Max length: 34
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function deleteContent() {
11
await client.content.v1.contents("HXXXXXXXX").remove();
12
}
13
14
deleteContent();

Submit templates for approval

submit-templates-for-approval page anchor

Submit a template approval for WhatsApp

submit-a-template-approval-for-whatsapp page anchor
(information)

Info

By default, to send outbound messages to WhatsApp users, a template approval by WhatsApp is required. However, if a WhatsApp user sends an inbound message, then a 24-hour messaging session is initiated and certain outbound rich content types can be sent without a template.

For details regarding which content types require approval and 24-hour session limitations, please refer to the following chart.

To use your content template on WhatsApp, you can request approval by submitting a request along with additional information required by WhatsApp. To ensure your WhatsApp templates are approved please see our guide WhatsApp Notification Messages with Templates. Approval by WhatsApp typically takes 1 business day.

POST https://content.twilio.com/v1/Content/{ContentSid}/ApprovalRequests/WhatsApp
ParameterTypeRequiredDescription
content_sidstringYesContent resource you want to submit for approval.

Additional parameters required by WhatsApp

additional-parameters-required-by-whatsapp page anchor
ParameterTypeRequiredDescription
namestringYesName that uniquely identifies the Content. Only lowercase alphanumeric characters or underscores.
categoryenumYesUse case category the Content corresponds to, as defined by WhatsApp(link takes you to an external page).
The following are the available WhatsApp categories:
  • UTILITY
  • MARKETING
  • AUTHENTICATION
1
curl -X POST 'https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp' \
2
-H 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4
-d '{
5
"name": "flight_replies",
6
"category": "UTILITY"
7
}'

Output

1
{
2
"category": "TRANSPORTATION_UPDATE",
3
"status": "received",
4
"rejection_reason": "",
5
"name": "flight_replies",
6
"content_type": "twilio/quick-reply"
7
}

Fetch an approval status request

fetch-an-approval-status-request page anchor
GET https://content.twilio.com/v1/Content/{ContentSid}/ApprovalRequests

All WhatsApp approval statuses can be found here. Flow status will begin to be returned in the approvals object.

Property nameTypeRequiredPIIDescription
sidSID<HX>
required

The Twilio-provided string that uniquely identifies the Content resource whose approval information to fetch.

Pattern: ^HX[0-9a-fA-F]{32}$Min length: 34Max length: 34
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchApprovalFetch() {
11
const approvalFetch = await client.content.v1
12
.contents("HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.approvalFetch()
14
.fetch();
15
16
console.log(approvalFetch.sid);
17
}
18
19
fetchApprovalFetch();

Response

1
{
2
"sid": "HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"whatsapp": {
5
"type": "whatsapp",
6
"name": "tree_fiddy",
7
"category": "UTILITY",
8
"content_type": "twilio/location",
9
"status": "approved",
10
"rejection_reason": "",
11
"allow_category_change": true
12
},
13
"url": "https://content.twilio.com/v1/Content/HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ApprovalRequests"
14
}

Send a message with preconfigured content

send-a-message-with-preconfigured-content page anchor
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages

To send messages you will use the content SID message body and your Twilio account SID in the POST request URL. For templates that use variables, please specify these variables in the POST request to send messages.

Property nameTypeRequiredPIIDescription
accountSidSID<AC>
required

The SID of the Account creating the Message resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
tostring<phone-number>
required

The recipient's phone number in E.164 format (for SMS/MMS) or channel address, e.g. whatsapp:+15552229999.


statusCallbackstring<uri>

Optional

The URL of the endpoint to which Twilio sends Message status callback requests. URL must contain a valid hostname and underscores are not allowed. If you include this parameter with the messaging_service_sid, Twilio uses this URL instead of the Status Callback URL of the Messaging Service.


applicationSidSID<AP>

Optional

The SID of the associated TwiML Application. Message status callback requests are sent to the TwiML App's message_status_callback URL. Note that the status_callback parameter of a request takes priority over the application_sid parameter; if both are included application_sid is ignored.

Pattern: ^AP[0-9a-fA-F]{32}$Min length: 34Max length: 34

maxPricenumber

Optional

[OBSOLETE] This parameter will no longer have any effect as of 2024-06-03.


provideFeedbackboolean

Optional

Boolean indicating whether or not you intend to provide delivery confirmation feedback to Twilio (used in conjunction with the Message Feedback subresource). Default value is false.


attemptinteger

Optional

Total number of attempts made (including this request) to send the message regardless of the provider used


validityPeriodinteger

Optional

The maximum length in seconds that the Message can remain in Twilio's outgoing message queue. If a queued Message exceeds the validity_period, the Message is not sent. Accepted values are integers from 1 to 36000. Default value is 36000. A validity_period greater than 5 is recommended. Learn more about the validity period(link takes you to an external page)


forceDeliveryboolean

Optional

Reserved


contentRetentionenum<string>

Optional

Possible values:
retaindiscard

addressRetentionenum<string>

Optional

Possible values:
retainobfuscate

smartEncodedboolean

Optional

Whether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: true or false.


persistentActionarray[string]

Optional

Rich actions for non-SMS/MMS channels. Used for sending location in WhatsApp messages.


trafficTypeenum<string>

Optional

Possible values:
free

shortenUrlsboolean

Optional

For Messaging Services with Link Shortening configured only: A Boolean indicating whether or not Twilio should shorten links in the body of the Message. Default value is false. If true, the messaging_service_sid parameter must also be provided.


scheduleTypeenum<string>

Optional

Possible values:
fixed

sendAtstring<date-time>

Optional

The time that Twilio will send the message. Must be in ISO 8601 format.


sendAsMmsboolean

Optional

If set to true, Twilio delivers the message as a single MMS message, regardless of the presence of media.


contentVariablesstring

Optional

For Content Editor/API only: Key-value pairs of Template variables and their substitution values. content_sid parameter must also be provided. If values are not defined in the content_variables parameter, the Template's default placeholder values are used.


riskCheckenum<string>

Optional

Possible values:
enabledisable

fromstring<phone-number>
required if MessagingServiceSid is not passed

The sender's Twilio phone number (in E.164(link takes you to an external page) format), alphanumeric sender ID, Wireless SIM, short code(link takes you to an external page), or channel address (e.g., whatsapp:+15554449999). The value of the from parameter must be a sender that is hosted within Twilio and belongs to the Account creating the Message. If you are using messaging_service_sid, this parameter can be empty (Twilio assigns a from value from the Messaging Service's Sender Pool) or you can provide a specific sender from your Sender Pool.


messagingServiceSidSID<MG>
required if From is not passed

The SID of the Messaging Service you want to associate with the Message. When this parameter is provided and the from parameter is omitted, Twilio selects the optimal sender from the Messaging Service's Sender Pool. You may also provide a from parameter if you want to use a specific Sender from the Sender Pool.

Pattern: ^MG[0-9a-fA-F]{32}$Min length: 34Max length: 34

bodystring
required if MediaUrl or ContentSid is not passed

The text content of the outgoing message. Can be up to 1,600 characters in length. SMS only: If the body contains more than 160 GSM-7 characters (or 70 UCS-2 characters), the message is segmented and charged accordingly. For long body text, consider using the send_as_mms parameter(link takes you to an external page).


mediaUrlarray[string<uri>]
required if Body or ContentSid is not passed

The URL of media to include in the Message content. jpeg, jpg, gif, and png file types are fully supported by Twilio and content is formatted for delivery on destination devices. The media size limit is 5 MB for supported file types (jpeg, jpg, png, gif) and 500 KB for other types of accepted media. To send more than one image in the message, provide multiple media_url parameters in the POST request. You can include up to ten media_url parameters per message. International(link takes you to an external page) and carrier(link takes you to an external page) limits apply.


contentSidSID<HX>
required if Body or MediaUrl is not passed

For Content Editor/API only: The SID of the Content Template to be used with the Message, e.g., HXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. If this parameter is not provided, a Content Template is not used. Find the SID in the Console on the Content Editor page. For Content API users, the SID is found in Twilio's response when creating the Template or by fetching your Templates.

Pattern: ^HX[0-9a-fA-F]{32}$Min length: 34Max length: 34
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createMessage() {
11
const message = await client.messages.create({
12
contentSid: "HXXXXXXXX",
13
contentVariables: JSON.stringify({
14
1: "YOUR_VARIABLE1",
15
2: "YOURVARIABLE2",
16
}),
17
from: "MGXXXXXXXXX",
18
to: "whatsapp:+18005551234",
19
});
20
21
console.log(message.sid);
22
}
23
24
createMessage();

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": "MGXXXXXXXXX",
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:+18005551234",
27
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}
(warning)

Warning

The From field in the POST request to the Programmable Messaging API must include a Messaging Service that includes a WhatsApp or Facebook Messenger sender.

Send templates using status callbacks

send-templates-using-status-callbacks page anchor

Status callback URLs can be set for all messages in a Messaging Service(link takes you to an external page) (under the Integration settings for a specific Messaging Service) or when you send an individual outbound message, by including the StatusCallback parameter. To learn more about status callback URLs, see Monitor the status of your WhatsApp outbound message.

1
-d "StatusCallback=http://postb.in/1234abcd" \
2

Send messages scheduled ahead of time

send-messages-scheduled-ahead-of-time page anchor

With content templates, you can schedule SMS, MMS, and WhatsApp messages to be sent at a fixed time in the future.

Scheduling a message is free. You'll only pay for a message once it's sent.

To learn more, see message scheduling.

1
--data-urlencode "SendAt=2021-11-30T20:36:27Z" \
2
--data-urlencode "ScheduleType=fixed" \
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createMessage() {
11
const message = await client.messages.create({
12
contentSid: "HXXXXXXXXXXXXXXX",
13
contentVariables: JSON.stringify({
14
1: "YOUR_VARIABLE1",
15
2: "YOURVARIABLE2",
16
}),
17
messagingServiceSid: "MGXXXXXXXXXXX",
18
scheduleType: "fixed",
19
sendAt: new Date("2023-11-30 20:36:27"),
20
to: "whatsapp:+18005551234",
21
});
22
23
console.log(message.body);
24
}
25
26
createMessage();

Response

1
{
2
"account_sid": "ACXXXXXXXXXX",
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": "+14155552345",
12
"num_media": "0",
13
"num_segments": "1",
14
"price": null,
15
"price_unit": null,
16
"messaging_service_sid": "MGXXXXXXXXXXX",
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:+18005551234",
27
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

Template status change alerts

template-status-change-alerts page anchor

Twilio supports error codes for "Alarms", "Rejected", and "Paused" WhatsApp Templates. With Twilio Alarms, you can receive webhook or email notifications when errors occur. Approved alarms are also available as a Beta feature.

For more information, see alerts for Rejected and Paused WhatsApp Templates(link takes you to an external page).