Content API public endpoints

(information)

Info

The Content API supports an unlimited number of content templates, but WhatsApp limits each account to 6,000 approved templates. Most of this page refers to v1 of the Content API. Content template search is available only in v2.

Property nameTypeRequiredDescriptionChild properties

dateCreatedstring<date-time>

Optional

Not PII

The date and time in GMT that the resource was created specified in RFC 2822 format.

dateUpdatedstring<date-time>

Optional

Not PII

The date and time in GMT that the resource was last updated specified in RFC 2822 format.

sidSID<HX>

Optional

Not PII

The unique string that that we created to identify the Content resource.

Pattern: ^HX[0-9a-fA-F]{32}$Min length: 34Max length: 34

accountSidSID<AC>

Optional

Not PII

The SID of the Account that created Content resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

friendlyNamestring

Optional

Not PII

A string name used to describe the Content resource. Not visible to the end recipient.

languagestring

Optional

Not PII

Two-letter (ISO 639-1) language code (e.g., en) identifying the language the Content resource is in.

variablesobject

Optional

Not PII

Defines the default placeholder values for variables included in the Content resource. e.g. {"1": "Customer_Name"}.

typesobject

Optional

Not PII

The Content types (e.g. twilio/text) for this Content resource.

urlstring<uri>

Optional

Not PII

The URL of the resource, relative to https://content.twilio.com.

linksobject<uri-map>

Optional

Not PII

A list of links related to the Content resource, such as approval_fetch and approval_create

Create a Content API template

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

(information)

Info

Save the ContentSid returned in the API response. You will reference this SID whenever you send a message or perform other operations with the template.

Create a Content API template

1// Install the C# / .NET helper library from twilio.com/docs/csharp/install
2
3using System;
4using Twilio;
5using Twilio.Rest.Content.V1;
6
7     TwilioClient.Init(accountSid, authToken);
8
9    // define the twilio/text type for less rich channels (e.g. SMS)
10    var twilioText = new TwilioText.Builder();
11    twilioText.WithBody("Hi {{1}}.  Thanks for contacting Owl Air Support. How can we help?");
12
13    // define the twilio/quick-reply type for more rich channels
14    var twilioQuickReply = new TwilioQuickReply.Builder();
15    twilioQuickReply.WithBody("Owl Air Support");
16    var quickreply1 = new QuickReplyAction.Builder()
17        .WithTitle("Contact Us")
18        .WithId("flightid1")
19        .Build();
20    var quickreply2 = new QuickReplyAction.Builder()
21        .WithTitle("Check gate number")
22        .WithId("gateid1")
23        .Build();
24    var quickreply3 = new QuickReplyAction.Builder()
25        .WithTitle("Speak with an agent")
26        .WithId("agentid1")
27        .Build();
28    twilioQuickReply.WithActions(new List<QuickReplyAction>() { quickreply1, quickreply2, quickreply3 });
29
30    // define all the content types to be part of the template
31    var types = new Types.Builder();
32    types.WithTwilioText(twilioText.Build());
33    types.WithTwilioQuickReply(twilioQuickReply.Build());
34
35    // build the create request object
36    var contentCreateRequest = new ContentCreateRequest.Builder();
37    contentCreateRequest.WithTypes(types.Build());
38    contentCreateRequest.WithLanguage("en");
39    contentCreateRequest.WithFriendlyName("owl_air_qr");
40    contentCreateRequest.WithVariables(new Dictionary<string, string>() { {"1", "John"} });
41    
42    // create the twilio template
43    var contentTemplate = await CreateAsync(contentCreateRequest.Build());
44
45    Console.WriteLine($"Created Twilio Content Template SID: {contentTemplate.Sid}");

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}

Fetch information about templates

Fetch a content resource

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

Retrieve a single Content API template.

Path parameters

Property nameTypeRequiredPIIDescription

sidSID<HX>

required

Not PII

The Twilio-provided string that uniquely identifies the Content resource to fetch.

Pattern: ^HX[0-9a-fA-F]{32}$Min length: 34Max length: 34

Fetch a Content API resource

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchContent() {
11  const content = await client.content.v1
12    .contents("HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .fetch();
14
15  console.log(content.dateCreated);
16}
17
18fetchContent();

Response

1{
2  "sid": "HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
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}

Template search (v2)

Filter	Number of filters	Behavior
`Language`	Multiple	Matches the template's `language` field.
`ContentType`	Multiple	Checks for the existence of one or more `contenttype` fields (for example, `twilio/text`).
`ChannelEligibility`	Multiple	Matches entries in the `approval_content.channel.status` field by using the `{channel}:{template_status}` format.
`Content`	Single	Case-insensitive search pattern that looks for matches in `body`, `title`, `sub_title`, `friendly_name`, and `approval_content.channel.name`. Maximum length: 1,024 characters or 30 words. The search returns documents that match all supplied terms in the given order.
`ContentName`	Single	Search pattern for `friendly_name` (template name) and `approval_content.channel.name`. Maximum length: 450 characters or 30 words.
`DateCreatedBefore`	Single	Upper bound for template creation time. Format: `YYYY-MM-DDThh:mm:ssZ`.
`DateCreatedAfter`	Single	Lower bound for template creation time. Format: `YYYY-MM-DDThh:mm:ssZ`.
`DateCreatedBefore` and `DateCreatedAfter`	Single	Specifies a date-time range for the search. Combine the two parameters as shown: `DateCreatedBefore=YYYY-MM-DDThh:mm:ssZ&DateCreatedAfter=YYYY-MM-DDThh:mm:ssZ`.

GET "https://content.twilio.com/v2/Content?PageSize=100&Content=hello"

GET "https://content.twilio.com/v2/ContentAndApprovals?ChannelEligibility=whatsapp:unsubmitted&Language=en"

Fetch all content resources

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

Retrieve all content templates. This endpoint supports pagination.

Fetch all content resources

1curl -X GET "https://content.twilio.com/v1/Content"
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Output

1{
2  "meta": {
3    "page": 0,
4    "page_size": 50,
5    "first_page_url": "https://content.twilio.com/v1/Content?PageSize=50&Page=0",
6    "previous_page_url": null,
7    "url": "https://content.twilio.com/v1/Content?PageSize=50&Page=0",
8    "next_page_url": "https://content.twilio.com/v1/Content?PageSize=50&Page=1&PageToken=DNHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-1678723520",
9    "key": "contents"
10  },
11  "contents": [
12    {
13      "language": "en",
14      "date_updated": "2023-03-31T16:06:50Z",
15      "variables": {
16        "1": "07:00",
17        "3": "owl.jpg",
18        "2": "03/01/2023"
19      },
20      "friendly_name": "whatsappcard2",
21      "account_sid": "ACXXXXXXXXXXXXXXX",
22      "url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
23      "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
24      "date_created": "2023-03-31T16:06:50Z",
25      "types": {
26        "twilio/card": {
27          "body": null,
28          "media": [
29            "https://twilio.example.com/{{3}}"
30          ],
31          "subtitle": null,
32          "actions": [
33            {
34              "index": 0,
35              "type": "QUICK_REPLY",
36              "id": "Stop",
37              "title": "Stop Updates"
38            }
39          ],
40          "title": "See you at {{1}} on {{2}}. Thank you."
41        }
42      },
43      "links": {
44        "approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests",
45        "approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp"
46      }
47    },
48    {
49      "language": "en",
50      "date_updated": "2023-03-31T15:50:24Z",
51      "variables": {
52        "1": "07:00",
53        "2": "03/01/2023"
54      },
55      "friendly_name": "whatswppward_01234",
56      "account_sid": "ACXXXXXXXXXXXXXXX",
57      "url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
58      "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
59      "date_created": "2023-03-31T15:50:24Z",
60      "types": {
61        "twilio/card": {
62          "body": null,
63          "media": [
64            "https://twilio.example.com/owl.jpg"
65          ],
66          "subtitle": null,
67          "actions": [
68            {
69              "index": 0,
70              "type": "QUICK_REPLY",
71              "id": "Stop",
72              "title": "Stop Updates"
73            }
74          ],
75          "title": "See you at {{1}} on {{2}}. Thank you."
76        }
77      },
78      "links": {
79        "approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests",
80        "approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp"
81      }
82    }
83  ]
84}

Fetch content and approvals

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

Retrieve templates together with their approval status. The WhatsApp Flow publish status appears in the approvals object. Pagination is supported.

For details, see WhatsApp approval statuses.

Fetch content and approvals

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listContentAndApprovals() {
11  const contentAndApprovals = await client.content.v1.contentAndApprovals.list({
12    limit: 20,
13  });
14
15  contentAndApprovals.forEach((c) => console.log(c.dateCreated));
16}
17
18listContentAndApprovals();

Response

1{
2  "contents": [],
3  "meta": {
4    "page": 0,
5    "page_size": 10,
6    "first_page_url": "https://content.twilio.com/v1/ContentAndApprovals?PageSize=10&Page=0",
7    "previous_page_url": null,
8    "next_page_url": null,
9    "url": "https://content.twilio.com/v1/ContentAndApprovals?PageSize=10&Page=0",
10    "key": "contents"
11  }
12}

Fetch mapping between legacy WhatsApp and content templates

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

If your existing WhatsApp Business Account (WABA) templates were migrated to the Content API, this endpoint returns a mapping between the legacy templates and their corresponding ContentSid values, languages, and body text. Pagination is supported.

Fetch legacy WhatsApp content mapping

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listLegacyContent() {
11  const legacyContents = await client.content.v1.legacyContents.list({
12    limit: 20,
13  });
14
15  legacyContents.forEach((l) => console.log(l.dateCreated));
16}
17
18listLegacyContent();

Response

1{
2  "contents": [],
3  "meta": {
4    "page": 0,
5    "page_size": 10,
6    "first_page_url": "https://content.twilio.com/v1/LegacyContent?PageSize=10&Page=0",
7    "previous_page_url": null,
8    "url": "https://content.twilio.com/v1/LegacyContent?PageSize=10&Page=0",
9    "next_page_url": null,
10    "key": "contents"
11  }
12}

Pagination

For endpoints that support pagination, append these query parameters to the request URL:

PageSize (recommended maximum: 500). The response is limited to 1 MB, which is roughly 500 templates.
PageToken. Use the meta.next_page_url value from the previous response to request the next page. Supplying a page number (page=) is not supported.

Delete a content template

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

Path parameters

Property nameTypeRequiredPIIDescription

sidSID<HX>

required

Not PII

The Twilio-provided string that uniquely identifies the Content resource to fetch.

Pattern: ^HX[0-9a-fA-F]{32}$Min length: 34Max length: 34

Delete a template by using the Content API

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteContent() {
11  await client.content.v1.contents("HXXXXXXXX").remove();
12}
13
14deleteContent();

Additional parameter for WhatsApp

Parameter	Type	Required	Description
`deleteInWaba`	Boolean	No	If the template was synchronized from WABA or legacy templates, set this parameter to `true` to delete the template both in Twilio and in the WABA. Set to `false` to delete the template only from Twilio. Default: `false`.

Submit templates for approval

Submit a template approval for WhatsApp

(information)

Info

To send outbound messages to WhatsApp users, the template must be approved by WhatsApp. If a user initiates a conversation, a 24-hour messaging session starts, during which certain outbound content types can be sent without a template.

To learn more about approval requirements and session limits, see the approval requirements chart.

Submit the template for WhatsApp review by sending a POST request that includes the parameters listed in the next tables. For best practices, see WhatsApp notification messages with templates. WhatsApp review usually finishes within one business day.

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

Path parameter

Parameter	Type	Required	Description
`ContentSid`	string	Yes	SID of the content resource you want to submit for approval.

Additional parameters required by WhatsApp

Parameter	Type	Required	Description
`name`	string	Yes	Unique name for the template. Accepts only lowercase alphanumeric characters and underscores.
`category`	enum	Yes	Template use-case category as defined by WhatsApp. Valid values: `UTILITY` `MARKETING` `AUTHENTICATION`

Submit a template for WhatsApp approval

1curl -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 request

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

For a list of possible status values, see WhatsApp template approval statuses. Flow status values are returned in the approvals object.

Path parameters

Property nameTypeRequiredPIIDescription

sidSID<HX>

required

Not PII

The Twilio-provided string that uniquely identifies the Content resource whose approval information to fetch.

Pattern: ^HX[0-9a-fA-F]{32}$Min length: 34Max length: 34

Fetch an approval status request

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchApprovalFetch() {
11  const approvalFetch = await client.content.v1
12    .contents("HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .approvalFetch()
14    .fetch();
15
16  console.log(approvalFetch.sid);
17}
18
19fetchApprovalFetch();

Response

1{
2  "sid": "HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "whatsapp": {
5    "type": "whatsapp",
6    "name": "tree_fiddy",
7    "category": "UTILITY",
8    "content_type": "twilio/location",
9    "status": "approved",
10    "rejection_reason": "",
11    "allow_category_change": true
12  },
13  "url": "https://content.twilio.com/v1/Content/HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ApprovalRequests"
14}

Send a template

Send a message with pre-configured content

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

Include the ContentSid in the POST body to send a message based on the template. If the template contains variables, pass them in the ContentVariables parameter.

Path parameters

Property nameTypeRequiredPIIDescription

accountSidSID<AC>

required

Not PII

The SID of the Account creating the Message resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

tostring<phone-number>

required

PII MTL: 120 days

The recipient's phone number in E.164 format (for SMS/MMS) or channel address, e.g. whatsapp:+15552229999.

statusCallbackstring<uri>

Optional

Not PII

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.

applicationSidSID<AP>

Optional

Not PII

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.

Pattern: ^AP[0-9a-fA-F]{32}$Min length: 34Max length: 34

maxPricenumber

Optional

Not PII

[OBSOLETE] This parameter will no longer have any effect as of 2024-06-03.

provideFeedbackboolean

Optional

Not PII

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

attemptinteger

Optional

Not PII

Total number of attempts made (including this request) to send the message regardless of the provider used

validityPeriodinteger

Optional

Not PII

The 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 36000. Default value is 36000. A validity_period greater than 5 is recommended. Learn more about the validity period

forceDeliveryboolean

Optional

Not PII

Reserved

contentRetentionenum<string>

Optional

Not PII

Possible values:

retaindiscard

addressRetentionenum<string>

Optional

Not PII

Possible values:

retainobfuscate

smartEncodedboolean

Optional

Not PII

Whether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: true or false.

persistentActionarray[string]

Optional

Not PII

Rich actions for non-SMS/MMS channels. Used for sending location in WhatsApp messages.

trafficTypeenum<string>

Optional

Not PII

Possible values:

free

shortenUrlsboolean

Optional

Not PII

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

scheduleTypeenum<string>

Optional

Not PII

Possible values:

fixed

sendAtstring<date-time>

Optional

Not PII

The time that Twilio will send the message. Must be in ISO 8601 format.

sendAsMmsboolean

Optional

Not PII

If set to true, Twilio delivers the message as a single MMS message, regardless of the presence of media.

contentVariablesstring

Optional

Not PII

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

riskCheckenum<string>

Optional

Not PII

Possible values:

enabledisable

fromstring<phone-number>

required if MessagingServiceSid is not passed

PII MTL: 120 days

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

messagingServiceSidSID<MG>

required if From is not passed

Not PII

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

Pattern: ^MG[0-9a-fA-F]{32}$Min length: 34Max length: 34

bodystring

required if MediaUrl or ContentSid is not passed

PII MTL: 30 days

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

mediaUrlarray[string<uri>]

required if Body or ContentSid is not passed

Not PII

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

contentSidSID<HX>

required if Body or MediaUrl is not passed

Not PII

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

Pattern: ^HX[0-9a-fA-F]{32}$Min length: 34Max length: 34

Send a message with pre-configured content

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    contentSid: "HXXXXXXXX",
13    contentVariables: JSON.stringify({
14      1: "YOUR_VARIABLE1",
15      2: "YOUR_VARIABLE2",
16    }),
17    from: "MGXXXXXXXXX",
18    to: "whatsapp:+18005551234",
19  });
20
21  console.log(message.sid);
22}
23
24createMessage();

Response

1{
2  "account_sid": "ACXXXXXXXXX",
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": "MGXXXXXXXXX",
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  "to": "whatsapp:+18005551234",
23  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24}

(warning)

Warning

The From value must be a Messaging Service SID that contains a WhatsApp or Facebook Messenger sender.

Send templates with status callbacks

You can configure a status callback URL for all messages in a Messaging Service or for a single outbound message by including the StatusCallback parameter.

-d "StatusCallback=https://example.com/callback"

For details, see monitor the status of your WhatsApp outbound message.

Send messages scheduled ahead of time

You can schedule RCS, SMS, MMS, and WhatsApp messages to be sent at a fixed time.

1--data-urlencode "SendAt=2023-11-30T20:36:27Z" \
2--data-urlencode "ScheduleType=fixed" \

Send a scheduled message

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    contentSid: "HXXXXXXXXXXXXXXX",
13    contentVariables: JSON.stringify({
14      1: "YOUR_VARIABLE1",
15      2: "YOUR_VARIABLE2",
16    }),
17    messagingServiceSid: "MGXXXXXXXXXXX",
18    scheduleType: "fixed",
19    sendAt: new Date("2023-11-30 20:36:27"),
20    to: "whatsapp:+18005551234",
21  });
22
23  console.log(message.body);
24}
25
26createMessage();

Response

1{
2  "account_sid": "ACXXXXXXXXXX",
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": "+14155552345",
12  "num_media": "0",
13  "num_segments": "1",
14  "price": null,
15  "price_unit": null,
16  "messaging_service_sid": "MGXXXXXXXXXXX",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "queued",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21  },
22  "to": "whatsapp:+18005551234",
23  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24}

Template status change alerts

Twilio returns specific error codes for Alarms, Rejected, and Paused WhatsApp templates. With Twilio Alarms, you can receive webhook or email notifications when these events occur. Alerts for approved templates are available as a beta feature.

For more information, see alerts for rejected and paused WhatsApp templates.