Content API Public Endpoints
The Content API supports an unlimited number of templates, however WhatsApp limits users to 6000 approved templates.
Creation of Templates
Create Templates
POST https://content.twilio.com/v1/ContentWe 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.
Parameters
|
friendly_name: Type - String Required - No Description - String name used to describe the Content. Not visible to the recipient.
|
|
ContentVariables: Type - JSON Required - No Description - Declare variables and define default placeholder values for variables included in content.
|
|
language: Type - String Required - Yes Description - Two-letter (ISO 639-1) language code. e.g. en. Some languages have regional variants such as Portuguese(BR) which uses language code pt_BR. We follow Meta's convention documented here. |
|
types: Type - JSON Required - Yes Description - See Types definition. |
Fetch Information About Templates
Fetch a Content Resource
GET https://content.twilio.com/v1/Content/{ContentSid}Retrieve information about a single Content API template.
Fetch all Content Resources
GET https://content.twilio.com/v1/ContentRetrieve information about a single Content API template.
- Pagination is supported in this endpoint.
Fetch Content and Approvals
GET https://content.twilio.com/v1/ContentAndApprovalsRetrieve information about templates and their approval status.
- Pagination is supported in this endpoint.
All WA approval statuses can be found here.
Fetch Mapping between Legacy WA and Content Templates
GET https://content.twilio.com/v1/LegacyContentFor 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.
Pagination
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.
Deletion of Templates
Delete a Content Resource
DELETE https://content.twilio.com/v1/Content/{ContentSid}Submit Templates for Approval
Submit Template Approval for WhatsApp
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.
POST https://content.twilio.com/v1/Content/{ContentSid}/ApprovalRequests/WhatsAppPath Parameters
|
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
|
name: Type - String Required - Yes Description - Name that uniquely identifies the Content.
|
|
category: Type - String (enum) Required - Yes Description - Use case category the Content corresponds to, as defined by WhatsApp
|
|
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. |
Fetch an Approval Status Request
GET https://content.twilio.com/v1/Content/{ContentSid}/ApprovalRequestsTemplate Status Change Alerts
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.
Sending Templates
Send a Message with Preconfigured Content
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/MessagesNew parameters in the Programmable Messaging API
Data Parameters
|
ContentSid: Type - String Required - Yes if sending templates created in the Content API/Editor Description - Identifier for the preconfigured Content. |
|
Variables: Type - JSON string Required - No Description - Key-value pairs of variable names to substitution values. |
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: Type - Number Required - Yes Description - The location you send the message to.
|
|
From: Type - Sid or Number Required - Yes Description - Messaging Service(MG...XXX) or Phone Number with an additional Messaging Service Sid parameter. |
|
MessagingServiceSid: Type - Sid Required - No Description - If your use case requires a Phone Number in the From field, you can instead specify a MessagingServiceSid in the POST request. Please see the FAQ to reference an example cURL command. |
|
Body: Type - String Required - No Description - This is an optional field and will not affect the template. The body will be overwritten by the body of the Content template. |
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
Status Callback URLs can be set for all messages in a Messaging Service (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.
-d "StatusCallback=http://postb.in/1234abcd" \
Send Messages Scheduled ahead of Time
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.
--data-urlencode "SendAt=2021-11-30T20:36:27Z" \
--data-urlencode "ScheduleType=fixed" \Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
