The Message Scheduling feature is only available for use with Messaging Services.
Message Scheduling is part of Engagement Suite. Visit the SMS Pricing page and WhatsApp Pricing page for price details.
With the Programmable Messaging API, you can schedule SMS, MMS, and WhatsApp messages to be sent at a fixed time in the future.
Message Scheduling is included in Engagement Suite. Scheduling a message is free; you'll only pay for a message once it is sent. For information on Engagement Suite pricing, see the pricing pages for SMS/MMS or WhatsApp.
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.
| Required parameter | Required value | Additional information |
|---|---|---|
ScheduleType | fixed | This parameter/value combination indicates to Twilio that the message should be sent at a fixed time in the future. |
SendAt | A datetime string in ISO-8601 format (e.g., 2021-11-30T20:36:27Z) | This is the date and time at which the message will be sent. Messages must be scheduled at least 15 minutes before the intended send time. This means that the POST request that creates the Message resource must be sent at least 15 minutes before the SendAt value.Messages must be scheduled no more than 35 days before the intended send time. This means that the POST request that creates the Message resource must be sent no more than 35 days before the SendAt value. |
MessagingServiceSid | The Messaging Service SID from which the message will be sent | Note: Without a MessagingServiceSid, Twilio treats the message as a non-scheduled message and the message is sent immediately. |
Body or MediaUrl or ContentSid | The content of the scheduled message (e.g., "This is a scheduled message.") | |
To | The recipient's phone number (e.g., +15558885333)or the recipient's channel address (e.g., whatsapp:+15558675310) |
Twilio's response to your POST request indicates whether or not your message was scheduled successfully.
POST
request to create the scheduled Message resource was valid, Twilio returns a
201 (scheduled)
HTTP status code.
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.
_24{_24 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",_24 "api_version": "2010-04-01",_24 "body": "This is a scheduled message",_24 "date_created": "Mon, 29 Nov 2021 22:40:10 +0000",_24 "date_sent": null,_24 "date_updated": "Mon, 29 Nov 2021 22:40:10 +0000",_24 "direction": "outbound-api",_24 "error_code": null,_24 "error_message": null,_24 "from": null,_24 "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",_24 "num_media": "0",_24 "num_segments": "0",_24 "price": null,_24 "price_unit": null,_24 "sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",_24 "status": "scheduled",_24 "subresource_uris": {_24 "media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"_24 },_24 "to": "+15558675310",_24 "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.
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.