Take More Control of Outbound Messages Using Validity Period

Better late than never…or is it? For some applications, it may be better for a message to fail completely than to arrive late. Now you have more control over your messages using  validity period. This period dictates how long you want Twilio to try to deliver your messages before failing with an error.

Imagine you subscribe to SMS traffic alerts for your daily evening commute home. You time your departure based on the alerts, but that day you get nothing. You drive off uninformed and steer right into Carmageddon 2.0. As you pull into your driveway three hours later, you get the text you were expecting three hours earlier. At this point the text serves no purpose other than to annoy you.

You, the developer, can save your users from this fate. Configure a validity period on those time-sensitive SMS messages.

Why Messages May Arrive Late

To better understand validity period, let’s look at some of the reasons messages may arrive late in the first place:

  • Not enough messages per second (MPS): Long code phone numbers can send 1 MPS by default in the US and Canada. Twilio Short Codes can handle up to 100 MPS by default in the US, Canada, and the UK (more info in this blog post). As a safeguard, Twilio handles carrier compliance for you by automatically rate limiting messages into the carrier network. So if your outbound messages are queueing at a higher rate, your messages will pile up. After sitting in the queue beyond the default validity period of 4 hours – or time you set – those messages will fail and won’t be sent.
  • Service outages: As hard as we work to prevent them, service disruptions can happen. Your message may get enqueued when the service comes back up, which could result in delays. Validity period lets you rest assured that you’re covered in that instance.

How to Set Validity Period

 

To set validity period, include the optional ValidityPeriod= parameter in your HTTP POST request to /2010-04-01/Accounts/{AccountSid}/Messages with the number of seconds that the message can remain in a Twilio queue. Valid values are between 1 and 14400 seconds< (the default), however we recommend avoiding validity periods of less than 5 seconds.   After exceeding this time limit, the message will fail and a POST request will later be made to your Status Callback URL. Please note that Twilio cannot guarantee that a message will not be queued by the carrier after they accept the message.   Finally, in case you needed one more reason to set validity period - you won’t pay for any messages that reach the validity period timer.   We can’t wait to see what you build!

  • > Please note that Twilio cannot guarantee that a message will not be queued by the carrier after they accept the message.

    Does this mean it’s possible that the validity period expires, and Twilio still sends the message on to the carrier and the carrier accepts it?

    • Ari Sigal

      Good question Alan, what I was trying to say was that Twilio would only send the message to the carrier before the validity period expires. However, its possible that the carrier then delivers the message after the validity period has expired. Does that make sense? Feel free to email me with questions ari [at] twilio [dot] com.

  • Viktor Gergely Bán

    Is this also available for SMS sent using TwiML (i.e. reply to an inbound SMS)?

    • Ari Sigal

      Hey Viktor, this isn’t available today, but it’s an interesting idea. Would love to learn more about what you’re working on. Feel free to email me directly as well ari [at] twilio [dot] com.