Message Scheduling is Now in Public Beta

January 12, 2022
Written by
Reviewed by
Liz Yee
Chris Piwinski
Opinions expressed by Twilio contributors are their own
Dave Esber

Message Scheduling.png

With millions of developers sending and receiving more than 100 billion messages on Twilio every year, we’re focused on releasing the software and developer-friendly APIs that make your job easier.

One common request we heard was for the ability to schedule messages to be sent at a future date or time. With Message Scheduling, now in Public Beta, you can do just that! This is especially useful for common alerts and notifications use cases where you might wish to send a reminder or update a few days later. Using the Twilio Programmable Messaging API and the message scheduling Messaging Service feature, you can schedule  SMS, MMS, or WhatsApp messages for a future date and time and let Twilio handle the rest. Best of all, the feature is included for free, along with other sender selection, integration, content, and compliance software functionality.

Why we built Message Scheduling

While many SMS or WhatsApp messages are sent as triggered messages, use cases like appointment reminders, scheduled surveys or bill payment reminders require additional logic. Message scheduling removes dependencies on your server and backend to ensure that messages are being sent to your customer at the correct day and time. Before Twilio’s Message Scheduling feature you had a few different ways to handle something like this:

  1. Setting up cron jobs on your server to send out messages at a predetermined time. 
  2. Having your backend poll for events to send out messages at the right time.

With Message Scheduling, you can accomplish the same task, but with less code. You now have the ability to set a desired delivery timeline while making your API request to Twilio to send messages.

Note that Message Scheduling is designed to support messages that need to be scheduled between 15 minutes and 35 days in advance of distribution. If your use case requires different parameters, you can still use the aforementioned cron jobs or backend polling solutions. 

Through our pilot program, we heard from developers about the additional desire of being able to cancel a scheduled message if the need arises. As a result, using Twilio’s server-side helper libraries or an HTTP request to our REST API, we provide the capability to cancel the pending scheduled messages.

Message Scheduling allows you to introduce more sophistication to your messages based on business requirements, such as scheduling them to be sent before, during or after business hours depending on the nature of your messages to promote customer engagement. As an added benefit, having your messages scheduled in advance takes away the worry of hitting API rate limits while sending a very large number of messages in a short span of time. However, it’s worth noting that using Message Scheduling has no effect on your message throughput (MPS) or your maximum queue length.

Message Scheduling in action

What’s Required

  • A free Twilio account (sign up for free using this link and receive $10 in credit when you upgrade your account!)
  • A Twilio Phone Number
  • A Messaging Service in your Twilio Account (Message Scheduling is only accessible with Messaging Services)
  • Familiarity with using Command Line (Terminal) or an API Platform such as Postman to make HTTP requests to Twilio

Use Case

One of the benefits of Message Scheduling is that it allows you to create something similar to an email journey flow using messages. When a customer does a particular action, you can schedule all the messages tied to that flow at once. Without Message Scheduling, you need to have a script or a job that runs periodically, scans for anyone eligible to receive a message, and then sends the messages at different points in time. Whereas, by scheduling messages, you can do this ahead of time with the confidence that the messages will go out in time. Additionally, you can cancel and reschedule updated messages as necessary.

To demonstrate this, the following example will create a multiple touchpoint appointment reminder for a patient with Message Scheduling.

This workflow has three main steps:

  1. Adding your Twilio phone number to a Messaging Service
  2. Scheduling two appointment related messages for the patient to be sent out at different points in time
  3. Canceling one of the scheduled messages due to appointment cancelation

Step 1: Adding Your Twilio Phone Number to Your Messaging Service

Since Message Scheduling is only accessible with Messaging Services, you need to add your Twilio phone number to your Messaging Service. This can be done by following the steps mentioned here. Once you have completed this step, you should note down your Messaging Service SID from the Service’s Properties page on Twilio’s Console as this will be one of the parameters in our HTTP request while scheduling messages.

Step 2: Scheduling Your Appointment Reminders

Once an appointment has been booked, we will be scheduling the following appointment related messages:

  1. Message 1: An SMS reminder to be sent out 24 hours prior to the appointment
  2. Message 2: An MMS to be sent out 3 hours prior to the appointment with a QR code for the patient to check-in on arriving at the place of appointment

In a new terminal session (remember not to close your ngrok session from step 1), run the following curl command to schedule Message 1:

curl -X POST$TWILIO_ACCOUNT_SID/Messages.json \
--data-urlencode "Body=This is a reminder about your appointment tomorrow at 3PM with Dr. Strange" \
--data-urlencode "MessagingServiceSid=<Your Messaging Service SID From Step 1>" \
--data-urlencode "To=<Your Patient's E.164 Formatted Phone Number>" \
--data-urlencode "ScheduleType=fixed" \
--data-urlencode "SendAt=<Scheduled UTC Date Time in ISO-8601 Format>" \

While running the above command on your terminal, remember to replace <Your Messaging Service SID From Step 1> with your actual Messaging Service SID, <Your Patient’s E.164 Formatted Phone Number> with the recipient’s E.164 formatted phone number, and <Scheduled UTC Date Time in ISO-8601 Format> with the UTC date and time you want to send the message on in ISO-8601 format (for example: 2022-01-01T14:00:00Z). You also need to make sure that your TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN are correctly stored as environment variables. Once you send the HTTP request, you will see a response which includes your message SID. Make sure you save your message SID as it would be handy in case you need to cancel your scheduled message!

Here is an example of what your response would look like:

"sid": "SM93b9cd1adf4045c592cd30984d8d4f32", "date_created": "Fri, 31 Dec 2021 07:56:51 +0000",
"date_updated": "Fri, 31 Dec 2021 07:56:51 +0000", "date_sent": null, "account_sid": "REDACTED",
"to": "+17815367324", "from": null, "messaging_service_sid": "REDACTED",
"body": "This is a reminder about your appointment tomorrow at 3PM with Dr. Strange",
"status": "scheduled", "num_segments": "0", "num_media": "0", "direction": "outbound-api",
"api_version": "2010-04-01", "price": null, "price_unit": null, "error_code": null, "error_message": null,
"uri": "/2010-04-01/Accounts/REDACTED/Messages/SM93b9cd1adf4045c592cd30984d8d4f32.json",
"subresource_uris": {"media": "/2010-04-01/Accounts/REDACTED/Messages/SM93b9cd1adf4045c592cd30984d8d4f32/Media.json"}

You can also verify that your message has been scheduled on the Programmable Messaging Logs of your Twilio Console with the status ‘Scheduled’:

Programmable Messaging Logs

Next, we will schedule an MMS with a check-in QR code to be sent out 3 hours before the appointment. Run the following curl command to schedule Message 2:

curl -X POST$TWILIO_ACCOUNT_SID/Messages.json \
--data-urlencode "MediaUrl=" \
--data-urlencode "Body=This is a reminder about your appointment tomorrow at 3PM with Dr. Strange" \
--data-urlencode "MessagingServiceSid=<Your Messaging Service SID From Step 1>" \
--data-urlencode "To=<Your Patient's E.164 Formatted Phone Number>" \
--data-urlencode "ScheduleType=fixed" \
--data-urlencode "SendAt=<Scheduled UTC Date Time in ISO-8601 Format>" \

While running the above command make sure to replace the placeholder values with your actual values similar to Message 1. Running the above command will return a similar response to Message 1 and will also be verifiable on the Programmable Messaging Logs of your Twilio Console with the status ‘Scheduled’. Once again, do not forget to store your message SID.

Step 3: Canceling a Scheduled Message

To cancel a scheduled message, we need to make an HTTP POST request to the Message resource by specifying the SID of the message you want to cancel and updating its status to ‘canceled’. Run the following curl command to cancel a scheduled message:

curl -X POST$TWILIO_ACCOUNT_SID/Messages/MM12719a98409c41eaac88267848290859 \
--data-urlencode "Status=canceled" \

Once your message has been canceled, you should be able to verify the same on the Programmable Messaging Logs of your Twilio Console which should look like this:

Programmable Messaging Logs

Important Considerations While Using Message Scheduling

Please note the following important considerations while setting Message Scheduling:

  • Message Scheduling is only accessible with Messaging Services. You must set up your Messaging Services before scheduling messages
  • Messages can only be scheduled at least 15 minutes into the future and up to 35 days in advance
  • Remember to specify the scheduled time as UTC Date-Time in ISO-8601 format only
  • Always save your Message SID when you schedule your messages as you will need this if you need to cancel them
  • A message cannot be canceled once it has been sent out by Twilio and has reached a finalized state.

Get started

Prior to today, if you wanted to send appointment reminders to customers, you would have to either separately track and send reminders to each end user or you would have to send all messages at once. 

Now you can schedule messages in the future to accommodate different factors such as time zones or business hours. You also have the ability to introduce more sophistication into who gets what and when based on business requirements.

Message Scheduling is available to you at no additional cost as part of our Messaging Services features. You can learn more about all the other features available to you when using Messaging Service in the Docs.

We can’t wait to see what you build!

Shashwat Johari is a Solutions Engineer at Twilio and a lifelong technology enthusiast currently living in the world of Twilio’s APIs. Shashwat would love to hear your feedback on Message Scheduling at sjohari [at]