Before sending templates created using the Content API, you'll need:
At least one valid sender.
This can be a phone number, WhatsApp sender, or Facebook Messenger sender (available by requesting through a support ticket).
A Messaging Service.
The Messaging Service provides a higher-level "bundling" of messaging functionality around a common set of senders.
Configuring Your Sender
To send SMS or MMS, use a
phone number
. You can port a number or purchase one from the Twilio Console by navigating to
Phone Numbers
.
To send WhatsApp messages, use your Twilio phone number or your own number to register a WhatsApp sender. See
Getting Started with WhatsApp
for more infomation.
To send Facebook Messenger messages, navigate to the
Channels
area in the Twilio Console and connect your Facebook page to create a FB Messenger sender.
In this tutorial, we will be using WhatsApp.
Configuring Your Messaging Service
Create a Messaging Service
by navigating to Messaging > Services and clicking "
Create Messaging Service
".
Give your Messaging Service a friendly name and select your use case. Once you get to step 2,
click to "Add Senders" to your service
and add the sender(s) that you'll be using to send messages.
Proceed to Step 3 to "Set up integration" and choose how you want to receive messages via webhooks.
If you are already using a sender that has an existing webhook configuration,
choose "Defer to sender's webhook".
You may choose "Send a webhook" if you want to use this Messaging Service's webhook. This option lets you manage multiple senders' with this single webhook.
Optional: If you want to use Conversations API, choose "Autocreate a conversation."
(information)
Info
If you already configured your sender's webhook and plan to switch to the Messaging Services' webhook, be sure to plan for up to a minute of downtime during the switch.
If you are using SMS and MMS, you may need to complete Step 4 "Add compliance info" depending on your region's
compliance requirements
. Otherwise, you can click
"Click to Complete Messaging Service Setup"
and click "View my new Messaging Service".
Find your Messaging Service Sid
and save it. You will need this later.
You are ready to start creating and sending message content!
Create and Send Your First Content API Template
Next, we'll explore the following using the Content API:
For all examples, replace the $TWILIO_ACCOUNT_SID with your Twilio Account SID and $TWILIO_AUTH_TOKEN with your Twilio Auth Token.
Create a Template
In the following code sample, we will be creating a quick-reply content type template, twilio/quick-reply. Quick replies let recipients tap, rather than type, to respond to the message on WhatsApp and Facebook Messenger.
Note that there is a second text content type, twilio/text. This means that the message content you are creating can be used to send quick replies, but if the end user's channel does not support quick replies, Twilio will automatically default to a simple text message. This lets you send the same content to all messaging channels.
In addition, we are using a placeholder value, {{1}}. This value can later be replaced dynamically when the message is sent. If you do not provide a value at message send time, the default value specified via variables will be used.
Tip: Provide self-evident default variable values if you plan to submit your template for approval to WhatsApp. These will be used as sample values during the template approval process.
Create your first Content Template
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": "owl_air_qr",
_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?."
After creating your first template, note down the ContentSid, HXXXXXXXXXXXXXXXXXXX, found in the response to your content creation request. You will be using that SID throughout the tutorial.
(information)
Info
The Content API supports an unlimited number of templates, however WhatsApp limits each business to 6000 approved templates per WhatsApp Business Account (WABA).
Review Individual Templates
Using the "content sid", HXXXXXXXXXXXXXXXXXXX, from the response in the previous step, you can utilize a GET request to review individual content templates. To review all templates omit {ContentSid} from your GET request URL.
Review Content API Templates
Fetch a Content API Resource
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
To send WhatsApp messages to start a conversation with an end user ("business-initiated" conversation), you will need to get the message template approved by WhatsApp. However, you can send messages without WhatsApp approval by responding to an inbound message from the end-user. The free-form session lasts 24-hours. We will take this approach in this tutorial.
Start by sending any message, such as "hi", from the number you wish to reach to the sender in your WhatsApp sender (the one in your messaging services sender pool).
Now, send the quick reply content template to the number you wish to reach. Pay special attention to these fields:
From:
the sender
must be replaced with the Messaging Service Sid
. Alternatively, you may use the sender in the
From
field, but you must add the additional parameter
MessagingServiceSid
to invoke the Messaging Service.
ContentSid:
specify your
HXXXXXXXXXXXXXXXX
sid.
ContentVariables:
specify the values you want to substitute into your placeholder variables.
Send a Template Created using Content API
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_21
// Download the helper library from https://www.twilio.com/docs/node/install
_21
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_21
_21
// Find your Account SID and Auth Token at twilio.com/console
_21
// and set the environment variables. See http://twil.io/secure
At this point, you should receive a response back from your WhatsApp sender, with 3 quick reply buttons! Note that if you change the recipient in the To field to an SMS-capable phone number, you will receive the twilio/text content instead.
Submit a Template for WhatsApp Approval
To use your content template to start WhatsApp business-initiated conversations, you can submit your template for approval. Approval by WhatsApp ranges from 5 minutes to 24 hours.
Note that WhatsApp only allows some template types to be submitted for approval and be used for notifications. For more info, see Content Types Overview.
WhatsApp has strict template approval criteria that are evolving over time. For best practices, please review the following documentation.
Submit a Template for WhatsApp Approval
curl
_10
curl -X POST 'https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/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
Fetching an approval status returns the current state of the WhatsApp template approval submission. The following statuses are possible:
Received
: The request has successfully been submitted to Twilio. Generally Twilio submits these immediately to WhatsApp.
Pending
: WhatsApp has received the submission and is currently processing the request.
Approved
: WhatsApp has approved the template and it is now available for use.
Rejected
: The template was rejected by WhatsApp. WhatsApp's reason for the rejection is found in the
rejection_reason
field. For tips to avoid template rejections, please review the following
documentation
(warning)
Warning
If you are seeing successfully created templates remain in Received status, this could mean WhatsApp does not accept them for approval, such as twilio/list-picker.
Check a Template's approval status
curl
_10
curl -X GET 'https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests' \
Congratulations on successfully using the Content API! Next, we recommend checking out the supported Content Types. You can also review additional Content API Resources.