Content API Quickstart

Before sending templates created using the Content API, you'll need:

1. At least one valid sender. This can be a phone number, WhatsApp sender, or Facebook Messenger sender (available by requesting through a support ticket).

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

You are ready to start creating and sending message content!

In this tutorial, we will be using WhatsApp.

Next, we'll explore the following using the Content API:

1. Create a template
2. Review individual templates
3. Submit templates for approval to WhatsApp
4. Fetch Approval Status
5. Send a Message

For more information on possible requests see Content API Resources.

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

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

For additional content types see Content Types and Definitions.

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
}'

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 template, note down the ContentSid, HXXXXXXXXXXXXXXXXXXX, found in the response to your content creation request. You will be using that SID throughout the tutorial.

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.

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();

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
}

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.

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
}'

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

Fetching an approval status returns the current state of the WhatsApp template approval submission. The following statuses are possible:

1. Received: The request has successfully been submitted to Twilio. Generally Twilio submits these immediately to WhatsApp.
2. Pending: WhatsApp has received the submission and is currently processing the request.
3. Approved: WhatsApp has approved the template and it is now available for use.
4. 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

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

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
}

To start a "business-initiated" conversation using WhatsApp you need to get the message template approved by WhatsApp by submitting them for approval as shown above. However, you can send messages without WhatsApp approval for 24 hours by responding to an inbound message from the end-user. This tutorial is written using this method.

Start by sending any message, such as "hi", from the number you wish to reach to the sender in your WhatsApp sender.

Now, send the quick reply content template to the number you wish to reach. Pay special attention to these fields:

• From: The identifier of the recipient you are sending the message to. Use e.164 format for phone numbers, "whatsapp:e.164" for WhatsApp, and "messenger:messenger_id" for FB Messenger.
• ContentSid: specify your HXXXXXXXXXXXXXXXX sid.
• ContentVariables: specify the values you want to substitute into your placeholder variables.

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();

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
}

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 and sender in the To and To fields to an SMS-capable phone numbers, you will receive the twilio/text content instead.

Expand image

Congratulations on successfully using the Content API! Next, we recommend checking out the supported Content Types. You can also review additional Content API Resources.