Message Scheduling

You first need to understand how to send outgoing, non-scheduled messages with Messaging Services. If you haven't done so, check out How to Send SMS with Messaging Services before you proceed.

If you want to schedule WhatsApp messages, you must have an approved WhatsApp sender added to your Messaging Service's Sender Pool. You also need to have pre-approved WhatsApp templates.

A "scheduled message" is a Message resource with a Status of scheduled.

When you want to send a normal (non-scheduled) message via the Programmable Messaging API, you create a Message resource. You also need to create a Message resource when creating a scheduled message, but with the addition of two parameters: ScheduleType and SendAt.

The parameters required to create a scheduled message are listed below.

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

22
createMessage();

1
{
2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
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
  "tags": null,
23
  "to": "+15558675310",
24
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
25
}

Twilio's response to your POST request indicates whether or not your message was scheduled successfully.

• If your POST request to create the scheduled Message resource was valid, Twilio returns a 201 (scheduled) HTTP status code.
• If your request was invalid, Twilio returns a 400 HTTP status code.

A scheduled Message resource has a Status of scheduled. You can check the status in the body of the response from Twilio, or by fetching the Message resource.

Note: No status callback event is emitted when a message is scheduled.

You should save the SID of the scheduled Message resource in case you need to cancel sending the message. This is found via the sid property of Twilio's response.

Below is an example of a response from Twilio, with the status and sid properties highlighted.

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
}

Sometimes, a Message is successfully created with a Status of scheduled, but the message fails at the SendAt time. Two of these cases are covered below.

User opt-outs do not automatically 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. See the "Cancel a scheduled message" section below for more information.

WhatsApp requires that business-initiated notifications sent by your application be templated and pre-registered, with the exception of messages sent as a reply to a user-initiated message. Check out Twilio's WhatsApp docs for more information.

Validation of pre-registered templates occurs at the SendAt time, not when the Message resource is created. Messages that don't use a pre-approved WhatsApp template fail at send time.

To cancel a scheduled message, update the Message resource so that the Status is canceled.

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

An example API request to cancel a scheduled message is shown below.

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 updateMessage() {
11
  const message = await client
12
    .messages("SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
    .update({ status: "canceled" });
14

15
  console.log(message.body);
16
}
17

18
updateMessage();

1
{
2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
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
  "tags": {},
24
  "to": "+18182008801",
25
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
26
}

Each Account (including Subaccounts) are allowed up to 500,000 scheduled messages (i.e. Message resources with scheduled statuses) at any given time. Subaccount limits are separate from the parent Account and do not consume the parent Account's allocation.

• "Message Scheduling FAQs" Help Center article
• How to Send SMS Messages with Messaging Services
• Message Resource API Documentation