The Content API supports an unlimited number of templates, however WhatsApp limits users to 6000 approved templates.
date_created
type: string<date-time>The date and time in GMT that the resource was created specified in RFC 2822 format.
date_updated
type: string<date-time>The date and time in GMT that the resource was last updated specified in RFC 2822 format.
sid
type: SID<HX>The unique string that that we created to identify the Content resource.
^HX[0-9a-fA-F]{32}$
34
34
account_sid
type: SID<AC>The SID of the Account that created Content resource.
^AC[0-9a-fA-F]{32}$
34
34
friendly_name
type: stringA string name used to describe the Content resource. Not visible to the end recipient.
language
type: stringTwo-letter (ISO 639-1) language code (e.g., en) identifying the language the Content resource is in.
variables
type: objectDefines the default placeholder values for variables included in the Content resource. e.g. {"1": "Customer_Name"}.
links
type: object<uri-map>A list of links related to the Content resource, such as approval_fetch and approval_create
_10POST https://content.twilio.com/v1/Content
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.
Code sample for creating a template using content API
_10GET https://content.twilio.com/v1/Content/{ContentSid}
Retrieve information about a single Content API template.
Sid
type: SID<HX>The Twilio-provided string that uniquely identifies the Content resource to fetch.
^HX[0-9a-fA-F]{32}$
34
34
Review an individual template created using Content API
_10GET https://content.twilio.com/v1/Content
Retrieve information about a single Content API template.
Retrieve information about multiple or all Content Templates
_10GET https://content.twilio.com/v1/ContentAndApprovals
Retrieve information about templates and their approval status.
All WA approval statuses can be found here.
Retrieve information about templates and their approval status
_10GET 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.
Fetch mapping between legacy WA templates and Content API templates
For endpoints where pagination is supported you can append the following parameters to the request URL to paginate the results.
_10DELETE https://content.twilio.com/v1/Content/{ContentSid}
Sid
type: SID<HX>The Twilio-provided string that uniquely identifies the Content resource to fetch.
^HX[0-9a-fA-F]{32}$
34
34
Delete an individual template using the Content API
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.
_10POST https://content.twilio.com/v1/Content/{ContentSid}/ApprovalRequests/WhatsApp
content_sid:
name:
Description: Name that uniquely identifies the Content.
category:
Description - Use case category the Content corresponds to, as defined by WhatsApp
WhatsApp Categories:
allow_category_change:
_10GET https://content.twilio.com/v1/Content/{ContentSid}/ApprovalRequests
All WA approval statuses can be found here.
Sid
type: SID<HX>The Twilio-provided string that uniquely identifies the Content resource whose approval information to fetch.
^HX[0-9a-fA-F]{32}$
34
34
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.
_10POST 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
AccountSid
type: SID<AC>The SID of the Account creating the Message resource.
^AC[0-9a-fA-F]{32}$
34
34
To
type: string<phone-number>RequiredThe recipient's phone number in E.164 format (for SMS/MMS) or channel address, e.g. whatsapp:+15552229999
.
StatusCallback
type: string<uri>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.
ApplicationSid
type: SID<AP>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.
^AP[0-9a-fA-F]{32}$
34
34
MaxPrice
type: number[DEPRECATED] This parameter will no longer have any effect as of 2024-06-03.
ProvideFeedback
type: booleanBoolean 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
.
Attempt
type: integerTotal number of attempts made (including this request) to send the message regardless of the provider used
ValidityPeriod
type: integerThe 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
ContentRetention
type: enum<string>Determines if the message content can be stored or redacted based on privacy settings
retain
discard
AddressRetention
type: enum<string>Determines if the address can be stored or obfuscated based on privacy settings
retain
obfuscate
SmartEncoded
type: booleanWhether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: true
or false
.
PersistentAction
type: array[string]Rich actions for non-SMS/MMS channels. Used for sending location in WhatsApp messages.
ShortenUrls
type: booleanFor 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.
ScheduleType
type: enum<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.
fixed
SendAt
type: string<date-time>The time that Twilio will send the message. Must be in ISO 8601 format.
SendAsMms
type: booleanIf set to true
, Twilio delivers the message as a single MMS message, regardless of the presence of media.
ContentVariables
type: stringFor 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.
RiskCheck
type: enum<string>Include this parameter with a value of disable
to skip any kind of risk check on the respective message request.
enable
disable
From
type: string<phone-number>Required if MessagingServiceSid is not passedThe sender's Twilio phone number (in E.164 format), alphanumeric sender ID, Wireless SIM, short code, 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.
MessagingServiceSid
type: SID<MG>Required if From is not passedThe 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.
^MG[0-9a-fA-F]{32}$
34
34
Body
type: stringRequired if MediaUrl or ContentSid is not passedThe 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.
MediaUrl
type: array[string]Required if Body or ContentSid is not passedThe 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 and carrier limits apply.
ContentSid
type: SID<HX>Required if Body or MediaUrl is not passedFor 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.
^HX[0-9a-fA-F]{32}$
34
34
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.
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.
_10-d "StatusCallback=http://postb.in/1234abcd" \
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" \