Menu

Expand
Rate this page:

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

Parameters

friendly_name:

Type - String

Required - No

Description - String name used to describe the Content. Not visible to the recipient.

  • Maximum 64 Characters

ContentVariables:

Type - JSON

Required - No

Description - Declare variables and define default placeholder values for variables included in content.
e.g. {“1": "Customer_Name"}

  • Note: WhatsApp requires that variables be formatted as {{1}}, {{2}}, {{3}}, etc. While Twilio supports text variables in templates, WhatsApp will not approve templates that do not conform to numeric formatting.

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.

Loading Code Sample...
        
        
        Code sample for creating a template using content API

        Create Content API Templates

        Code sample for creating a template using content API

        Fetch Information About Templates

        Fetch a Content Resource

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

        Retrieve information about a single Content API template.

        Loading Code Sample...
              
              
              Review an individual template created using Content API

              Fetch a Content API Resource

              Review an individual template created using Content API

              Fetch all Content Resources

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

              Retrieve information about a single Content API template.

              • Pagination is supported in this endpoint.
              Loading Code Sample...
                    
                    
                    Retrieve information about multiple or all Content Templates

                    Fetch all Content Resources

                    Retrieve information about multiple or all Content Templates

                    Fetch Content and Approvals

                    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.

                    Loading Code Sample...
                          
                          
                          Retrieve information about templates and their approval status

                          Fetch Content and Approvals

                          Retrieve information about templates and their approval status

                          Fetch Mapping between Legacy WA and Content Templates

                          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.

                          Loading Code Sample...
                                
                                
                                Fetch mapping between legacy WA templates and Content API templates

                                Fetch Legacy WA Content Mapping

                                Fetch mapping between legacy WA templates and Content API templates

                                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}
                                Loading Code Sample...
                                      
                                      
                                      Delete an individual template using the Content API

                                      Delete a template using Content API

                                      Delete an individual template using the Content API

                                      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/WhatsApp

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

                                      • Only lowercase alphanumeric characters or underscores.

                                      category:

                                      Type - String (enum)

                                      Required - Yes

                                      Description - Use case category the Content corresponds to, as defined by WhatsApp

                                      • WhatsApp Categories:
                                        • UTILITY
                                        • MARKETING
                                        • AUTHENTICATION

                                      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.

                                      Loading Code Sample...
                                            
                                            

                                            Submit a Content API Template for Whatsapp Approval

                                            Fetch an Approval Status Request

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

                                            All WA approval statuses can be found here.

                                            Loading Code Sample...
                                                  
                                                  

                                                  Fetch an Approval Status Request

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

                                                  Learn more here.

                                                  Sending Templates

                                                  Send a Message with Preconfigured Content

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

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

                                                  • FBM - messenger:$FBM_ID
                                                  • WhatsApp - whatsapp:number
                                                  • SMS and MMS - number

                                                  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.

                                                  Loading Code Sample...
                                                        
                                                        

                                                        Send a Message with Preconfigured Content

                                                        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" \
                                                        Loading Code Sample...
                                                              
                                                              

                                                              Send Scheduled Messages

                                                              Rate this page:

                                                              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.

                                                              Loading Code Sample...
                                                                    
                                                                    
                                                                    

                                                                    Thank you for your feedback!

                                                                    Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                                                    Sending your feedback...
                                                                    🎉 Thank you for your feedback!
                                                                    Something went wrong. Please try again.

                                                                    Thanks for your feedback!

                                                                    thanks-feedback-gif