Troubleshooting the SMS channel

Verify that logging is turned on to assist in identifying the cause of failure. For more information, see Monitoring and logging.

SMS delivery failures

Issues and solutions

• Confirm that the number is valid using the Amazon Pinpoint number validator. SMS delivery is supported for ‘MOBILE’ phoneType. SMS delivery to ‘VOIP’ numbers might not be successful, but will be attempted on a best effort.

• Confirm that your monthly SMS spend quota isn't depleted by reviewing the TextMessageMonthlySpend metric in Amazon CloudWatch. For more information see Monitoring SMS and voice spending in the Amazon Pinpoint SMS User Guide.

• If the delivery issue is limited to one or two devices, then rule out device-related issues. Verify that the number(s) can receive SMS outside of Amazon Pinpoint at the time of the failure.

• Turn on SMS event logging to assist in identifying the cause of the failure.

  • Review the message status.

  • Review how to resolve Unknown error attempting to reach phone.

• Take note of the special requirements and regulations. See Supported countries and regions (SMS channel) in the Amazon Pinpoint SMS User Guide, and confirm that these requirements are being met.

SMS delivery delays

Issue and solution

• SMS delivery issues can occur for many reasons. This is because of the distributed path through which the message travels after leaving the AWS infrastructure. For example, device-related issues may be the result of poor network coverage.

• As a best practice, measure SMS delivery delays by comparing the message sent time and the received time of the destination device.

• Message Parts per Second (MPS) limits in the Amazon Pinpoint SMS User Guide related to the original identity can also introduce delays.

SMS two-way

Two-way SMS responses are not received on either the SNS topic, subscribers, or both.

Issues and solutions

• Verify that you have a number with two-way SMS enabled for a country where the feature is supported. See Supported countries and regions (SMS channel) and Two-way SMS messaging in the Amazon Pinpoint SMS User Guide.

• Verify that the sender number is from the same country as the two-way SMS-enabled number in Amazon Pinpoint.

  • An inbound SMS that is sent from a number outside of the country might fail to be delivered to Amazon Pinpoint. Deliverability is affected by factors like telecom local rules and regulations across countries. International SMS deliveries are attempted at a maximum effort.

  • If the sender number isn't from the same country as the two-way SMS activated number in Amazon Pinpoint, and the source country of the sender number supports two-way SMS, then a long or short code can work for users in the country. See Choosing a phone number or sender ID in the Amazon Pinpoint SMS User Guide.

• Verify that the sender number is a valid mobile number and not a virtual number by using the Amazon Pinpoint Phone Number validator API. Communication between two virtual numbers, like the ones in Amazon Pinpoint, will be attempted at a maximum effort.

• Review Amazon SNS CloudWatch metrics for NumberOfMessagesPublished, NumberOfNotificationsDelivered, and NumberOfNotificationsFailed to verify if the Amazon SNS topic is able to receive the inbound SMS.

  • If there are data points for NumberOfMessagesPublished at the time of the inbound SMS timestamps, then the recipient response was successfully received from downstream. They then attempted to reach Amazon SNS subscribers from Amazon Pinpoint. However,there's a configuration or delivery issue between Amazon SNS and the destination endpoint. To troubleshoot, activate logging on the Amazon SNS topic for the delivery protocol being used. See Amazon SNS message delivery status.

  • If there are data points for the NumberOfMessagesPublished metric at the time of the inbound SMS timestamps:

    • Review the Amazon SNS topic policy to confirm that it allows the Amazon Pinpoint service to publish to the Amazon SNS topic. For an example policy, see Two-way SMS messaging in the Amazon Pinpoint SMS User Guide.

    • If the Amazon SNS topic linked to the two-way SMS number is encrypted:

      • Verify that the key used is symmetric.

      • Verify that the key policy is modified to allow Amazon Pinpoint to use the key, see Amazon SNS topic policies for Amazon SNS topics in the Amazon Pinpoint SMS User Guide.