How do I resolve the "Unknown error attempting to reach phone" error in Amazon SNS or the "UNKNOWN" error in Pinpoint when sending SMS?

Short description

An SMS message is delivered to mobile devices through third-party downstream aggregators, SMS suppliers, and mobile carriers. That is, when you use SMS with Amazon SNS, Amazon Pinpoint, or any AWS service that integrates with either Amazon SNS or Amazon Pinpoint. You receive the "Unknown error attempting to reach phone" error when these downstream partners can't reach the mobile device.
Important: the SMS architecture is distributed by design. It's a best practice to avoid making assumptions about the reliability and performance of SMS message transmission for your applications. For more information, see RFC 5724 from the Internet Engineering Task Force (IETF).

Resolution

Follow these troubleshooting steps for your use case.

Check for common issues

Rule out common issues that are not related to Amazon SNS or Amazon Pinpoint.
You can receive the error for the following reasons:

• The phone number is blocked by a carrier as spam.
• The destination is blocked.
• The message body is not valid.
• The phone number is on a Do Not Disturb (DND) list.
• The phone is in a roaming network.
• The phone carrier is blocking the message.
• The phone is blocking SMS.
• The phone is temporarily out of the coverage area.
• The phone is turned off.
• The phone is a landline number (not a mobile phone).
• There is an unregistered URL in the message body.
• The mobile number isn't valid.
• Downstream partners have incorrect network configurations for a given number or set of Regional numbers.

Review SMS best practices

Confirm that you're following SMS best practices, rules, and regulations for the destination country or AWS Region where you send your SMS messages.
Confirm that you're using the correct origination identity. If required, the identity must be registered. For more information, see Supported countries and Regions (SMS channel).
If you send SMS messages to the US, make sure that you are using a supported origination number for the US.
If you use a toll-free number for the US, make sure that the phone number is registered.
If you send SMS messages to India using local routes, first preregister your dedicated alphabetic sender ID. Then, use the DLT registered template. When adding content to SMS messages, make sure that it exactly matches the content in the DLT registered template. For more information, see Sender ID registration requirements for India.

Troubleshoot single device delivery issues

Device-level SMS blocking, roaming, coverage gaps, and other factors can cause single device delivery issues.
To troubleshoot these issues:

1. Use the Amazon Pinpoint API to validate the phone number. Using landline and VoIP phone numbers might cause delivery issues.
2. Send an SMS message from another device, and then check if the message was delivered.

If both of these steps are successful, then consider testing on other devices.
If the issue persists, then the device owner must contact their mobile carrier for support.

Troubleshoot multiple device delivery issues

If delayed SMS delivery affects multiple devices, there might be issues with downstream aggregators, suppliers, providers, and carriers.

To troubleshoot potential downstream issues, create a support case for the service that you're using to send SMS messages.
Provide the following information in your support case:

• The Region that you're using to send SMS messages.
• A timestamp of when the issue started.
• Three samples of SMS logs with the message IDs of failed SMS messages to different phone numbers not older than three days.
• (India only) Provide your DLT registered entity ID, template ID, and a sample of the content used to send the SMS messages.

Note: Mobile carriers might not store SMS information for more than three days.
Important: SMS deliveries from Amazon CloudWatch Logs don't always provide accurate SMS delivery times. In some cases, SMS messages can be delivered before CloudWatch logs are received. The dwellTimeMsUntilDeviceAck value in the delivery logs shows when the carrier accepted the message, but doesn't provide information on delayed SMS messages. For more information, see Viewing CloudWatch metrics and logs for SMS deliveries.

Related information

How to manage global sending of SMS with Amazon Pinpoint
Monitoring Amazon SNS topics using CloudWatch