Take More Control of Outbound Messages Using Validity Period

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!