Authy and Verify One-Time-Passcodes (OTPs) sent via SMS text messages may not arrive at their destination due to a number of possible causes. This guide covers some of the most common issues developers may encounter, as well as workarounds.
Notice: After November 1, 2022, we started to deprecate the service for SMS/Voice in the Authy API. Any requests sent to the API after May 1, 2023, will automatically receive an error.
SMS text message troubleshooting
SMS is considered a “best effort protocol”, as we can only confirm the message has been successfully delivered to the sending carrier. That said, there are several steps that can be taken for troubleshooting message delivery.
Verify SMS OTPs
Records from OTP messages sent via Verify can be found in your service's Logs in Console. These records show the SMS's delivery status, and any error codes flagged in the delivery of the message.
Here's an example of what a failed message looks like:
Click the timestamp of a failed attempt to view more details about the message, including a link to troubleshooting for any error codes present.
Destination device troubleshooting
If your OTP message shows that it was successfully delivered, you'll want to check with your end user to ensure they are able to successfully receive text messages. If end users are reporting missing OTP SMS from your app, please troubleshoot with the following checklist:
- Do you have the right phone number on file for your end user?
- Is the user’s device powered on?
- Does their device have sufficient signal? If not, have them power the device off, wait 30 seconds, and then power it back up.
- Is the device connected to the home carrier's network? Message delivery on devices roaming internationally, or off-network, are more likely to fail due to the extra message hops involved and some users having restrictive messaging plans.
- Can the device receive SMS from other sources? Some mobile providers may block messages from certain senders or number types - check with the carrier for more details.
- Can other devices using the same mobile carrier receive your messages?
If you can rule out all of the above issues, and non-Authy/Verify text messages are working correctly, an alternative to sending SMS OTPs may be a better temporary solution:
- Attempt to deliver OTPs via a phone call
- Have the end user download and install the Authy app (for Authy API verification only)
Notice: If you are experiencing continued, repeatable SMS delivery issues to the same destination country with Verify, please collect 3 or more logs from the last 24 hours, and then escalate these issues to our Twilio Messaging Support team.
Use a phone call for delivering OTPs
Phone calls usually arrive much faster than SMS, and can be a good alternative to users experiencing issues receiving messages. If 2FA codes are not arriving via SMS, have your end user attempt to receive the token via phone call.
Please note, this method will require the user to answer a live phone call, as they will need to enter codes into the phone. To successfully receive a 2FA code, the number used can’t be behind an extension or go straight to voicemail.
Use the Authy app for 2FA codes (for Authy API only)
If your user is unable to receive calls or messages, they may have better results using the Authy app. Once configured with your 2FA tokens, the Authy app can be used to provide updated codes without the need for a constant internet connection.
Users can find instructions here: Downloading and Installing Authy Apps