Content API Quickstart


Create your first content template and send it using the Content API. In this tutorial, you'll learn how to do the following:

  1. Create a content template.
  2. Review content templates (Optional).
  3. Submit content templates for approval to WhatsApp (Optional).
  4. Fetch an approval status (Optional).
  5. Send a message on WhatsApp.

For other possible requests, see content API resources.


Before sending content templates created using the Content API, you must have at least one registered sender. The sender can be one of the following:

To send messages across different channels, configure the appropriate sender as follows:


Create a content template

create-a-content-template page anchor

Create a twilio/quick-reply template. Recipients can tap, rather than type, to respond to messages on WhatsApp and Facebook Messenger.

When you create a twilio/text template, recipients can send quick replies using the pre-configured messages you created. If the recipient's channel doesn't support quick replies, Twilio automatically defaults to a text message. This helps you send the same content across all messaging channels.

You can add a placeholder ({{1}}) to the message. The placeholder value is updated dynamically when you send the message. If you don't provide a placeholder value at send time, Twilio will use the default value specified in variables.

See content types overview to learn more about additional content types.

(information)

Tip

If you plan to submit your content template for WhatsApp approval, use self-evident default variable values. These values will be used as sample values during the approval process.

(information)

Info

For all examples, replace the $TWILIO_ACCOUNT_SID with your Twilio Account SID and $TWILIO_AUTH_TOKEN with your Twilio Auth Token.

1
curl -X POST 'https://content.twilio.com/v1/Content' \
2
-H 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4
-d '{
5
"friendly_name": "owl_air_qr",
6
"language": "en",
7
"variables": {"1":"Owl Air Customer"},
8
"types": {
9
"twilio/quick-reply": {
10
"body": "Hi, {{1}} 👋 \nThanks for contacting Owl Air Support. How can I help?",
11
"actions": [
12
{
13
"title": "Check flight status",
14
"id": "flightid1"
15
},
16
{
17
"title": "Check gate number",
18
"id": "gateid1"
19
},
20
{
21
"title": "Speak with an agent",
22
"id": "agentid1"
23
}
24
]
25
},
26
"twilio/text": {
27
"body": "Hi, {{1}}. \n Thanks for contacting Owl Air Support. How can I help?."
28
}
29
}
30
}'

Output

1
{
2
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
"date_created": "2022-08-29T10:43:20Z",
4
"date_updated": "2022-08-29T10:43:20Z",
5
"friendly_name": "owl_air_qr",
6
"language": "en",
7
"links": {
8
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp",
9
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests"
10
},
11
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
"types": {
13
"twilio/text": {
14
"body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?."
15
},
16
"twilio/quick-reply": {
17
"body": "Hi, {{ 1 }}. \n Thanks for contacting Owl Air Support. How can I help?",
18
"actions": [
19
{
20
"id": "flightid1",
21
"title": "Check flight status"
22
},
23
{
24
"id": "gateid1",
25
"title": "Check gate number"
26
},
27
{
28
"id": "agentid1",
29
"title": "Speak with an agent"
30
}
31
]
32
}
33
},
34
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
35
"variables": {
36
"1": "Owl Air Customer"
37
}
38
}

After creating your first content template, note down the sid value (for example, HXXXXXXXXXXXXXXXXXXX) in the response. You'll use the sid for other requests.

(information)

Info

The Content API supports an unlimited number of content templates. However, WhatsApp limits each business to 6,000 approved content templates per WhatsApp Business Account (WABA).


Review content templates (Optional)

review-content-templates-optional page anchor

You can make a GET request to review all content templates. To review a specific content template, include {ContentSid} in the request URL path.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchContent() {
11
const content = await client.content.v1.contents("HXXXXXXX").fetch();
12
13
console.log(content.dateCreated);
14
}
15
16
fetchContent();

Response

1
{
2
"sid": "HXXXXXXX",
3
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"friendly_name": "Some content",
5
"language": "en",
6
"variables": {
7
"name": "foo"
8
},
9
"types": {
10
"twilio/text": {
11
"body": "Foo Bar Co is located at 39.7392, 104.9903"
12
},
13
"twilio/location": {
14
"longitude": 104.9903,
15
"latitude": 39.7392,
16
"label": "Foo Bar Co"
17
}
18
},
19
"url": "https://content.twilio.com/v1/Content/HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
20
"date_created": "2015-07-30T19:00:00Z",
21
"date_updated": "2015-07-30T19:00:00Z",
22
"links": {
23
"approval_create": "https://content.twilio.com/v1/Content/HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ApprovalRequests/whatsapp",
24
"approval_fetch": "https://content.twilio.com/v1/Content/HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ApprovalRequests"
25
}
26
}

Submit a content template for WhatsApp approval (Optional)

submit-a-content-template-for-whatsapp-approval-optional page anchor

To use your content template to start WhatsApp business-initiated conversations, submit your content template for approval. The approval process generally takes 5 minutes to 24 hours.

WhatsApp has strict template approval criteria. Learn more about WhatsApp approval requirements and best practices.

1
curl -X POST 'https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp' \
2
-H 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4
-d '{
5
"name": "flight_replies",
6
"category": "UTILITY"
7
}'

Output

1
{
2
"category": "TRANSPORTATION_UPDATE",
3
"status": "received",
4
"rejection_reason": "",
5
"name": "flight_replies",
6
"content_type": "twilio/quick-reply"
7
}

Fetch an approval status (Optional)

fetch-an-approval-status-optional page anchor

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 processing the request.
  • Approved: WhatsApp has approved the template and it's now available for use.
  • Rejected: WhatsApp has rejected the request. You can find the rejection reason in the rejection_reason field. Learn more about the approval process and best practices.
(warning)

Warning

To support WhatsApp flows, Twilio will return a flow object in the approval request response.

1
curl -X GET 'https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests' \
2
-H 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Output

1
{
2
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests",
3
"whatsapp": {
4
"category": "TRANSPORTATION_UPDATE",
5
"status": "pending",
6
"name": "flight_replies",
7
"type": "whatsapp",
8
"content_type": "twilio/quick-reply",
9
"rejection_reason": ""
10
},
11
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
13
}

Send a message on WhatsApp

send-a-message-on-whatsapp page anchor

You can send messages without WhatsApp approval for up to 24 hours by responding to an inbound message from the end user.

Note: To start a "business-initiated" conversation using WhatsApp, you must submit your message template for approval.

Send any message, such as "hi", from the recipient's number to your WhatsApp sender. Then, send the twilio/quick-reply content template you created to the recipient's number, including the following fields:

Now, send the quick reply content template to the number you want to reach, including the following fields:

FieldDescription
FromThe identifier of the sender. Use the folllowing format:
  • Phone numbers: E.164 format
  • WhatsApp: whatsapp:E.164
  • Facebook Messenger: messenger:{messenger_id}
ToThe identifier of the recipient. Use the folllowing format:
  • Phone numbers: E.164 format
  • WhatsApp: whatsapp:E.164
  • Facebook Messenger: messenger:{messenger_id}
ContentSidThe Content SID (for example, HXXXXXXXXXXXXXXXX).
ContentVariablesThe values you want to substitute into your placeholder variables.
Send a content template created using Content APILink to code sample: Send a content template created using Content API
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createMessage() {
11
const message = await client.messages.create({
12
contentSid: "HXXXXXXX",
13
contentVariables: JSON.stringify({ 1: "Name" }),
14
from: "whatsapp:+18551234567",
15
to: "whatsapp:+18551234567",
16
});
17
18
console.log(message.body);
19
}
20
21
createMessage();

Response

1
{
2
"account_sid": "ACXXXXXXX",
3
"api_version": "2010-04-01",
4
"body": "Hello! 👍",
5
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
"direction": "outbound-api",
9
"error_code": null,
10
"error_message": null,
11
"from": "whatsapp:+18551234567",
12
"num_media": "0",
13
"num_segments": "1",
14
"price": null,
15
"price_unit": null,
16
"messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17
"sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
"status": "queued",
19
"subresource_uris": {
20
"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
},
22
"tags": {
23
"campaign_name": "Spring Sale 2022",
24
"message_type": "cart_abandoned"
25
},
26
"to": "whatsapp:+18551234567",
27
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

You'll now receive a response from your WhatsApp sender.

Note: If you change the recipient and sender in the To and From fields to SMS-capable phone numbers, you'll receive the twilio/text content instead.

Chat interface from Owl Air Support offering options to check flight status, gate number, or speak with an agent.