What is message expiry?
Some text messages have a limited useful lifetime. If they’re not delivered within a certain period, they become useless. By default, Plivo expires messages that remain in the messaging queues after three hours. These messages are marked “failed” with error code 420 and are not charged to customers.
Why might a message expire?
When customers send a message through Plivo, it spends a short time in Plivo’s messaging queue before we forward it to a carrier. Typically this time is on the order of seconds, but it might be longer, typically due to messaging rate limits or an outage.
Each Plivo account and sender (the source number in the API) has an upper cap of how many messages it can handle, because we need to comply with carrier-level guidelines in each country. For instance, a short code in the US supports throughput of 100 messages per second. Sending messages at a higher rate results in queuing delays.
Another common cause of message expiry is an outage, either on Plivo’s side or on carriers’, that causes messages to be delayed.
In such cases your users might be getting messages at a time later than you expected — sometimes too late to be useful. A one-time password (OTP) that gets delayed by 15 minutes is no good when your application expects the OTP to be entered within one minute.
How can I customize the expiry of my messages with Plivo?
You can set the expiry time for each message with our send message API by passing the parameter message_expiry. Its default value is 10,800 seconds (three hours); you can set the expiry time to be 5 to 10,799 seconds.
When Plivo dequeues each message to send it to the carrier, we evaluate the time it has spent in Plivo’s messaging queue and compare that value with the expiry interval. If the elapsed time is more than the expiry period of the message, we mark the messages as failed and don’t charge for it.
What does Plivo recommend for message expiry values?
If your use case revolves around authentication, set message expiry to a value of between 60 and 600 seconds, depending on the time your application allows for a value to be input. For less time-sensitive use cases, such as promotional messaging, you can keep the default value of three hours or lower it to one hour (3,600 seconds).
Setting a too aggressive message expiry period might mean your messages don’t reach your customers, so choose your expiry period based on the upper limit of when the message will be useful.
You can check for message expiry by filtering your message log for an error code of 420.
If you see messages expiring frequently, you might be sending too many messages in too short a period, beyond the allowed limit for your account or number type. Your customer success manager or our support team can help you resolve the issue.