As of January 12, 2022, Twilio offers Message Scheduling as a Public Beta feature. This feature enables you to schedule an SMS, MMS or WhatsApp message for a fixed time in the future. Scheduling a message is free, so you'll only pay for a message once it is sent.
To get started with Message Scheduling, refer to the Message Scheduling API documentation.
As a new feature and one that is in Public Beta, there are some important limitations to be aware of when implementing message scheduling, or when considering using the scheduling functionality at large scale. Please read on for details.
Limitations of Message Scheduling
Message Scheduling requires the use of Messaging Services
Message Scheduling is only accessible when using Messaging Services.
You must pass a MessageServiceSid in your API request in order to schedule messages. You may pass a specific From number as well, if you want to choose a specific sender instead of letting Twilio choose for you. It is not sufficient to just have your Twilio number(s) in a Messaging Service. If you only pass a From number in your API request and do not pass a Messaging Service SID, the scheduling parameters will be dropped from the API request and the message will be sent immediately.
Time range limitations for scheduled messages
A message must be scheduled at least 60 minutes in advance of message send time.
A message cannot be scheduled more than 7 days in advance of the request.
User opt-outs (STOP replies) do not automatically cancel scheduled messages
If you have already scheduled a message to be sent to a specific end user, and the user then opts-out of messaging from your number(s) by sending a message with STOP or another opt-out keyword, the scheduled message will not be automatically canceled.
This limitation is specific to messages that were already scheduled, but not yet sent, before the user opted out.
If this occurs, you must cancel the scheduled message prior to the SendAt time to ensure the end user does not receive a message after opting-out.
Limit of messages that can be in a scheduled state at any time
At this time, there is a soft limit of 50,000 scheduled messages at any given time, per Account SID. As each scheduled message reaches its SendAt time and is removed from the total scheduled messages queue, more messages can be scheduled.
Importantly, canceling a message will not remove it from the scheduled queue until the SendAt time. For example, if you schedule 50,000 messages to be sent 7 days from the present, and then you cancel all 50,000 of those messages, you will not be able to schedule any additional messages until the time when those messages were originally scheduled to be sent.
No support for message body or phone number redaction (Message Privacy features)
Message scheduling is incompatible with message body or phone number redaction at this time.
Malformatted API parameters will return error 20001, instead of a dedicated error code
If you send an API request with a malformed or invalid parameter, such as a scheduled time that is >7 days from the present, you will receive an HTTP 400 response as expected. However, the Twilio error code returned will be the "20001" warning code, although the request failed. The API response will include a custom error description, along with the code 20001, to explain why the request failed.
Viewing Message Scheduling information in Console or via API
When viewing Messaging logs in your Twilio Console, a scheduled message will display the "scheduled" status, but will not show up when using the UI to filtering for "scheduled" status messages. They will show up under the "accepted" status filter instead.
This behavior also applies to GET requests on the /Messages endpoint: messages will appear with the "scheduled" status, but attempting to filter for messages with that status will not return results. Query for messages in the "accepted" status instead.
We do not yet have the ability to return the time a message was scheduled for in the API response, or in Messaging Logs in the Twilio Console.
Message Scheduling FAQs
Is Message Scheduling free?
Yes, scheduling messages is free of cost. You will pay for a scheduled message when it is sent, just like any other message.
Can I cancel messages before they are sent?
Yes, a message can be canceled before it is sent. Please see the API docs for a code sample.
Please note that repeatedly scheduling and canceling a large number of messages could consume your account's scheduled message cap. See "Limit of messages that can be in a scheduled state at any time" above for details.
Can I schedule messages more than 7 days in advance?
Currently, messages can only be scheduled up to 7 days into the future, at the time of the scheduling request.
If you have a strong business need for scheduling messages more than 7 days in advance, please let us know by talking to your Twilio account executive or contacting our Support team. We will provide your feedback to our Product team for consideration in future enhancements.
Which versions of the Twilio helper libraries support the new scheduling parameters?
Support for message scheduling was introduced in the following versions of the Twilio helper libraries. However we recommend that you use the most recent version of the libraries for maximum compatibility.