Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-implement-self-managed-opt-outs-for-sms-with-amazon-pinpoint/

Amazon Pinpoint offers marketers and developers the ability to send SMS to over 240 countries and/or regions around the world; giving users the global reach, scalability, cost effective pricing, and high deliverability that is required to build a successful SMS program. SMS is a flexible communication channel that facilitates different business requirements, including One-Time Password (OTP), reminders, and bulk marketing to name a few. Regardless of the content that you are sending via SMS there is a requirement to manage your recipients’ opt-in/out status. Read on to learn your two options for managing opt-outs and how you can configure them. Amazon Pinpoint offers a fully managed opt-out capability and the ability to self-manage the process with your own tools.

NOTE: If you are sending to US numbers with a toll-free (TFN) number the carriers will automatically manage those numbers and are not eligible for either of these processes.

Managed Opt-Out Process
If you prefer to have Pinpoint manage your opt-out processes you can refer to our blog “How to Manage SMS Opt-Outs with Amazon Pinpoint” to learn how to configure keywords and opt-out lists.

Self-Managed Opt-Out Process
Many customers use Pinpoint’s Managed Opt-Out process to deliver their communications, but some scenarios require the ability to self-manage this process. Self-managing the opt-out process provides more granular control over customer communication preferences and allows customers to centralize those preferences within their own applications.
Common reasons for organizations to implement self-managed opt-out include but aren’t limited to:

1. Have an existing self-managed opt-out capability with a standing toolset that is already integrated with other aspects of their communication stack.
2. Need multiple options for their customers to manage the communication preferences such as a web portal, call center, and mobile application to name a few.
3. Require full control in order to implement custom logic that caters to their business needs.
4. Want to change their SMS provider to Pinpoint while not changing what they have already built within an existing application.

How to implement Self-Managed Opt-Outs with Pinpoint
Choosing to self-manage your opt-outs requires some configuration within Pinpoint and the use of other AWS services. The solution outlined in this blog will use Amazon Pinpoint in addition to the following services:

1. AWS Lambda
2. Amazon DynamoDB
3. Amazon SNS

NOTE: If you have existing services/applications that allow you to implement similar functionality as explained in this blog, you don’t have to use these services listed above.

What’s in scope?

This blog covers the following scenario:

1. SMS is being sent with Amazon Pinpoint SMS and Voice V2 API – SendTextMessage
2. You specify the Origination Identity (OID) to be used (short code, long code, 10DLC, etc) as the parameter to send the SMS to the destination phone number.

While the following scenarios can be self-managed this blog does not cover the following cases:

1. You use a phone-pool to send SMS.
2. You do not specify an OID in your call SendTextMessage call and let Amazon Pinpoint figure out and use the appropriate OID.

Keywords in scope

1. Opt-out keywords – All Opt-out keywords mentioned in this document are included in the code.
2. Opt-in keywords – This blog considers ‘JOIN’ as a valid keyword that SMS recipients can respond with to opt back in for the SMS communication.

NOTE: The code examples in this blog can be modified to add any additional custom keywords for your use case.

Assumptions/Prerequisites

1. You have the necessary permissions to configure the following services in the same AWS account and region where Amazon Pinpoint is implemented.
   a. AWS Lambda
   b. Amazon DynamoDB
   c. Amazon SNS
2. Your instance of Amazon Pinpoint has at least one OID approved and provisioned to send SMS.
   a. If you need help to determine what OID fits your use case(s) use this guide
   b. NOTE: Sender IDs do not have an ability to receive 2-way communication. If you are using Sender IDs, you still must manage opt-outs, but must do so by offering alternative ways of opting out such as a web portal, call center, and/or mobile applications.

Solution Overview

The solution proposed in this blog is fully serverless arhitecture and uses AWS managed services to eliminate a need for you to maintain and manage any of the infrastructure components.

1. Your application invokes AWS Lambda function ‘InvokeSendTextMessage’ which calls Amazon Pinpoint SMS and Voice V2 API – SendTextMessage.
2. The AWS Lambda function called ‘InvokeSendTextMessage’ performs the following tasks:
   2a. Fetches the latest item based on the descending order of the timestamp with the destination phone number and OID from Amazon DynamoDB table ‘SMSOptOut‘.
   2b. If an item is found with the customer response as any valid keyword for Opt-out (Refer section Keywords in scope), the process stops and Amazon Pinpoint APIs won’t be called by InvokeSendTextMessage function as the customer chose to opt-out.
   2c. If an item is not found or is found with the customer response as any valid keyword for Opt-in (Refer section Keywords in scope), the function calls Amazon Pinpoint SMS and Voice V2 API – SendTextMessage to deliver it to the customer/destination phone number.

NOTE: Amazon DynamoDB table can also be configured to receive the Opt-out or Opt-in information through various other channels (app, website, customer care etc.) if you have multiple interfaces for customer to do so but that is not in the scope for this blog.

Refer to the section, ‘InvokeSendTextMessage function code’ to understand the sample AWS Lambda function code. The code uses Python 3.12 language.

3. The message is successfully delivered to a destination phone number.
4. If the customers responds to the same OID (because you have enabled 2-way SMS feature) with a keyword that is a valid value from all the keywords in scope (Refer section Keywords in scope), Amazon SNS topic is configured with Amazon Pinpoint which captures the customer response.
   Note: The other keywords are not in scope for this blog, but you can specifically add all possible keywords that customers can respond with. There can be an accidental responses by a customer which will be ignored by the AWS Lambda code.
5. AWS Lambda function ‘AddOptOutInDynamoDB’ is a subscriber to the topic in Amazon SNS and processes customer responses.

6. AWS Lambda function ‘AddOptOutInDynamoDB’ performs few tasks as described below
7. 6a. If the customer response is a keyword that is a valid value from all the keywords in scope (Refer section Keywords in scope), Amazon Lambda function ‘AddOptOutInDynamoDB‘ extracts the OID and customer phone number information from the response and adds the entry in the Amazon DynamoDB table ‘SMSOptOut’. This way Amazon DynamoDB table keeps getting latest customer opt-in/opt-out status.
   6b. Once the item is successfully put in dynamodb table ‘SMSOptOut‘, if the customer response was any Opt-out keyword (Refer section Keywords in scope), the function sends a SMS to the customer who has just opted out to confirm the status. “YOU HAVE BEEN UNSUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT “JOIN” TO THIS NUMBER TO BE RESUBSCRIBED”.
   If the customer response was any Opt-in keyword (Refer section Keywords in scope) the function sends a SMS to the customer who has just opted back in to confirm the status. “YOU HAVE BEEN SUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT “STOP” OR “UNSUBSCRIBE” TO THIS NUMBER TO BE UNSUBSCRIBED”. (But SMS recipients can still respond with any valid keyword mentioned in Opt-out keyword list)

NOTE: Refer the section ‘AddOptOutInDynamoDB function code’ to understand the sample code. The code uses Python3.12 language.

7. The Opt-in/Opt-out status confirmation SMS is successfully delivered to a customer/destination phone number.

Amazon Pinpoint setup

1. Enable 2-way SMS messaging for the OID that you procured. Refer to the screenshot below for your reference.

2-way SMS setting:

2. Enable the self-managed opt-out feature for the OID. Once enabled, Amazon Pinpoint does not respond to opt-out messages sent to the SNS topic by your recipients. You can collect the response from the customers in an AWS SNS topic and process it as per your business needs.

Self Managed Opt-Out feature setting:

Amazon SNS setup

1. On Amazon SNS console, click on ‘Topics’ and then ‘create a topic’ as shown below.

2. Click ‘Create Subscription‘ to add the Lambda function ‘AddOptOutInDynamoDB‘ as a subscriber by using the Amazon Resource Name (ARN).

Amazon DynamoDB Setup

Table Name: ‘SMSOptOut‘

The Customer phone number is used as the primary key(PK). The sort key(SK) contains multiple values that include OID, timestamp, and the customer response separated by #. By having generic attribute names as PK and SK, you can expand the usage of this table for accommodating any custom business needs. For example: Customer can use any of the individual phone numbers like short code, long code, or 10DLC to send the SMS and any of these values can be accomodated as a part of the sort key (SK). The sort key can be used for granular retrieval to see the latest customer status (For example: ‘STOP‘). It can then additionally have attributes like OID, Timestamp, Response and others as per your requirements. The table uses On-demand Read/Write capacity mode. Refer to this document to understand On-demand capacity mode in detail.

Sample item in DynamoDB table is below

InvokeSendTextMessage function code

This AWS Lambda function calls Amazon Pinpoint SMS and Voice V2 API – SendTextMessage. It uses Query API for DynamoDB to scan the items for SourcePhoneNumber (customer phone number) and OID (Part of SK) in descending order of the timestamp. If an item exists with customer response value is a valid keyword for Opt-out (Refer section Keywords in scope), it means the customer has opted-out and the SMS can’t be sent. If no item is found or the customer response value is a valid keyword for Opt-in (Refer section Keywords in scope), the customer can be contacted and the funtion calls SendTextMessage API with the same OID and customer phone number.

import boto3
import os
from boto3.dynamodb.conditions import Key, Attr
import json

dynamodb = boto3.resource('dynamodb')
table = dynamodb.Table('SMSOptOut')
pinpoint = boto3.client('pinpoint-sms-voice-v2')
OptOutKeyword = ['ARRET','CANCEL','END','OPT-OUT','OPTOUT','QUIT','REMOVE','STOP','TD','UNSUBSCRIBE']
OptInKeyword = ['JOIN']

#adds item in the DynamoDB table
def query_table(OID, SourcePhoneNumber):
    try:
        response = table.query(
            KeyConditionExpression=Key('PK').eq(SourcePhoneNumber) & Key('SK').begins_with(OID),
            ScanIndexForward=False,
            Limit=1
        )
    except Exception as e: 
        print("Error when writing an item in DynamoDB table: ",e) 
        raise e
    return response

#send opt-in/opt-out confirmation text using send_text_message.
def send_confirmation_text(SourcePhoneNumber,OID,messageBody,messageType): 
    
    try: 
        response = pinpoint.send_text_message(DestinationPhoneNumber=SourcePhoneNumber, 
        OriginationIdentity=OID,
        MessageBody=messageBody, 
        MessageType=messageType 
        ) 
    except Exception as e: 
        print("Error in sending text message using Pinpoint send_text_message api:", e) 
        raise e

#gets the message from SNS topic
def lambda_handler(event, context):
    OID = event['OID']
    SourcePhoneNumber = event['SourcePhoneNumber']

    response=query_table(OID, SourcePhoneNumber)
    items = response['Items']
    
    #Count number of items. The value will be either 1 or 0.
    count = len(items)

    # If the latest customer response is any OptOutKeyword
    if count == 1 and items[0]['Response'] in OptOutKeyword:
        print("Exit : Customer has opted out, do not send SMS")
    # If the latest customer response is any OptOutKeyword
    elif count == 0 or (count == 1 and items[0]['Response'] in OptInKeyword):
        send_confirmation_text(SourcePhoneNumber,OID,'This is a test message from Amazon Pinpoint','TRANSACTIONAL')
    # Only allowed values for customer response are valid OptOutKeyword or OptInKeyword 
    else: 
        print("The customer response is not one of the allowed keyword")

AddOptOutInDynamoDB Lambda function code

For example: When customer responds with ‘STOP’, the response is captured in the SNS topic that you configured with Amazon Pinpoint. The response json looks as shown below –

{
"originationNumber": "+1224xxxxxxx",
"destinationNumber": "+1844xxxxxxx",
"messageKeyword": "KEYWORD_xxxxxxxxxxxx",
"messageBody": "STOP",
"previousPublishedMessageId": "xxxxxxxxxxxxxx",
"inboundMessageId": "xxxxxxxxxxxxxx"
}

This Lambda function extracts the OID (destinationNumber), Customer phone number (originationNumber), and the customer response (messageBody) from the json payload above and adds an entry in the DynamoDB table (SMSOptOut). Once the item is put successfully in DynamoDB table, the function also sends out a confirmation SMS (either Opt-in or Opt-out) to the customer phone number using SendTextMessage.
For example:

• If the customer response value is a valid keyword for Opt-out (Refer section Keywords in scope), the confirmation SMS is ‘YOU HAVE BEEN UNSUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT “JOIN” TO THIS NUMBER TO BE RESUBSCRIBED’.
• If the customer response value is a valid keyword for Opt-in (Refer section Keywords in scope), the confirmation SMS is ‘YOU HAVE BEEN SUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT “STOP” OR “UNSUBSCRIBE” TO THIS NUMBER TO BE UNSUBSCRIBED’.

import json
import boto3
import datetime

dynamodb = boto3.resource('dynamodb')
dynamodb_table = dynamodb.Table('SMSOptOut')
pinpoint = boto3.client('pinpoint-sms-voice-v2')
OptOutKeyword = ['ARRET','CANCEL','END','OPT-OUT','OPTOUT','QUIT','REMOVE','STOP','TD','UNSUBSCRIBE']
OptInKeyword = ['JOIN']

#adds item in the DynamoDB table
def put_item(data,current_timestamp):
    print(dynamodb_table)
    try:
        response = dynamodb_table.put_item(
            Item = {
                'PK': data['originationNumber'],
                'SK': data['destinationNumber']+'#'+current_timestamp+'#'+data['messageBody'], 
                'OID': data['destinationNumber'],
                'Timestamp': current_timestamp,
                'Response': data['messageBody']
            }
        )
    except Exception as e:
        print("Error when writing an item in DynamoDB table: ",e)
        raise e

#send opt-in/opt-out confirmation text using send_text_message.
def send_confirmation_text(data,messageBody,messageType):
    try:
        response = pinpoint.send_text_message(
            DestinationPhoneNumber=data['originationNumber'],
            OriginationIdentity=data['destinationNumber'],
            MessageBody=messageBody,
            MessageType=messageType
            )
    except Exception as e:
        print("Error in sending text message using Pinpoint send_text_message api:", e)
        raise e
        
#gets the message from SNS topic
def lambda_handler(event, context):
    message = event['Records'][0]['Sns']['Message']
    data = json.loads(message)
    current_timestamp = datetime.datetime.now().isoformat()

    if data['messageBody'] in OptOutKeyword:
        put_item(data,current_timestamp)
        send_confirmation_text(data, 'YOU HAVE BEEN UNSUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT "JOIN" TO THIS NUMBER TO BE RESUBSCRIBED', 'TRANSACTIONAL')
    elif data['messageBody'] in OptInKeyword:
        put_item(data,current_timestamp)
        send_confirmation_text(data, 'YOU HAVE BEEN SUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT "STOP" OR "UNSUBSCRIBE" TO THIS NUMBER TO BE UNSUBSCRIBED', 'TRANSACTIONAL')
    else:
        print("The customer response is not one of the allowed keyword")

Clean Up

DynamoDB storage and any Lambda invocation will incur a cost so it is important to delete these resources if you do not plan on using them as shown below.

DynamoDB:

1. 1. On DynamoDB table, select table ‘SMSOptOut’ and click Delete. Confirm the action.

Lambda:

1. On Lambda console, find the 2 functions you created and click Actions → Delete. Confirm the actions.

Amazon Pinpoint

1. After deleting the DynamoDB table and Lambda functions your self-managed Opt-out flow will not work so you will need to disable self-managed opt-outs in Pinpoint for the respective OID as shown below.

Conclusion
In this post, you learned how to implement a self-managed opt-out workflow when using Pinpoint SMS. Keep in mind that when you implement the self-managed Opt-out flow, Pinpoint will not track or maintain any opt-out status for the OID that it was enabled for.

Take the time to plan out your approach, follow the steps outlined in this blog, and take advantage of any resources available to you within your support tier.

Decide what origination IDs you will need here
Review the documentation for the V2 SMS and Voice API here
Check out the support tiers comparison here

Resources:
https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-sms-by-country.html
https://aws.amazon.com/blogs/messaging-and-targeting/how-to-utilise-amazon-pinpoint-to-retry-unsuccessful-sms-delivery/
https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-limitations-opt-out.html
https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-simulator.html
https://docs.aws.amazon.com/dynamodb/
https://docs.aws.amazon.com/sns/
https://docs.aws.amazon.com/lambda/

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-send-sms-using-a-sender-id-with-amazon-pinpoint/

Amazon Pinpoint enables you to send text messages (SMS) to recipients in over 240 regions and countries around the world. Pinpoint supports all types of origination identities including Long Codes, 10DLC (US only), Toll-Free (US only), Short Codes, and Sender IDs.
NOTE: Certain subtypes of Origination Identities (OIDs), such as Free to End User (FTEU) Short Codes might not be supported

Unlike other origination identities, a Sender ID can include letters, enabling your recipients to receive SMS from “EXAMPLECO” rather than a random string of numbers or phone number. A Sender ID can help to create trust and brand awareness with your recipients which can increase your deliverability and conversion rates by improving customer interaction with your messages. In this blog we will discuss countries that allow the use of Sender IDs, the types of Sender IDs that Pinpoint supports, how to configure Pinpoint to use a Sender ID, and best practices for sending SMS with a Sender ID. Refer to this blog post for guidance planning a multi-country rollout of SMS.

What is a Sender ID?

A sender ID is an alphanumeric name that identifies the sender of an SMS message. When you send an SMS message using a sender ID, and the recipient is in an area where sender ID is supported, your sender ID appears on the recipient’s device instead of a phone number, for example, they will see AMAZON instead of a phone number such as “1-206-555-1234”. Sender IDs support a default throughput of 10 messages per second (MPS), which can be raised in certain situations. This MPS is calculated at the country level. As an example, a customer can send 10 MPS with “SENDERX” to Australia (AU) and 10 MPS with “SENDERX” to Germany (DE).

The first step in deciding whether to use a Sender ID is finding out whether the use of a Sender ID is supported by the country(ies) you want to send to. This table lists all of the destinations that Pinpoint can send SMS to and the Origination Identities that they support. Many countries support multiple origination identities so it’s important to know the differences between them. The two main considerations when deciding what originator to use is throughput and whether it can support a two-way use case.

Amazon Pinpoint supports three types of Sender IDs detailed below. Your selection is dependent on the destination country for your messages, consult this table that lists all of the destinations that Pinpoint can send SMS to.

Dynamic Sender ID – A dynamic sender ID allows you to select a 3-11 character alphanumeric string to use as your originator when sending SMS. We suggest using something short that outlines your brand and use case like “[Company]OTP.” Dynamic sender IDs vary slightly by country and we recommended senders review the specific requirements for the countries they plan to send to. Pay special attention to any notes in the registration section. If the country(ies) you want to send to require registration, read on to the next type of Sender ID.

Registered Sender ID – A registered SenderID generally follows the same formatting requirements as a Dynamic Sender ID, alowing you to select a 3-11 character alphanumeric string to use, but has the added step of completing a registration specific to the country you want to use a Sender ID for. Each country will require slightly different information to register, may require specific forms, as well as a potential registration fee. Use this list of supported countries to see what countries support Sender ID as well as which ones require registration.

Generic, or “Shared” Sender ID – In countries where it is supported, when you do not specify a dynamic Sender ID, or you have not set a Default Sender ID in Pinpoint, the service may allow traffic over a Generic or Shared SenderID like NOTICE. Depending on the country, traffic could also be delivered using a service or carrier specific long or short code. When using the shared route your messages will be delivered alongside others also sending in this manner.

As mentioned, Sender IDs support 10 MPS, so if you do not need higher throughput than this may be a good option. However, one of the key differences of using a Sender ID to send SMS is that they do not support two-way use cases, meaning they cannot receive SMS back from your recipients.

IMPORTANT: If you use a sender ID you must provide your recipients with alternative ways to opt-out of your communications as they cannot text back any of the standard opt-out keywords or any custom opt-in keywords you may have configured. Common ways to offer your recipients an alternative way of opting out or changing their communication preferences include web forms or an app preference center.

How to Configure a Sender ID

The country(ies) you plan on sending to using a Sender ID will determine the configuration you will need to complete to be able to use them. We will walk through the configuration of each of the three types of Sender IDs below.

Step 1 – Request a Sender ID(Dependent on Country, Consult this List)

Some countries require a registration process. Each process, dependent on the country can be unique so it is required that a case be opened to complete this process. The countries requiring Sender ID registration are noted in the following list.
When you request a Sender ID, we provide you with an estimate of how long the request will take to complete. This estimate is based on the completion times that we’ve seen from other customers.

NOTE: This time is not an SLA. It is recommended that you check the case regularly and make sure that nothing else is required to complete your registration. If your registration requires edits it will extend this process each time it requires edits. If your registration passes over the estimated time it is recommended that you reply to the case.

Because each country has its own process, completion times for registration vary by destination country. For example, Sender ID registration in India can be completed in one week or less, whereas it can take six weeks or more in Vietnam. These requests can’t be expedited, because they involve the carriers themselves making changes to the ways that their networks are configured and certify the use case onto their network. We suggest that you start your registration process early so that you can start sending messages as soon as you launch your product or service.

IMPORTANT: Make sure that you are checking on your case often as support may need more details to complete your registration and any delay extends the expected timeline for procuring your Sender ID

Generic Sender ID – In countries that support a Generic or Shared ID like NOTICE there is no requirement to register or configure prior to sending we will review how to send with this type of Sender ID in Step 2.

Dynamic Sender ID – A Dynamic Sender ID can be requested via the API or in the console, complete the following steps to configure these Sender IDs in the console.
NOTE: If you are using the API to send it is not required that you request a Sender ID for every country that you intend on sending to. However, it is recommended, because the request process will alert you to any Sender IDs that require registration so you do not attempt to send to countries that you cannot deliver successfully to. All countries requiring registration for Sender IDs can be found here.

1. Navigate to the SMS Console
   1. Make sure you are in the region you plan on using to send SMS out of as each region needs to be configured independently and any registrations also need to be made in the account and region in which you will be sending from
2. Select “Sender IDs” from the left rail
   1. Click on “Request Originator”
      
   2. Choose a country from the drop down that supports Sender ID
   3. Choose “SMS”
      1. Leave “Voice” unchecked if it is an option.
         NOTE: If you choose Voice than you will not be able to select a Sender ID in the next step
      2. Select your estimated SMS volume
      3. Choose whether your company is local or international in relation to the country you are wanting to configure. Some countries, like India, require proof of residency to access local pricing so select accordingly.
      4. Select “No” for two-way messaging or you will not be able to select a Sender ID in the next step
   4. Click next and choose “Sender ID” and provide your preferred Sender ID.
      NOTE: Refer to the following criteria when selecting your Sender ID for configuration (some countries may override these)
      1. Numeric-only Sender IDs are not supported
      2. No special characters except for dashes ( – )
      3. No spaces
      4. Valid characters: a-z, A-Z, 0-9
      5. Minimum of 3 characters
      6. Maximum of 11 characters. NOTE: India is exactly 6 Characters
      7. Must match your company branding and SMS service or use case.
         1. For example, you wouldn’t be able to choose “OTP” or “2FA” even though you might be using SMS for that type of a use case. You could however use “ANYCO-OTP” if your company name was “Any Co.” since it complies with all above criteria.

NOTE: If the console instructs you to open a case as seen below than your Sender ID likely requires some form of registration. Read on to configure a Registered Sender ID.

Registered Sender ID – A registered sender ID follows the same criteria above for a Dynamic Sender ID, although some countries may have minor criteria changes or formatting restrictions. Follow the directions here to complete this process, AWS support will provide the correct forms needed for the country that you are registering. Each Registered Sender ID will need a separate case per country. Follow the link to the “AWS Support Center” and follow these instructions when creating your case

Step 2 – How to Send SMS with a Sender ID

Sender IDs can be used via three different mechanisms

Option 1 – Using the V2 SMS and Voice API and “SendTextMessage“
This is the preferred method of sending and this set of APIs is where all new functionality will be built on.

1. SendTextMessage has many options for configurability but the only required parameters are the following:
   1. DestinationPhoneNumber
   2. MessageBody
      
2. “OriginationIdentity” is optional, but it’s important to know what the outcome is dependent on how you use this parameter:
   1. Explicitly stating your SenderId
      1. Use this option if you want to ONLY send with a Sender ID. Setting this has the effect of only sending to recipients in countries that accept SenderIDs and rejecting any recipients whose country does not support Sender IDs. The US for example cannot be sent to with a Sender ID
   2. Explicitly stating your SenderIdArn
      1. Same effect as “SenderID” above
   3. Leaving OriginationIdentity Blank
      1. If left blank Pinpoint will select the right originator based on what you have available in your account in order of decreasing throughput, from a Short Code, 10DLC (US Only), Long Code, Sender ID, or Toll-Free (US Only), depending on what you have available.
         1. Keep in mind that sending this way opens you up to sending to countries you may not have originators for. If you would like to make sure that you are only sending to countries that you have originators for then you need to use Pools.
   4. Explicitly stating a PoolId
      1. A pool is a collection of Origination Identities that can include both phone numbers and Sender IDs. Use this option if you are sending to multiple country codes and want to make sure that you send to them with the originator that their respective country supports.
         1. NOTE: There are various configurations that can be set on a pool. Refer to the documentation here
            1. Make sure to pay particular attention to “Shared Routes” because in some countries, Amazon Pinpoint SMS maintains a pool of shared origination identities. When you activate shared routes, Amazon Pinpoint SMS makes an effort to deliver your message using one of the shared identities. The origination identity could be a sender ID, long code, or short code and could vary within each country. Turn this feature off if you ONLY want to send to countries for which you have an originator.
            2. Make sure to read this blogpost on Pools and Opt – Outs here
   5. Explicitly stating a PoolArn
      1. Same effect as “PoolId” above

Option 2 – Using a journey or a Campaign

1. If you do not select an “Origination Phone Number” or a Sender ID Pinpoint will select the correct originator based on the country code being attempted to send to and the originators available in your account.
   1. Pinpoint will attempt to send, in order of decreasing throughput, from a Short Code, 10DLC (US Only), Long Code, Sender ID, or Toll-Free (US Only), depending on what you have available. For example, if you want to send from a Sender ID to Germany (DE), but you have a Short Code configured for Germany (DE) as well, the default function is for Pinpoint to send from that Short Code. If you want to override this functionality you must specify a Sender ID to send from.
      1. NOTE: If you are sending to India on local routes you must fill out the “Entity ID and Template ID that you received when you registered your template with the Telecom Regulatory Authority of India (TRAI)
   2. You can set a default Sender ID for your Project in the SMS settings as seen below.
      NOTE: Anything you configure at the Campaign or Journey level overrides this project level setting
      

Option 3 – Using Messages in the Pinpoint API

1. Using “Messages“ is the second option for sending via the API. This action allows for multi-channel(SMS, email, push, etc) bulkified sending but is not recommended to standardize on for SMS sending.
   1. NOTE: Using the V2 SMS and Voice API and “SendTextMessage” detailed in Option 1 above is the preferred method of sending SMS via the API and is where new features and functionality will be released. It is recommended that you migrate SMS sending to this set of APIs.

Conclusion:
In this post you learned about Sender IDs and how they can be used in your SMS program. A Sender ID can be a great option for getting your SMS program up and running quickly since they can be free, many countries do not require registration, and you can use the same Sender ID for lots of different countries, which can improve your branding and engagement. Keep in mind that one of the big differences in using a Sender ID vs. a short code or long code is that they don’t support 2-way communication. Common ways to offer your recipients an alternative way of opting out or changing their communication preferences include web forms or an app preference center.

A few resources to help you plan for your SMS program:
Use this spreadsheet to plan for the countries you need to send to Global SMS Planning Sheet
The V2 API for SMS and Voice has many more useful actions not possible with the V1 API so we encourage you to explore how it can further help you simplify and automate your applications.
If you are needing to use pools to access the “shared pools” setting read this blog to review how to configure them
Confirm the origination IDs you will need here
Check out the support tiers comparison here

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-build-a-compliant-sms-opt-in-process-with-amazon-pinpoint/

SMS messaging is a great way to stay in touch with your customers and send them timely, relevant messages. However, it’s always required to get their permission before you start sending them texts. This is known as opting in.

There are a few different ways to opt-in users to your SMS program. One common method is to have them sign up on your website or in your app. You can also collect opt-ins at in-person events or via phone call through your customer service team; though it’s not limited to just those options.

No matter which method you choose, it’s important to make sure that your opt-in process is clear, concise, and compliant with all applicable local laws and regulations in the countries that you are sending to. Here are some best practices:

• Get explicit consent. Explicit consent is the intentional action taken by a end-user to request a specific message from your service.
• Provide clear instructions. Tell users how to opt-in, what they are opting into, and how to opt-out of your program. Be sure to include your contact information at the opt-in location in case they have any questions or concerns.
• Give users the option to choose what kind of messages they want to receive. For example, you might allow them to opt-in to OTP/2FA messages, shipping notifications, or both.
• Respect users’ privacy. Never sell or share users’ phone numbers with third parties without their permission. 3rd party data sharing is generally considered a prohibited practice by mobile carriers and violates privacy regulations in many countries.
• Make it easy to opt-out. Users should be able to opt-out of your program at any time by replying with a simple text message, such as “STOP.” See additional relevent documentation related to this: Opting out. Self-managed opt-outs.

The above will help you build a strong audience of engaged subscribers who want to hear from you and improve your chances in successfully registering for a dedicated number. By following these best practices, you can ensure that your SMS opt-in process is compliant and effective.

What carriers require for a compliant opt-in workflow and call-to-action

The primary purpose of the opt-in workflow is to demonstrate that the end-user explicitly consents to receive text messages and understands the nature of the program. Your application is being reviewed by a 3rd party reviewer and sometimes multiple 3rd party reviewers for a single registration, so make sure to provide clear and thorough information about how your end-users opt-in to your SMS service and any associated fees or charges. If the reviewer cannot determine how your opt-in process works or if it is not compliant then your application will be denied and returned. It is important to note that Amazon does not review or approve your use cases and that it’s a telecom industry standard in most countries for 3rd parties to review and approve your use case prior to sending.

Note: If you have a use case that is internal to your business, you are still required to demonstrate explicit opt-in consent from the recipients. There are no exceptions to having an opt-in workflow and explicit consent is always required.

If your opt-in process requires a login, is not yet public, is a verbal opt-in, or if it occurs on printed forms or fliers then make sure to thoroughly document how this process is completed by the end-user receiving messages — remember, these are 3rd party reviewers and if they’re unable to access where your end-users opt-in, they will require thorough information via other means like text or screenshots. Provide a screenshot of the Call to Action (CTA) in such cases. If the consent is being asked for and supplied verbally, as in a contact center situation, make sure to provide the verbal scripts to ensure the entire CTA is shown. Host any screenshots on a publicly accessible website (like S3, OneDrive, or Google Drive) and provide the URL when you submit (NOTE: toll-free number registration process supports attachments and do not require a public URL to be included). Regardless of the medium used to collect end-user information (e.g., webform, point of sale, fliers, or verbal opt-ins), the requirements are the same. In the case of online and printed materials, they would be shown as text to the end-users. In the case of verbal opt-ins (i.e., on the phone), the information below would be verbally read to the end-user.

Call-to-action/opt-in requirements

The following items are the minimum that must be presented to an end-user at the time of opt-in to ensure your SMS program is compliant:

• Program (brand) name
• Message frequency disclosure. (example: “Message frequency varies” or “One message per login”)
• Customer care contact information (example: “Text HELP or call 1-800-111-2222 for support.”)
• Opt-out information (example: “Text STOP to opt-out of future messages.”)
• Include “Message and data rates may apply” disclosure.
• Link to a publicly accessible Terms & Conditions page
  • Terms & conditions: See section “Publicly accessible Terms & Conditions page” below
• Link to a publicly accessible Privacy Policy page
  • Privacy Policy: See section “Publicly accessible Privacy Policy page” below

**Now lets break the above bullet points down into more detail:

Program, service, brand name

All SMS originator types that require registration must disclose the program name, product description, or both in service messages, on the call-to-action, and in the terms and conditions. The program name is the sponsor of the messaging program, often the brand name or company name associated with the sending use case. The product description describes the product advertised by the program.

Publicly accessible terms & conditions page

The terms should be live and publicly accessible. For verbal scripts, a URL must be read off to the end-user enrolling in the SMS program, or the comprehensive terms must be directly included in the script. You should provide a compliant screenshot, link, or mockup of the SMS Terms of Service in the registration submission.

Below is a copy of the boilerplate terms of service that cover minimum requirements from the carriers:

1. {Program name}
2. {Insert program description here; this is simply a brief description of the kinds of messages users can expect to receive when they opt-in.}
3. You can cancel the SMS service at any time. Just text “STOP” to the short code. After you send the SMS message “STOP” to us, we will send you an SMS message to confirm that you have been unsubscribed. After this, you will no longer receive SMS messages from us. If you want to join again, just sign up as you did the first time and we will start sending SMS messages to you again.
4. If you are experiencing issues with the messaging program you can reply with the keyword HELP for more assistance, or you can get help directly at {support email address or toll-free number}.
5. Carriers are not liable for delayed or undelivered messages
6. As always, message and data rates may apply for any messages sent to you from us and to us from you. You will receive {message frequency}. If you have any questions about your text plan or data plan, it is best to contact your wireless provider.
7. If you have any questions regarding privacy, please read our privacy policy: {link to privacy policy}

Publicly accessible privacy policy page

Message Senders are responsible for protecting the privacy of Consumers’ information and must comply with applicable privacy law. Message Senders should maintain a privacy policy for all programs and make it accessible from the initial call-to-action. The privacy policy should be labeled clearly and all cases, terms and conditions and privacy policy disclosures must provide up-to-date, accurate information about program details and functionality. For verbal scripts, a URL must be read off to the end-user enrolling in the SMS program, or the comprehensive terms must be directly included in the script.

One of the key items carriers look for in a Privacy Policy is the sharing of end-user information with third-parties. If your privacy policy mentions data sharing or selling to non-affiliated third parties, there is a concern that customer data will be shared with third parties for marketing purposes.

Express consent is required for SMS; therefore, sharing data is prohibited. Privacy policies must specify that this data sharing excludes SMS opt-in data and consent. Privacy policies can be updated (or draft versions provided) where the practice of sharing personal data to third parties is expressly omitted from the number registration.

Example: “The above excludes text messaging originator opt-in data and consent; this information will not be shared with any third parties.”

Message frequency disclosure

The message frequency disclosure provides end-users an indication of how often they’ll receive messages from you. For example, a recurring messaging program might say “one message per week.” A one-time password or multi-factor authentication use case might say “message frequency varies” or “one message per login attempt”.

Customer care contact information

Customer care contact information must be clear and readily available to help Consumers understand program details as well as their status with the program. Customer care information should result in Consumers receiving help.

Numbers should always respond to customer care requests, regardless of whether the requestor is subscribed to the program. At a minimum, Message Senders must respond to messages containing the HELP keyword with the program name and further information about how to contact the Message Sender. SMS programs should promote customer care contact instructions at program opt-in and at regular intervals in content or service messages, at least once per month.

Example: “For more information, text ‘HELP’ or call 1-800-123-1234.”

Opt-Out Information

Opt-out mechanisms facilitate Consumer choice to terminate communications from text messaging programs. Message Senders should acknowledge and respect Consumers’ opt-out requests consistent with the following guidelines:

• Message Senders should ensure that Consumers have the ability to opt-out at any time
• Message Senders should support multiple mechanisms of opt-out, including: phone call, email, or text
• Message Senders should acknowledge and honor all Consumer opt-out requests by sending one final opt-out confirmation message to notify the Consumer that they have opted-out successfully. No further messages should be sent following the confirmation message.

Message Senders should include opt-out information in the call-to-action, terms and conditions, and opt-in confirmation.

If a 2FA/OTP program requires end-users to opt-in and request an OTP from the same CTA, and it is compliant with all applicable regulations, then the sender does not need to explicitly opt-out that number if the user texts “STOP” to the business’s number. However, the sender must still respond with a compliant opt-out response.

See the following Amazon Pinpoint blog post on How to Manage SMS Opt-Outs with Amazon Pinpoint

“Message and data rates may apply” disclosure

All SMS programs must display or must be read out loud (if a verbal opt-in) the disclosure verbatim: “Message and data rates may apply”. By requiring the disclosure, US mobile carriers are helping to ensure that consumers are aware of the potential costs of sending and receiving text messages, and that they have consented to receive those messages before they are sent.

SMS Opt-Ins for Independent Software Vendors (ISVs)

Definitions

In this section, we’ll outline the terms we use, to help better explain each party, and the requirements.

ISV: ISVs are positioned between Amazon Pinpoint and the ISV’s end-business customers. While they may operate differently, and/or offer different services, their requirements for SMS program registrations are largely the same.

End Business: The End Business is how we refer to your ISV customers. This is generally the entity that creates the messaging content, distributes it through your platform, and interacts with their end-users (message recipients).

Note: In some rare cases, an ISV platform can be considered the end business if they control content via templates, and collect and manage opt-in in their entirety — meaning the ISV information directly will be used for the registration and will be branded as such in the text messages. If you are unsure, we recommend including the information for the entity (your customer) that is engaging with the opted-in handset with registration. ISVs who don’t include this information (if it is required) risk their verification request being rejected.

End-User: The message recipient is considered the end-user. The person with the handset where messages terminate. As an independent software vendor (ISV), you need to comply with all applicable laws and regulations when it comes to SMS opt-ins. This means that your end business(es) need to get explicit consent from their end-users before text messages start being sent and give end-users the option to opt-out of their program at any time. You also need to provide them with a registered and approved phone number to send their SMS messages to ensure that they are delivered reliably and not flagged as spam.

When does an ISV have to submit each end business?

SMS program registrations requires end-user business information, not ISV information. This means the ISV needs to provide a mechanism for their end businesses to provide their information to be submitted for registration. For ISVs or aggregators who provide messaging services to businesses, it’s expected that the information provided represents the entity (your customer) that is sending messages to the opted-in handset.

NOTE: Amazon uses this information in accordance with all applicable obligations, and only to verify the end-user is a legitimate business. Amazon will not contact the end-business user with the information provided.

Submissions that are missing information or are populated with ISV/aggregator information may be rejected. Exceptions may apply when the use case clearly showcases that the ISV manages opt-in mechanisms, is the sole message content creator, and the messages clearly come from the ISV, not their end businesses. For example, if the ISV owns a web application that requires their end-customers to enroll into OTP.

If you are unsure, we recommend including the information for the entity (your customer) that is engaging with the opted-in handset with registration. ISVs who don’t include this information (if it is required) risk their verification request being rejected.

In conclusion

Getting user consent through a compliant opt-in process is crucial for any SMS messaging program. Key elements include clearly disclosing the program details, providing easy opt-out methods, having accessible terms of service and privacy policies, and adhering to all applicable regulations. For ISVs enabling businesses to send SMS messages, it’s important they provide a way for each end business to submit their own information for registration and comply with the requirements. By following SMS best practices around opt-ins, businesses can build trust with subscribers and ensure deliverability of their text messaging campaigns.

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-migrate-your-sms-program-to-amazon-pinpoint/

How to Migrate Your SMS Program to Amazon Pinpoint

In the fast-paced realm of communication, where every second counts and attention spans are shorter than ever, the choice of channels that you use to deliver your message to your recipients is critical. While we often find ourselves swept away by the allure of flashy social media platforms and sleek email interfaces, it’s the unassuming text message, or SMS, that continually proves to be one of the most effective options. According to Statista, there over 5 billion mobile internet users globally, amounting to over 60% of the earth’s population of ~8 billion. SMS obviously provides an expansive reach that can help businesses connect with a diverse audience but in order to do that at scale, you need to use a service like Amazon Pinpoint that facilitates the ability to send SMS to over 240 countries and/or regions around the world. If you have a current SMS provider and are considering Pinpoint SMS for its global reach, scalability, cost effective pricing, and demonstrably high deliverability, this guide will walk you through how to migrate from your current provider.

There are several common reasons our customers give us when considering a migration. Don’t worry if your situation doesn’t fit into a neat box, we help customers navigate the dynamic landscape of SMS that is constantly evolving. Let’s dive deep into each of the below to highlight some common things we hear from our customers.

• My current provider doesn’t deliver to countries I want to send to
  • We send to over 240 countries and/or regions so if there is a country you want to send SMS to, it’s very likely we can deliver. Please review this post on global sending for a strategy on how to prepare.
• My current provider is more expensive than Pinpoint pricing
  • Our pricing is available on the public pricing page here. Each country has it’s own cost associated with it so enter in the countries you would like to see pricing for. These prices are per message sent so if you are planning on sending to multiple countries factor in the types of messages that you will want to send as well as the countries. If your use case includes 2 way communication make sure to factor the number of inbound messages you expect into your calculations.
    • NOTE: Depending on the language the available characters per message varies, which can affect your calculations on cost. See here for an explanation
• My current provider doesn’t have features that Pinpoint has
  • Among many other features Pinpoint has the ability to send over multiple channels, including: SMS, Email, Push/In-App, Voice, Over the Top (OTT) services such as WhatsApp, as well as interact with third-party APIs giving you the flexibility to send to many other channels.
• My current provider is not native to AWS
  • Pinpoint, being native to the AWS Cloud, boasts the capability to seamlessly integrate with a wide array of services, including AI/ML offerings such as Amazon Personalize, Amazon Bedrock, and Amazon SageMaker, among others. This means you can leverage various AWS services to create innovative solutions that enhance and optimize the communications sent through Pinpoint.
• My current provider does not have good deliverability
  • Price is not the only factor to consider when looking at SMS providers. If you find another provider with lower pricing make sure to ask about their deliverability to the countries you are wanting to send to. There is a big difference between sending an SMS at a low price, and actually delivering that SMS. We are happy to discuss deliverability with you, just reach out to your Account Manager if you have one or contact us to start a conversation about your migration.
• I’m not happy with the customer support of my current provider
  • The SMS landscape is constantly changing and our SMS experts are here to help guide you through the process. Whether it’s regulatory changes, pricing changes, or creating complex architectures to support your needs. Reach out to your Account Manager if you have one or contact us to start a conversation about your migration and get your questions answered.

Regardless of your reason for considering migrating there are four scenarios that most of our customers find themselves in when beginning to plan for an SMS migration.

I have not sent SMS before but I would like to start sending through Pinpoint
Skip ahead to the section on “Checklist for Planning an SMS Migration” to start planning for sending SMS

I have number(s) (Also known as Originators, Origination Identities (OIDs), Toll-Free, 10DLC, Long Code, Short Code, and/or SenderID) with a different provider and I would like to move those to Pinpoint
The ability to “port” numbers from other providers is dependent on the type of originator, the vendor you procured them from, and the country that they support. You may need to get new originators so factor that into your timeline and reach out to your Account Manager to determine whether your originators are able to be ported over. Once you have done that, pull the reports for how much volume you are sending to each country with your current provider and then skip ahead to the section on “Checklist for Planning an SMS Migration” to start planning for sending SMS

I have a current provider but I would like to procure new numbers from Pinpoint
Pull the reports for how much volume you are sending to each country with your current provider and then skip ahead to the section on “Checklist for Planning an SMS Migration” to start planning for sending SMS

I have a current provider but would like to split traffic between them and Pinpoint
Pull the reports for how much volume you are sending to the countries you plan on migrating to AWS and then skip ahead to the section on “Checklist for Planning an SMS Migration” to start planning for sending SMS. Make sure that you consider how you will be managing opt-outs across two providers. Pinpoint offers centrally managed opt-outs but self-management is also an option. All Delivery Receipts/Reporting (DLRs) and inbound/outbound events can be streamed through Amazon Kinesis, Amazon CloudWatch, and/or Amazon Simple Notification Service (SNS) if you need to send those events to another location inside or outside of the AWS Cloud.

Checklist for Planning an SMS Migration

• Setup a spreadsheet similar to the one outlined in this post
• Identify your use case(s)
  • Note whether your use case is one-way or two-way
    • NOTE: Not all countries support 2-way communications, which is the ability to have the recipient send a message back to the OID.
    • NOTE: Sender ID also does not support 2-way communication so if you are planning on using Sender ID you will need to account for how to opt recipients out of future communications.
• Identify your countries
  • Take note of which countries require registration as this will affect your timeline
    • Supported Countries and Regions
• Identify your volume per country
  • If you are already sending SMS with another provider pull a report over a representative time period.
• Identify your throughput needs (Also referred to as Messages per Second, MPS, Transactions per Second, or TPS) for each country
  • Most origination identities are chosen for their ability to support a certain level of MPS, not volume, so if you have seasonality make sure to account for burst rates. There are quotas for the APIs that govern sending as well as quotas for the different types of originators.
• Identify which origination identities you will need for each country using this guide
  • Make note of any countries/OIDs that require registration
  • Reach out to your Account Manager if you have one or contact us to start a conversation about your migration.
  • If you have OIDs you would like to migrate make sure you determine whether that is possible ASAP since your timelines could be affected by the outcome.

Make sure you give ample time for your migration. There are many entities involved in delivering SMS, from governments, to mobile carriers, to third-party registrars, and more, which means that timelines are not always within your control. Ask questions, take advantage of the expert resources we have at AWS, and the content we have produced around these topics.

Content to read

• Review the countries and regions we support here
• Use the format for aggregating information on your use cases outlined in this post here
• Decide what origination IDs you will need here
• Review the documentation for the V2 SMS and Voice API here
• Review the Pinpoint API and SendMessage here
• Check out the support tiers comparison here