How to Use Validity Period for Promotional and Verification Use Cases

How to Use Validity Period for Promotional and Verification Use Cases

Here at Twilio, we've received a number of questions from our messaging customers around Validity Period as they are preparing for Black Friday and Cyber Monday. In this post, I will address some of the more common questions focusing on how to approach Validity Period for promotional and verification use cases.

What is Validity Period?

Validity Period refers to the number of seconds that messages you send will remain in Twilio’s platform before becoming stale (meaning the content of the message is no longer relevant). If the time required to send the message exceeds the Validity Period, Twilio fails the message, and sends a request to your status callback URL to notify your application of the failure.

How does Validity Period affect message requests?

Messages are checked for validity when they are dequeued to be sent to a carrier. Once the message is dequeued Twilio checks when the message was submitted, and compares the timespan that passed since then to the Validity Period the message was submitted with. If the Validity Period is less than the time that passed, Twilio will fail the message as it is no longer valid.   

For example, a messages that was submitted with 30 seconds validity period will fail if it was queued for 60 seconds.

Why should Validity Period be used?

Setting a Validity Period for messages ensures that your users will not receive stale messages due to delivery delays. There are a couple of reasons messages can be delayed:

• Not enough messages per second (MPS): Carriers around the world are expecting messages to be submitted at a predefined rate based on the sender type, the identity of the sender and the destination number. 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 and can experience delays.
• Service outages: As hard as we work to prevent them, service disruptions can happen. Your message may get enqueued until the service comes back up, which could result in delays. Validity period lets you rest assured that you’re covered in these rare occasions.

How to use Validity Period?

Validity Period can be set on a Messaging Service, and/or a Message. If different Validity Period settings are applied on a message and Messaging Service, the message setting will trump the Messaging Service setting.

Messaging Service

Setting the value of Validity Period on a Messaging Service can usually be done without changing production code, via the Integration tab of the Messaging Service:

This setting will apply for all messages sent via the Messaging Service unless there is a different Validity Period value specified with the message request.

Message request

Setting a custom Validity Period can be done for every message via the Message resource API by specifying the optional ValidityPeriod parameter.

What should Validity Period be set to?

The default value for Validity Period is 14400 seconds which translates to 4 hours, so if no value is provided, messages will expire after this time.

Validity Period requirements will change based on the specifics of the use case. As a general guideline, Twilio recommends setting the following values for promotional (marketing messages) and verification (one time passwords or two factor authentication) use cases:

Are there any counter productive ways to use Validity Period?

Yes. Validity Period is a powerful tool that ensures stale messages do not reach end users, and that failures to send messages at the expected latency will be reported promptly, but setting the wrong value can reduce deliverability or result in delivery delays.

It is important to set a value that will allow messages to queue for an acceptable period of time to allow fluctuations in outgoing messaging traffic to be balanced correctly, therefore it is recommended to set the highest value that is acceptable for the use case.

Validity Period of promotional and verification use cases

Hopefully, this post cleared up some of the questions you had around Validity Period and your promotional or verification use cases. For more information about Verification Period or anything else about messaging at Twilio, check out our docs.

We can't wait to see what you build!

Matan Gal leads Product Management for Messaging Services at Twilio, where he helps customers bring their messaging applications to the market faster.