Front-End Web & Mobile
Introducing Worldwide SMS Messaging
Introduction
Earlier this week, Amazon SNS released worldwide SMS delivery and made it available in six AWS Regions. Worldwide SMS delivery means that you can now send SMS text messages directly to mobile phone numbers in more than 200 countries. Along with this expansion, SNS also enabled default “opt-in” of recipient phone numbers. This creates more possibilities for SMS messages, such as those needed for multi-factor authentication (MFA) or one-time passcodes.
In this blog post, we will cover notable changes from the previous SMS offering and highlight the new features. We’ll also describe SMS account-level configuration, show how to set up delivery status, and describe the new SMS API calls and message attributes.
What’s new with worldwide SMS delivery?
The following table shows the previous SMS offering and the features and options that are now available with the new worldwide SMS delivery from Amazon SNS.
| SMS (former capability) |
Worldwide SMS (new) |
| US-based phone numbers only. |
Global support of phone numbers in 200+ countries. The full list of supported countries can be found here. |
| Each phone number required “opt-in” from recipient prior to the developer sending messages. |
No opt-in required. |
| SMS delivery available in the us-east-1 Region only. |
Available in the following AWS Regions: us-east-1: US East (N. Virginia) us-west-2: US West (Oregon) eu-west-1: EU (Ireland) ap-northeast-1: Asia Pacific (Tokyo) ap-southeast-1: Asia Pacific (Singapore) ap-southeast-2: Asia Pacific (Sydney) |
| All US-based phone numbers required a subscription to an SNS topic with a display name; developers published to the topic. |
Developers can now directly publish to a phone number without requiring subscriptions to an SNS topic. They can also subscribe the phone number to an SNS topic and publish to the topic. |
| N/A |
Manage opted-out phone numbers in the AWS Management Console, API, CLI or SDK. More details here. |
| Delivery status available for application, Lambda, HTTP, and SQS protocols only. |
SMS has its own delivery status that can be configured per region. Delivery status can be enabled in the AWS Management Console, the AWS CLI, or SDK. |
| N/A |
Optionally set account (maximum spend per month) and message level (maximum spend per message) spend limits. |
| N/A |
Optional Daily SMS Usage Reports (in CSV) for successful and failed SMS deliveries. Set-up instructions can be found here. |
| All SMS text messages were delivered from the same Amazon short code: 30304. |
Amazon SNS uses a pool of long codes or short codes to send SMS notifications. Users will no longer receive messages from the 30304 short code. Additionally SNS sends messages from an AWS account to a phone number from the same long or short code (this is called the Sticky Sender ID). |
| N/A |
With worldwide SMS delivery, developers can choose between transactional or promotional message types to optimize for high delivery success or cost savings. More details can be found here. |
Notable Changes to existing SMS subscriptions
- All SMS phone numbers actively subscribed to an SNS topic will see a new long code or short code when a new message is delivered after June 28. After the new long/short code is established, recurring messages should come from the same code (though this is not guaranteed). This feature is called Sticky Sender ID.
- When a user sends “STOP”, the phone number will not be unsubscribed from the SNS topic. Instead, the phone number is added to the new “opted out” list that you manage. The SMS phone number that is subscribed to the SNS topic will still show subscribed even after a “STOP” request. However, if you publish to the SNS topic for which the opted out phone number exists, the delivery will fail and the failed message will be logged to Amazon CloudWatch Logs (if you enabled delivery status, of course).
SMS account-level configuration
You can set account-level text messaging preferences in the Amazon SNS console. In messaging preferences, you can specify account-level SMS message type, specify the spend limit, enable delivery status, provide a sender ID, and specify an Amazon S3 bucket to receive daily SMS delivery reports.
Here’s what the configuration screen looks like, including a description for each preference.
Delivery status
What is SNS delivery status?
SNS delivery status logs successful and unsuccessful SMS deliveries to Amazon CloudWatch Logs. Delivery status for SMS enables developers to collect logged data on successful and unsuccessful delivery attempts of their SMS messages to individual phone numbers. It also provides information about dwell times in Amazon SNS. Dwell times indicate: 1) how long it takes to deliver the message to the destination carrier from the time the message was published to SNS, and 2) how long it takes for the recipient carrier to acknowledge delivery of that message from the time the message was published to SNS. In addition, the price per message is logged so that you can manage your SMS costs.
Note: Delivery status plays a very important role in troubleshooting SMS deliverability. If you have issues with deliverability, consider enabling and configuring delivery status so that you can quickly identify and troubleshoot the issue.
Enabling delivery status
You can enable the delivery status feature for SMS with the Amazon SNS console, the AWS CLI, or the AWS SDKs. The simplest way is to enable delivery status using the SNS console, as described next.
Enabling SMS delivery status using the Amazon SNS console
Step 1: Log in to the Amazon SNS console.
Step 2: Navigate to Text Messaging (SMS).
Step 3: Select Create IAM role next to Default IAM role for success feedback.
Step 4: On the SNS is requesting permission to use resources in your account page, choose Allow. This allows Amazon SNS to gain write access to Amazon CloudWatch Logs on your behalf.
You should now see an IAM role as shown in the following example:
Example CloudWatch Logs
Delivery status for SMS creates two CloudWatch Log Groups: Successful and Failed. The groups have the following format:
Successful: sns/<region>/<accountID>/DirectPublishToPhoneNumber
Failed: sns/<region>/<accountID>/DirectPublishToPhoneNumber/Failure
Note: If one of the groups does not exist, then no logs have been delivered to that group, or the IAM role assumed by SNS does not have permission to write to CloudWatch Logs.
Example log for successful SMS delivery
The delivery status log for a successful SMS delivery looks like the following example:
Example log for failed SMS delivery
The delivery status log for a failed SMS delivery looks like the following example:
New APIs for SMS worldwide delivery
Along with the announcement of worldwide SMS delivery, there are new API calls and attributes for setting SMS preferences and text message delivery.
SMS Account Preferences
The following are the new API calls for setting and getting account SMS preferences:
SetSMSAttributes
GetSMSAttributes
The following are the new SMS account attributes for setting and getting SMS account preferences:
DefaultSenderID, MonthlySpendLimit, DeliveryStatusIAMRole, DeliveryStatusSuccessSamplingRate, DefaultSMSType, and UsageReportS3Bucket.
For all SMS attributes, see SetSMSAttributes and GetSMSAttributes in the Amazon Simple Notification Service API reference.
Sending a message
You can send an SMS text message through the SNS console, CLI, or SDK. Remember, you can now publish directly to the individual phone number without going through an SNS topic or first waiting for the user to opt in.
Note: When you send an SMS message, specify the phone number using the E.164 format. E.164 is a standard for the phone number structure used for international telecommunication. Phone numbers that follow this format have a maximum of 15 digits. They are prefixed with the plus character (+) and the country code. For example, a U.S. phone number in E.164 format would appear as +1XXX5550100.
To send an SMS message by using one of AWS SDKs, use the same SNS Publish action in the SDK that corresponds to the Publish request in the Amazon SNS API.
To directly publish to a phone number, you’ll use the new phoneNumber and message parameters of the Publish API.
Java
.withMessage(message) // Specify the text message sent to the mobile phone.
.withPhoneNumber(phoneNumber) // Specify the phone number using the E.164 format.
.withMessageAttributes(smsAttributes) // Specify one or more of the three new MessageAttributes shown next.
JavaScript
Message, PhoneNumber, and additional MessageAttributes
var params = { "Message": value, "PhoneNumber": value }
The following are the new MessageAttributes for the Publish API:
AWS.SNS.SMS.SenderID // (Optional) defaults to an SNS specified value, if not specified by the sender.
AWS.SNS.SMS.MaxPrice // (Optional) defaults to no max price.
AWS.SNS.SMS.SMSType // (Optional) defaults to "Transactional".
Tip: For Java, you will apply your attributes to the PublishRequest object of the Amazon SNS client.
Questions?
Check out the SMS FAQ here.
Resources
Happy text messaging!