Provisioning and using 10DLC origination numbers with Amazon SNS

Effective June 1, 2021, US telecom providers require one of the following types of origination numbers be used for application-to-person (A2P) text messaging (SMS) to US destinations:

An origination number is a numeric string that identifies the SMS message sender. This blog post explains how customers using Amazon SNS to send text messages to US destinations can migrate to 10DLC origination numbers. This can help to ensure that their SMS workloads are successful under the new requirements.

Background

On March 1, 2021 a new standard for A2P messaging came into effect with the introduction of 10DLC. In preparation for this, SNS announced support for ten-digit long codes in February 2021. This allows customers to use 10DLC phone numbers to send SMS text messages at scale quickly and affordably.

Customers sending SMS messages with SNS to US destinations should migrate to 10DLC origination numbers from June 1 2021 to avoid service disruptions. This only applies to you if you are sending messages to recipients in the US.

Migrating to 10DLC

You can request a 10DLC number using Amazon Pinpoint– a multichannel marketing communication service. First register your company and campaign to add the information to the Campaign Registry (TCR). This is an industry-wide database of companies and use cases that are authorized to send messages using 10DLC phone numbers. After you complete these registrations, request a phone number and associate it with a 10DLC campaign.

The following steps explain how to migrate SNS messaging to use 10DLC origination numbers.

Registering your company and 10DLC campaign

Choose SMS and Voice from the settings page of the Pinpoint console.
Choose Register your Company. Enter the required company information and choose Register. Refer to the documentation for detailed explanation of the information that is required.
Choose Create a 10DLC campaign, add the use case details and choose Create. The documentation contains detailed instructions on how to complete this form.

Requesting a 10DLC number

Choose SMS and Voice from the settings page of the Pinpoint console.
On the Phone numbers tab, choose Request phone number.
On the Define your phone numbers page, for Country, choose United States.
In the Number type section, choose 10DLC. Assign the number to the 10DLC campaign created in the previous steps.To learn more about the appropriate default message type and quantity refer to Requesting a number in the Amazon SNS developer guide.
After purchasing the phone numbers, choose Next. Verify that the information is correct and choose Request.

There are registration and monthly fees associated with using 10DLC, such as registering your company and 10DLC campaign. These are separate from any other monthly or AWS fees. To learn more about 10DLC fees, visit the Amazon SNS Worldwide SMS Pricing page.

Sending an SMS message using a 10DLC

Use SNS to send messages to SMS-enabled devices. Publish messages directly to the phone numbers for these devices using the AWS Management Console, or programmatically via the AWS CLI for SNS or AWS SDKs:

Using a 10DLC with the AWS SDK

To send an SMS message using one of the AWS SDKs, use the `MessageAttributes` parameter to set the value for the 10DLC. The following example application in the Serverless Patterns Collection shows how to implement this with the AWS javascript SDK.

An AWS Serverless Application Model (AWS SAM) template defines an AWS Lambda function with the required SNS permissions to publish a message directly to a phone number. Follow these steps to clone and deploy the example application.

This deploys a Lambda function with the following function code:

/*! Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *  SPDX-License-Identifier: MIT-0
 */
const AWS = require('aws-sdk')
AWS.config.region = process.env.AWS_REGION 
const sns = new AWS.SNS({apiVersion: '2012-11-05'})
// The Lambda handler
exports.handler = async (event) => {
  // Params object for SNS
  const params = {
    Message: `Message at ${Date()}`,
    Subject: 'New message from publisher',
    PhoneNumber: process.env.phoneNumber, // recipient phone number goes here
    MessageAttributes:{
      'AWS.MM.SMS.OriginationNumber':{
        'DataType':'String',
        'StringValue':process.env.tenDLC // your 10DLC goes here
      }
    }
  }
  
  // Send to SNS
  const result = await sns.publish(params).promise()
  console.log(result)
}

The 10DLC is passed to the messageAttributes parameter from an attributed named AWS.MM.SMS.OriginationNumber. The 10DLC value is set by an environment variable and is displayed as the sender’s phone number on the receiver’s device.

I invoke the Lambda Function with the AWS CLI:

aws lambda invoke --function-name lambda-sns-sms-SMSPublisherFunction-zV8HOwE6YEg4  response.json

The following response is returned:

{"ResponseMetadata":{"RequestId":"7eb3c17c-5bec-57d7-8a65-9859a532e92f"},"MessageId":"20c73250-d35f-5377-8d35-6b752d81dd8f"}

Using a 10DLC in the AWS Management Console

You can use the 10DLC to send an SMS message with SNS directly from the AWS Management Console.

1. In the SNS console, choose Text messages (SMS), from the Mobile menu.
2. Choose Publish Text message, and input the destination phone number and message into the relevant fields.
3. Enter your 10DLC into the Origination number field from Origination Identities section. Choose Publish message.
  
  The SNS console shows the Message ID and Request ID:

Viewing Amazon CloudWatch Logs for SMS deliveries

To collect information about successful and unsuccessful SMS message deliveries, enable SNS to write to Amazon CloudWatch Logs. Follow these steps to enable and view CloudWatch Logs for your SMS messages.

The delivery status log for the previous SMS delivery is shown in the following example:

Alternatives to 10DLC

As an alternative to 10DLC, you can purchase a Toll-Free Number (TFN), or a short code. TFNs have a maximum of three TPS but are cost effective. Short codes have higher default throughput. For more information, refer to Origination Numbers in the Amazon SNS Developer Guide.

Conclusion

This blog post explains how to obtain a 10DLC origination number using Pinpoint. The 10DLC can be used to send application-to-person (ATP) SMS messages to US destinations at scale quickly and affordably. Customers should do this to avoid service disruptions.

This blog post also shows how to use a 10DLC origination number to send SMS messages with SNS. An example application is provided in the serverless patterns collection demonstrating how to implement a 10DLC using the AWS SDK in a Lambda function.

For more information regarding 10DLC origination numbers refer to the SNS developer guide.

AWS Compute Blog