Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this pageProducts used

Content API Public Endpoints


(information)

Info

The Content API supports an unlimited number of templates, however WhatsApp limits users to 6000 approved templates.

date_createdstring<date-time>
Not PII

date_updatedstring<date-time>

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>

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

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

account_sidSID<AC>

The SID of the Account(link takes you to an external page) that created Content resource.

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

friendly_namestring

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


languagestring

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


variablesobject

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


typesobject

The Content types(link takes you to an external page) (e.g. twilio/text) for this Content resource.


urlstring<uri>

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


linksobject<uri-map>

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


Creation of Templates

creation-of-templates page anchor

Create Templates

create-templates page anchor

_10
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.

Create Content API Templates

create-content-api-templates page anchor

Code sample for creating a template using content API

curl

_30
curl -X POST 'https://content.twilio.com/v1/Content' \
_30
-H 'Content-Type: application/json' \
_30
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
_30
-d '{
_30
"friendly_name": "flight_replies",
_30
"language": "en",
_30
"variables": {"1":"Owl Air Customer"},
_30
"types": {
_30
"twilio/quick-reply": {
_30
"body": "Hi, {{1}} 👋 \nThanks for contacting Owl Air Support. How can I help?",
_30
"actions": [
_30
{
_30
"title": "Check flight status",
_30
"id": "flightid1"
_30
},
_30
{
_30
"title": "Check gate number",
_30
"id": "gateid1"
_30
},
_30
{
_30
"title": "Speak with an agent",
_30
"id": "agentid1"
_30
}
_30
]
_30
},
_30
"twilio/text": {
_30
"body": "Hi, {{1}}. \n Thanks for contacting Owl Air Support. How can I help?."
_30
}
_30
}
_30
}'

Output

_38
{
_38
"language": "en",
_38
"date_updated": "2022-08-29T10:43:20Z",
_38
"variables": {
_38
"1": "Owl Air Customer"
_38
},
_38
"friendly_name": "flight_replies",
_38
"account_sid": "ACXXXXXXXXXXXXXXXXXXX",
_38
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"date_created": "2022-08-29T10:43:20Z",
_38
"types": {
_38
"twilio/text": {
_38
"body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?."
_38
},
_38
"twilio/quick-reply": {
_38
"body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?",
_38
"actions": [
_38
{
_38
"id": "flightid1",
_38
"title": "Check flight status"
_38
},
_38
{
_38
"id": "gateid1",
_38
"title": "Check gate number"
_38
},
_38
{
_38
"id": "agentid1",
_38
"title": "Speak with an agent"
_38
}
_38
]
_38
}
_38
},
_38
"links": {
_38
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests",
_38
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp"
_38
}
_38
}


Fetch Information About Templates

fetch-information-about-templates page anchor

Fetch a Content Resource

fetch-a-content-resource page anchor

_10
GET https://content.twilio.com/v1/Content/{ContentSid}

Retrieve information about a single Content API template.

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

Fetch a Content API Resource

fetch-a-content-api-resource page anchor

Review an individual template created using Content API

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.content.v1.contents('HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(content => console.log(content.friendlyName));

Output

_26
{
_26
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26
"friendly_name": "Some content",
_26
"language": "en",
_26
"variables": {
_26
"name": "foo"
_26
},
_26
"types": {
_26
"twilio/text": {
_26
"body": "Foo Bar Co is located at 39.7392, 104.9903"
_26
},
_26
"twilio/location": {
_26
"longitude": 104.9903,
_26
"latitude": 39.7392,
_26
"label": "Foo Bar Co"
_26
}
_26
},
_26
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26
"date_created": "2015-07-30T19:00:00Z",
_26
"date_updated": "2015-07-30T19:00:00Z",
_26
"links": {
_26
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp",
_26
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests"
_26
}
_26
}

Fetch all Content Resources

fetch-all-content-resources page anchor

_10
GET https://content.twilio.com/v1/Content

Retrieve information about a single Content API template.

  • Pagination is supported in this endpoint.

Retrieve information about multiple or all Content Templates

curl

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

Output

_84
{
_84
"meta": {
_84
"page": 0,
_84
"page_size": 50,
_84
"first_page_url": "https://content.twilio.com/v1/Content?PageSize=50&Page=0",
_84
"previous_page_url": null,
_84
"url": "https://content.twilio.com/v1/Content?PageSize=50&Page=0",
_84
"next_page_url": "https://content.twilio.com/v1/Content?PageSize=50&Page=1&PageToken=DNHXXXXXXXXXXXXXXXX-1678723520",
_84
"key": "contents"
_84
},
_84
"contents": [
_84
{
_84
"language": "en",
_84
"date_updated": "2023-03-31T16:06:50Z",
_84
"variables": {
_84
"1": "07:00",
_84
"3": "owl.jpg",
_84
"2": "03/01/2023"
_84
},
_84
"friendly_name": "whatsappcard2",
_84
"account_sid": "ACXXXXXXXXXXXXXXX",
_84
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXX",
_84
"sid": "HXXXXXXXXXXXXXXXX",
_84
"date_created": "2023-03-31T16:06:50Z",
_84
"types": {
_84
"twilio/card": {
_84
"body": null,
_84
"media": [
_84
"https://twilio.com/{{3}}"
_84
],
_84
"subtitle": null,
_84
"actions": [
_84
{
_84
"index": 0,
_84
"type": "QUICK_REPLY",
_84
"id": "Stop",
_84
"title": "Stop Updates"
_84
}
_84
],
_84
"title": "See you at {{1}} on {{2}}. Thank you."
_84
}
_84
},
_84
"links": {
_84
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXX/ApprovalRequests",
_84
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp"
_84
}
_84
},
_84
{
_84
"language": "en",
_84
"date_updated": "2023-03-31T15:50:24Z",
_84
"variables": {
_84
"1": "07:00",
_84
"2": "03/01/2023"
_84
},
_84
"friendly_name": "whatswppward_01234",
_84
"account_sid": "ACXXXXXXXXXXXXXXX",
_84
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXX",
_84
"sid": "HXXXXXXXXXXXXXXXX",
_84
"date_created": "2023-03-31T15:50:24Z",
_84
"types": {
_84
"twilio/card": {
_84
"body": null,
_84
"media": [
_84
"https://twilio.com/owl.jpg"
_84
],
_84
"subtitle": null,
_84
"actions": [
_84
{
_84
"index": 0,
_84
"type": "QUICK_REPLY",
_84
"id": "Stop",
_84
"title": "Stop Updates"
_84
}
_84
],
_84
"title": "See you at {{1}} on {{2}}. Thank you."
_84
}
_84
},
_84
"links": {
_84
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXX/ApprovalRequests",
_84
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp"
_84
}
_84
}
_84
]
_84
}

Fetch Content and Approvals

fetch-content-and-approvals page anchor

_10
GET https://content.twilio.com/v1/ContentAndApprovals

Retrieve information about templates and their approval status.

  • Pagination is supported in this endpoint.

All WA approval statuses can be found here.

Retrieve information about templates and their approval status

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.content.v1.contentAndApprovals
_10
.list({limit: 20})
_10
.then(contentAndApprovals => contentAndApprovals.forEach(c => console.log(c.sid)));

Output

_99
{
_99
"contents": [
_99
{
_99
"date_created": "2015-07-30T19:00:00Z",
_99
"date_updated": "2015-07-30T19:00:00Z",
_99
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_99
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_99
"friendly_name": "Some content",
_99
"language": "en",
_99
"variables": {
_99
"name": "foo"
_99
},
_99
"types": {
_99
"twilio/text": {
_99
"body": "Foo Bar Co is located at 39.7392, 104.9903"
_99
},
_99
"twilio/location": {
_99
"longitude": 104.9903,
_99
"latitude": 39.7392,
_99
"label": "Foo Bar Co"
_99
}
_99
},
_99
"approval_requests": {
_99
"name": "",
_99
"category": "",
_99
"content_type": "",
_99
"status": "unsubmitted",
_99
"rejection_reason": "",
_99
"allow_category_change": true
_99
}
_99
},
_99
{
_99
"language": "en",
_99
"date_updated": "2023-01-13T23:33:46Z",
_99
"variables": {
_99
"1": "name",
_99
"2": "typedocument"
_99
},
_99
"friendly_name": "Media Test",
_99
"account_sid": "AC25c0d4b9093547216c460212e24e77ee",
_99
"sid": "HX5fcd48a417c1cb59da349ad6d5da4607",
_99
"date_created": "2023-01-13T23:33:46Z",
_99
"types": {
_99
"twilio/media": {
_99
"body": "{{1}}, Congratulations {{2}}! For additional assistance, please contact us at hello@twilio.com",
_99
"media": [
_99
"https://example.com/template"
_99
]
_99
}
_99
},
_99
"approval_requests": {
_99
"category": "TRANSACTIONAL",
_99
"status": "approved",
_99
"rejection_reason": "",
_99
"name": "Media Test",
_99
"content_type": "twilio/media",
_99
"allow_category_change": false
_99
}
_99
},
_99
{
_99
"language": "en",
_99
"date_updated": "2023-01-18T02:46:35Z",
_99
"variables": {
_99
"1": "name",
_99
"2": "type_video",
_99
"3": "small.mp4"
_99
},
_99
"friendly_name": "Video Highlights",
_99
"account_sid": "AC25c0d4b9093547216c460212e24e77ee",
_99
"sid": "HX15c711fcc6d9ea5268d7ab77938a20ff",
_99
"date_created": "2023-01-18T02:46:35Z",
_99
"types": {
_99
"twilio/media": {
_99
"body": "Hi there, {{1}}, we have received your request to upload {{2}}, and should be uploaded shortly.",
_99
"media": [
_99
"http://example.com/highlights/{{3}}"
_99
]
_99
}
_99
},
_99
"approval_requests": {
_99
"category": "TRANSACTIONAL",
_99
"status": "rejected",
_99
"rejection_reason": "INVALID_FORMAT. Facebook is not able to create template with templateName=Video Highlights_hx15c711fcc6d9ea5268d7ab77938a20ff due to the following error: Invalid parameter. More Details: Message template 'components' param is missing expected field(s). component of type HEADER is missing expected field(s) (example)",
_99
"name": "Video Highlights",
_99
"content_type": "twilio/media",
_99
"allow_category_change": true
_99
}
_99
}
_99
],
_99
"meta": {
_99
"page": 0,
_99
"page_size": 20,
_99
"first_page_url": "https://content.twilio.com/v1/ContentAndApprovals?PageSize=20&Page=0",
_99
"url": "https://content.twilio.com/v1/ContentAndApprovals?PageSize=20&Page=0",
_99
"previous_page_url": "https://content.twilio.com/v1/ContentAndApprovals?PageSize=20&Page=0",
_99
"next_page_url": "https://content.twilio.com/v1/ContentAndApprovals?PageSize=20&Page=1",
_99
"key": "contents"
_99
}
_99
}

Fetch Mapping between Legacy WA and Content Templates

fetch-mapping-between-legacy-wa-and-content-templates page anchor

_10
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.

Fetch Legacy WA Content Mapping

fetch-legacy-wa-content-mapping page anchor

Fetch mapping between legacy WA templates and Content API templates

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.content.v1.legacyContents
_10
.list({limit: 20})
_10
.then(legacyContents => legacyContents.forEach(l => console.log(l.sid)));

Output

_85
{
_85
"contents": [
_85
{
_85
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_85
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_85
"friendly_name": "Some content",
_85
"language": "en",
_85
"variables": {
_85
"name": "foo"
_85
},
_85
"legacy_template_name": "legacy_template_1",
_85
"legacy_body": "a body",
_85
"types": {
_85
"twilio/text": {
_85
"body": "Foo Bar Co is located at 39.7392, 104.9903"
_85
},
_85
"twilio/location": {
_85
"longitude": 104.9903,
_85
"latitude": 39.7392,
_85
"label": "Foo Bar Co"
_85
}
_85
},
_85
"url": "https://content.twilio.com/v1/LegacyContent",
_85
"date_created": "2015-07-30T19:00:00Z",
_85
"date_updated": "2015-07-30T19:00:00Z"
_85
},
_85
{
_85
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_85
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_85
"friendly_name": "Anotha content",
_85
"language": "en",
_85
"variables": {
_85
"name": "foo"
_85
},
_85
"legacy_template_name": "legacy_template_2",
_85
"legacy_body": "another body",
_85
"types": {
_85
"twilio/text": {
_85
"body": "Foo Bar Co is located at 39.7392, 104.9903"
_85
},
_85
"twilio/location": {
_85
"longitude": 104.9903,
_85
"latitude": 39.7392,
_85
"label": "Foo Bar Co"
_85
}
_85
},
_85
"url": "https://content.twilio.com/v1/LegacyContent",
_85
"date_created": "2015-07-30T19:00:00Z",
_85
"date_updated": "2015-07-30T19:00:00Z"
_85
},
_85
{
_85
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_85
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_85
"friendly_name": "Third content",
_85
"language": "en",
_85
"variables": {
_85
"name": "foo"
_85
},
_85
"legacy_template_name": "legacy_template_3",
_85
"legacy_body": "a third body",
_85
"types": {
_85
"twilio/text": {
_85
"body": "Foo Bar Co is located at 39.7392, 104.9903"
_85
},
_85
"twilio/location": {
_85
"longitude": 104.9903,
_85
"latitude": 39.7392,
_85
"label": "Foo Bar Co"
_85
}
_85
},
_85
"url": "https://content.twilio.com/v1/LegacyContent",
_85
"date_created": "2015-07-30T19:00:00Z",
_85
"date_updated": "2015-07-30T19:00:00Z"
_85
}
_85
],
_85
"meta": {
_85
"page": 0,
_85
"page_size": 20,
_85
"first_page_url": "https://content.twilio.com/v1/LegacyContent?PageSize=20&Page=0",
_85
"previous_page_url": "https://content.twilio.com/v1/LegacyContent?PageSize=20&Page=0",
_85
"url": "https://content.twilio.com/v1/LegacyContent?PageSize=20&Page=0",
_85
"next_page_url": "https://content.twilio.com/v1/LegacyContent?PageSize=20&Page=1",
_85
"key": "contents"
_85
}
_85
}

For endpoints where pagination is supported you can append the following parameters to the request URL to paginate the results.

  • PageSize: Limit 1000
  • PageToken: The unique token that is generated with each call to show the next page of results.

Delete a Content Resource

delete-a-content-resource page anchor

_10
DELETE https://content.twilio.com/v1/Content/{ContentSid}

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

Delete a template using Content API

delete-a-template-using-content-api page anchor

Delete an individual template using the Content API

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.content.v1.contents('HXXXXXXXX').remove();


Submit Templates for Approval

submit-templates-for-approval page anchor

Submit Template Approval for WhatsApp

submit-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 during the 24-hour session.

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.


_10
POST https://content.twilio.com/v1/Content/{ContentSid}/ApprovalRequests/WhatsApp

content_sid:

  • Type: String
  • Required: Yes
  • Description: content_sid corresponding to the Content resource you want to submit for approval.

Additional parameters required by WhatsApp

additional-parameters-required-by-whatsapp page anchor

name:

  • Type: String
  • Required: Yes
  • Description: Name that uniquely identifies the Content.

    • Only lowercase alphanumeric characters or underscores.

category:

allow_category_change:

  • Type: Boolean
  • Required: No - Defaults to True
  • Description: If you wish to force the category not to be updated and possibly have the template rejected you may set this to false. The template may require an appeal to be approved with the set category.

Submit a Content API Template for WhatsApp Approval

submit-a-content-api-template-for-whatsapp-approval page anchor
curl

_10
curl -X POST 'https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp' \
_10
-H 'Content-Type: application/json' \
_10
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
_10
-d '{
_10
"name": "flight_replies",
_10
"category": "UTILITY"
_10
}'

Output

_10
{
_10
"category": "TRANSPORTATION_UPDATE",
_10
"status": "received",
_10
"rejection_reason": "",
_10
"name": "flight_replies",
_10
"content_type": "twilio/quick-reply"
_10
}

Fetch an Approval Status Request

fetch-an-approval-status-request page anchor

_10
GET https://content.twilio.com/v1/Content/{ContentSid}/ApprovalRequests

All WA approval statuses can be found here.

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

Fetch an Approval Status Request

fetch-an-approval-status-request-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.content.v1.contents('HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.approvalFetch()
_11
.fetch()
_11
.then(approval_fetch => console.log(approval_fetch.sid));

Output

_14
{
_14
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_14
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_14
"whatsapp": {
_14
"type": "whatsapp",
_14
"name": "tree_fiddy",
_14
"category": "ACCOUNT_UPDATE",
_14
"content_type": "twilio/location",
_14
"status": "approved",
_14
"rejection_reason": "",
_14
"allow_category_change": true
_14
},
_14
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests"
_14
}


Template Status Change Alerts

template-status-change-alerts page anchor

Twilio now supports new error codes for "Alarms", "Rejected", and "Paused" WhatsApp Templates. With Twilio Alarms, you can now get notified via webhook or email when these and other errors occur. Approved alarms are also available as a Beta feature.

Learn more here(link takes you to an external page).


Send a Message with Preconfigured Content

send-a-message-with-preconfigured-content page anchor

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

New parameters in the Programmable Messaging API

Data Parameters

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.

Key Info

  • To
  • From
  • MessagingServiceSid
  • Body
AccountSidSID<AC>required

The SID of the Account(link takes you to an external page) creating the Message resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
Tostring<phone-number>required
PII MTL: 120 days

The recipient's phone number in E.164(link takes you to an external page) format (for SMS/MMS) or channel address(link takes you to an external page), e.g. whatsapp:+15552229999.


StatusCallbackstring<uri>

The URL of the endpoint to which Twilio sends Message status callback requests(link takes you to an external page). 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(link takes you to an external page).


ApplicationSidSID<AP>

The SID of the associated TwiML Application(link takes you to an external page). Message status callback requests(link takes you to an external page) 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

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


ProvideFeedbackboolean

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


Attemptinteger

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


ValidityPeriodinteger

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 14400. Default value is 14400. A validity_period greater than 5 is recommended. Learn more about the validity period(link takes you to an external page)


ForceDeliveryboolean

Reserved


ContentRetentionenum<string>

Determines if the message content can be stored or redacted based on privacy settings

Possible values:
retaindiscard

AddressRetentionenum<string>

Determines if the address can be stored or obfuscated based on privacy settings

Possible values:
retainobfuscate

SmartEncodedboolean

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


PersistentActionarray[string]

Rich actions for non-SMS/MMS channels. Used for sending location in WhatsApp messages(link takes you to an external page).


ShortenUrlsboolean

For Messaging Services with Link Shortening configured(link takes you to an external page) 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>

For Messaging Services only: Include this parameter with a value of fixed in conjuction with the send_time parameter in order to schedule a Message(link takes you to an external page).

Possible values:
fixed

SendAtstring<date-time>

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


SendAsMmsboolean

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


ContentVariablesstring

For Content Editor/API(link takes you to an external page) only: Key-value pairs of Template variables(link takes you to an external page) 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(link takes you to an external page) are used.


RiskCheckenum<string>

Include this parameter with a value of disable to skip any kind of risk check on the respective message request.

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(link takes you to an external page), Wireless SIM(link takes you to an external page), short code(link takes you to an external page), or channel address(link takes you to an external page) (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(link takes you to an external page) 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

Bodystringrequired 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(link takes you to an external page) characters (or 70 UCS-2(link takes you to an external page) 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(link takes you to an external page) 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(link takes you to an external page) 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(link takes you to an external page) or by fetching your Templates(link takes you to an external page).

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

Send a Message with Preconfigured Content

send-a-message-with-preconfigured-content-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_18
// Download the helper library from https://www.twilio.com/docs/node/install
_18
// Find your Account SID and Auth Token at twilio.com/console
_18
// and set the environment variables. See http://twil.io/secure
_18
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18
const authToken = process.env.TWILIO_AUTH_TOKEN;
_18
const client = require('twilio')(accountSid, authToken);
_18
_18
client.messages
_18
.create({
_18
from: 'MGXXXXXXXXX',
_18
contentSid: 'HXXXXXXXX',
_18
contentVariables: JSON.stringify({
_18
1: 'YOUR_VARIABLE1',
_18
2: 'YOURVARIABLE2'
_18
}),
_18
to: 'whatsapp:+18005551234'
_18
})
_18
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "Hello! 👍",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "MGXXXXXXXXX",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "whatsapp:+18005551234",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}

(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. For more information about Status Callback URLs see Monitor the Status of your WhatsApp Outbound Message section.


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

Send Messages Scheduled ahead of Time

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

With 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 is sent.

To learn more about Message Scheduling, see this page.


_10
--data-urlencode "SendAt=2021-11-30T20:36:27Z" \
_10
--data-urlencode "ScheduleType=fixed" \

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_20
// Download the helper library from https://www.twilio.com/docs/node/install
_20
// Find your Account SID and Auth Token at twilio.com/console
_20
// and set the environment variables. See http://twil.io/secure
_20
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20
const authToken = process.env.TWILIO_AUTH_TOKEN;
_20
const client = require('twilio')(accountSid, authToken);
_20
_20
client.messages
_20
.create({
_20
messagingServiceSid: 'MGXXXXXXXXXXX',
_20
contentSid: 'HXXXXXXXXXXXXXXX',
_20
contentVariables: JSON.stringify({
_20
1: 'YOUR_VARIABLE1',
_20
2: 'YOURVARIABLE2'
_20
}),
_20
scheduleType: 'fixed',
_20
sendAt: new Date(Date.UTC(2023, 10, 30, 20, 36, 27)),
_20
to: 'whatsapp:+18005551234'
_20
})
_20
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "Hello! 👍",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "+14155552345",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "whatsapp:+18005551234",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}


Rate this page: