Message Scheduling

(information)

Part of the Twilio Engagement Suite

The Message Scheduling feature comes with the Twilio Engagement Suite. To learn more about Engagement Suite pricing, see RCS, SMS, MMS, or WhatsApp pricing.

The Programmable Messaging API lets you schedule Rich Communication Services (RCS), Short Messaging Services (SMS), Multimedia Messaging Services (MMS), and WhatsApp messages. Scheduled messages can be sent at a fixed time in the future.

The Engagement Suite includes Message Scheduling. Message scheduling comes at no cost and Twilio only charges for messages sent.

Prefer to watch a video?

Prerequisites

Understand how to send outgoing, non-scheduled messages with Messaging Services.

For WhatsApp messaging, create, configure, and get approved:

A WhatsApp sender in your Messaging Service's Sender Pool
A WhatsApp templates

Schedule an outgoing message

Twilio defines a scheduled message as a Message resource where set Status to scheduled.

To send a scheduled message using the Programmable Messaging API, create a Message resource with two parameters set: ScheduleType and SendAt.

Parameters

A scheduled message requires all of the following parameters.

Parameter	Type	Description	Accepted value	Example
`ScheduleType`	String	The indicator that the message scheduled or not.	`fixed`	`fixed`
`SendAt`	String	The date and time when the message gets sent. Messages must be scheduled between 15 minutes and 35 days before this value. Twilio must receive the `POST` request for this message in that range.	Timestamp expressed in ISO-8601 format.	`2021-11-30T20:36:27Z`
`MessagingServiceSid`	String	The Messaging Service SID that sends the message. Without this parameter, Twilio treats the message as a non-scheduled and sends it.	A 32-hexadecimal-digit ID that starts with `MG`.	`MGX{32}`
`Body`	String	The content of the scheduled message as text. Use this parameter, `MediaUrl`, or `ContentSid`, but not all at once.	The text body of the message up to 1600 characters long.	`"This is a scheduled message."`
`MediaUrl`	String	The content of the scheduled message as a URL. Use this parameter, `Body`, or `ContentSid`, but not all at once.	A URL referencing the content of the media received in the Message.
`ContentSid`	String	The content of the scheduled message as an Content SID. Use this parameter, `MediaUrl`, or `Body`, but not all at once. Required to send templates created using the Content Template Builder.	A 32-hexadecimal-digit ID that starts with `HX` String field used to identify the preconfigured content.	`HXX{32}`
`To`	String	The intended recipient's phone number or channel address.	Number expressed in the E.164 format. Preface with `whatsapp:` for WhatsApp recipients.	`+15558885333` or `whatsapp:+15558675310`

Create 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    body: "This is a scheduled message",
13    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14    scheduleType: "fixed",
15    sendAt: new Date("2021-11-30 20:36:27"),
16    to: "+15558675310",
17  });
18
19  console.log(message.body);
20}
21
22createMessage();

Response

1{
2  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "api_version": "2010-04-01",
4  "body": "This is a scheduled message",
5  "date_created": "Mon, 29 Nov 2021 22:40:10 +0000",
6  "date_sent": null,
7  "date_updated": "Mon, 29 Nov 2021 22:40:10 +0000",
8  "direction": "outbound-api",
9  "error_code": null,
10  "error_message": null,
11  "from": null,
12  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
13  "num_media": "0",
14  "num_segments": "0",
15  "price": null,
16  "price_unit": null,
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "queued",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21  },
22  "to": "+15558675310",
23  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24}

Response

Your POST request response indicates whether or not your message scheduled successfully.

A valid POST request returns a 201 (scheduled) HTTP status code.
An invalid POST request returns a 400 HTTP status code.

A scheduled Message resource returns a "status": "scheduled". To check the message status, review the response body of the response from the POST request or fetch the Message resource.

Scheduled messages don't return a status callback event.

In case you need to cancel the message, save the sid property from the scheduled Message resource response.

Example of the Message response with status and sid

1{
2  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "api_version": "2010-04-01",
4  "body": "This is a scheduled message",
5  "date_created": "Mon, 29 Nov 2021 22:40:10 +0000",
6  "date_sent": null,
7  "date_updated": "Mon, 29 Nov 2021 22:40:10 +0000",
8  "direction": "outbound-api",
9  "error_code": null,
10  "error_message": null,
11  "from": null,
12  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
13  "num_media": "0",
14  "num_segments": "0",
15  "price": null,
16  "price_unit": null,
17  "sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
18  "status": "scheduled",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
21  },
22  "to": "+15558675310",
23  "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
24}

Send-time failures

A scheduled message can succeed at creation, but the message fails at the SendAt time. The following sections cover two of these cases.

User-opt outs

User opt-outs don't cancel scheduled messages. Scheduled messages to users who have opted out fail at the SendAt time. If a user opts out of receiving messages, you can cancel the remaining scheduled messages to that user.

WhatsApp template validation failures

WhatsApp requires apps use pre-registered templates for their business-initiated notifications, except in reply to a user-initiated message. Pre-registered templates get validated at the SendAt time, not when you create the Message resource. Messages that don't use a pre-approved WhatsApp template fail at send time.

To learn more, see Twilio WhatsApp API.

Cancel a scheduled message

To cancel a scheduled message, update the Message resource and set the Status to canceled.

A canceled status callback event returns when a Message resource's status transitions to canceled.

Cancel 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 updateMessage() {
11  const message = await client
12    .messages("SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .update({ status: "canceled" });
14
15  console.log(message.body);
16}
17
18updateMessage();

Response

1{
2  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "api_version": "2010-04-01",
4  "body": "Hello World!",
5  "date_created": "Fri, 24 May 2019 17:18:27 +0000",
6  "date_sent": null,
7  "date_updated": "Fri, 24 May 2019 18:18:28 +0000",
8  "direction": "outbound-api",
9  "error_code": null,
10  "error_message": null,
11  "from": null,
12  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "num_media": "0",
14  "num_segments": "1",
15  "price": null,
16  "price_unit": "USD",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "canceled",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",
21    "feedback": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"
22  },
23  "to": "+18182008801",
24  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
25}

Maximum number of scheduled messages

Each Account and Subaccount can schedule up to 1,000,000 messages at any given time. Subaccount limits don't consume the parent Account's allocation.

Message Scheduling

Part of the Twilio Engagement Suite

Prerequisites

Schedule an outgoing message

Parameters

Response

Response

Example of the Message response with status and sid

Send-time failures

User-opt outs

WhatsApp template validation failures

Cancel a scheduled message

Response

Maximum number of scheduled messages

Additional resources