How do I resolve the "Unknown error attempting to reach phone" error from SMS through Amazon SNS or AWS End User Messaging?

Short description

You might receive the "Unknown error attempting to reach phone" error in your CloudWatch Logs for SMS messages because of multiple reasons. To turn on and view CloudWatch Logs for your SMS messages, see Viewing CloudWatch Logs.

To troubleshoot other type of SMS error messages, see How do I troubleshoot mobile text message (SMS) failures in Amazon SNS?

Important: The SMS architecture is distributed by design. It's a best practice to avoid 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

Check for common issues

Verify that the issue didn't occur because of the following reasons:

• The phone number is blocked by a carrier as spam.
• The destination is blocked.
• The message body isn't valid.
• The phone number is on a Do Not Disturb (DND) list.
• The phone is in a roaming network.
• The phone carrier blocked the message.
• The phone blocked 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's 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 the origination identity used is correct. If required, then register the identity. For more information, see Supported countries and regions for SMS messaging with AWS End User Messaging SMS.

If you send SMS messages to the US, then make sure that you use a supported origination number for the US.

If you use a toll-free number for the US, then make sure that the phone number is registered.

If you send SMS messages to India over local routes, then specify the Entity ID and Template ID values after you complete the registration process. Make sure that the Template ID that you specify matches your message template exactly.

Troubleshoot single device delivery issues

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

Complete the following steps:

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

If both steps are successful, then test 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, then 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 use to send SMS messages.

Provide the following information in your support case:

• The Region that you use 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) 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 3 days.

Important: SMS deliveries from CloudWatch Logs might not provide accurate SMS delivery times. SMS messages might deliver before you receive the CloudWatch Logs. 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 Logs.

Related information

How to manage global sending of SMS with AWS End User Messaging

Monitoring Amazon SNS topics using CloudWatch

What are the best practices for sending SMS messages?