AWS Messaging & Targeting Blog

How to Send SMS Using Configuration Sets with Amazon Pinpoint

In a previous blog post we walked through how to manage opt-outs for SMS in Amazon Pinpoint using the V2 SMS and Voice API. The post detailed a scenario where a user needed to manage multiple use-cases such as marketing and One-Time Password (OTP) or Multi-Factor Authentication (MFA). This works great if all of your data can be streamed to a single location, but what if you have multiple business units or you are an Independent Software Vendor (ISV) and need to manage SMS sending for multiple customers? You need a way to not only manage multiple use-cases and opt-out lists, but also sender details and separate event destinations for metrics. Read on to learn how to combine SMS Opt-Out Lists with Configuration Sets to simplify your sending and solve your multi-tenant challenge.

Prerequisites

  • In order to manage Configuration Sets you need to use the V2 API for SMS and voice
  • You must Purchase/Register an Origination Identity (OID) for each use-case in each country you plan to support.
    • Example: If you are sending marketing materials and OTP messages in the US and are using a short code then you will need to purchase at least two short codes (one for each use-case) and register each use-case.
    • If you need help determining what OID you need use this guide.

The Scenario:
For the sake of simplicity our scenario will use two different senders that need to manage two distinct use-cases but these steps can scale as you need.

SMS Sender 1 Details:

  • Sending only in the US
  • Sending OTP via a US Short Code
  • Sending Marketing messages via a 10DLC
    • Send text events to an Amazon Kinesis Data Firehose destination
    • Send text events to an Amazon CloudWatch destination

SMS Sender 2 Details:

  • Sending SMS Globally
  • Sending OTP via multiple country specific originators
    • Send events to an Amazon Kinesis Data Firehose destination
    • Send all events to an Amazon CloudWatch destination

The V2 SMS and Voice API has several helpful actions to configure this scenario above, some of which will expand upon our previous blog post that covered managing SMS opt-outs so make sure to read that one first and have it handy as you review.

What is a Configuration Set for SMS?

A Configuration Set is a container that is used to hold information about Event Destinations as well as rules that you apply to the SMS messages that you send. Configuration Sets are used when sending messages with the SendTextMessage Action in the V2 API for SMS and voice. When you use SendTextMessage you can specify a Configuration Set that determines how the messages are treated and where the events from that particular send are streamed. The image below explains the concepts we will walk through in this post.


How to Create Configuration Sets and Send SMS
Below we will walk through the steps needed to configure each of the above scenarios. Note that the default quota for Configuration Sets is 25 per account but this can be increased if needed

  • Scenario 1 –
    • Short Code Configuration
      • Create a Pool for the US Short Code delivering OTP messages
        • Associate the short code to that Pool by setting “OriginationIdentity” using the PhoneNumberArn of your US Short Code
          • You can use DescribePhoneNumbers to find the values for PhoneNumberArn
          • Note: You can have multiple OIDs per Pool if necessary
          • Note: Opt-Out Lists of OIDs and Pools must match. If you previously associated an Opt-Out List to any OIDs you may need to update those OIDs to match that of the Pool prior to associating it with the Pool
        • Set the IsoCountryCode to “US”
      • Use the “UpdatePool” action to ensure we only send to US phone numbers as well as to create an Opt-Out List specifically for the OTP use-case
        • Set “SharedRoutesEnabled” to False. This will ensure that only the OIDs in this pool will be used to send messages.
          • Since we will only have a US Shortcode in this pool then only US based phone numbers will be sent messages, other destination phone numbers will generate a ConflictException error
            • An error occurred (ConflictException) when calling the SendTextMessage operation: Conflict Occurred – Reason=”NO_ORIGINATION_IDENTITIES_FOUND”
        • Set an Opt-Out List for the Pool by specifying the “OptOutListName”
      • Use the “PutKeyword” action to create at least one Opt-In Keyword
        • This will allow destination numbers to opt back into your use-case
      • Create a Configuration Set
        • This is a container for your Event Destinations which you will set up next. Each configuration set can contain between 0 and 5 event destinations. Each event destination can contain a reference to a single destination, such as a CloudWatch or Kinesis Data Firehose destination
        • Give your Configuration a descriptive name by setting “ConfigurationSetName”
      • Create an SNS Topic that will receive all of the events. Dependent on your needs you can decide where you want to publish these events. Your options are:
      • Create a CloudWatch Log Group that will receive all of the events you would like to log
      • Create Event Destinations – Each event destination can contain a reference to a single destination, since we are adding two destinations (SNS and CloudWatch) we will need to make this call twice, once for each destination
        • Create the SNS destination.
          • Set the “ConfigurationSetName” to the Configuration Set you just created
          • Set “MatchingEventTypes” to the event types you are wanting to log
          • Set the SNS Event Destination
            • Set the “TopicArn”
        • Create the CloudWatch Destination
          • Set the “ConfigurationSetName” to the Configuration Set you just created
          • Set “MatchingEventTypes” to the event types you are wanting to log
          • Set “IamRoleArn” to the ARN of an Amazon Identity and Access Management (IAM) role that is able to write event data to an Amazon CloudWatch destination
          • Set the “LogGroupArn” to the Log Group in CloudWatch you want the events to stream to
    • 10DLC Configuration
        • Create a Pool for the 10DLC delivering Marketing messages
          • Associate the 10DLC to that Pool by setting “OriginationIdentity” using the PhoneNumberArn of your 10DLC
            • You can use DescribePhoneNumbers to find the values for PhoneNumberArn
            • Note: You can have multiple OIDs per Pool if necessary
            • Note: Opt-Out Lists of OIDs and Pools must match, so if you previously associated an Opt-Out List to any OIDs you may need to update those OIDs to match that of the Pool prior to associating it with the Pool
          • Set the IsoCountryCode to “US”
        • Use the “UpdatePool” action to ensure we only send to US phone numbers as well as to create an Opt-Out List specifically for the Marketing use-case
          • Set “SharedRoutesEnabled” to False. This will ensure that only the OIDs in this pool will be used to send messages.
            • Since we will only have a 10DLC in this pool then only US based phone numbers will be sent messages, other destination phone numbers will generate an error
          • Set an Opt-Out List for the Pool by specifying the “OptOutListName”
        • Use the “PutKeyword” action to create at least one Opt-In Keyword
        • Create a Configuration Set
          • Give your Configuration a descriptive name by setting “ConfigurationSetName”
        • Create a Kinesis Data Firehose Delivery Stream that will receive all of the events.
        • Create a CloudWatch Log Group that will receive all of the events you would like to log
        • Create Event Destinations – Each event destination can contain a reference to a single destination. We are adding two destinations (SNS and CloudWatch) so we need to make this call twice, once for each destination
          • Create the Kinesis destination.
            • Set the “ConfigurationSetName” to the Configuration Set you just created
            • Set “MatchingEventTypes” to the event types you are wanting to log
            • Set the Kinesis Event Destination
              • Set the “DeliveryStreamArn” to the Stream you created earlier
              • Set the “IamRoleArn” to the ARN of an IAM role that is able to write event data to an Amazon Firehose destination
          • Create the CloudWatch Destination
            • Set the “ConfigurationSetName” to the Configuration Set you just created
            • Set “MatchingEventTypes” to the event types you are wanting to log
            • Set “IamRoleArn” to an IAM role that is able to write event data to an Amazon CloudWatch destination
            • Set the “LogGroupArn” to the Log Group in CloudWatch you want the events to stream to
  • Scenario 2
    • Global OTP Configuration
      • Create a Pool for delivering the OTP messages
        • Associate all of your OIDs being used to that Pool
          • You can use DescribePhoneNumbers to find the values for PhoneNumberArn
          • Note: Opt-Out Lists of OIDs and Pools must match, so if you previously associated an Opt-Out List to any OIDs you may need to update those OIDs to match that of the Pool prior to associating it with the Pool
      • Use the “UpdatePool” action to create an Opt-Out List specifically for the OTP use-case.
        • Set an Opt-Out List for the Pool by specifying the “OptOutListName”
      • Use the “PutKeyword” action to create at least one Opt-In Keyword
        • This will allow destination numbers to opt back into your use-case, in this case OTP
      • Create a Configuration Set
        • Give your Configuration a descriptive name by setting “ConfigurationSetName”
      • Create a Kinesis Data Firehose Delivery Stream that will receive all of the events
      • Create a CloudWatch Log Group that will receive all of the events you would like to log
      • Create Event Destinations – Each event destination can contain a reference to a single destination, since we are adding two destinations (SNS and CloudWatch) we will need to make this call twice, once for each destination
        • Create the Kinesis destination.
          • Set the “ConfigurationSetName” to the Configuration Set you just created
          • Set “MatchingEventTypes” to the event types you are wanting to log
          • Set the Kinesis Event Destination
            • Set the “DeliveryStreamArn” to the Stream you created earlier
            • Set the “IamRoleArn” to the ARN of an IAM role that is able to write event data to an Amazon Firehose destination
        • Create the CloudWatch Destination
          • Set the “ConfigurationSetName” to the Configuration Set you just created
          • Set “MatchingEventTypes” to the event types you are wanting to log
          • Set “IamRoleArn” to an IAM role that is able to write event data to an Amazon CloudWatch destination
          • Set the “LogGroupArn” to the Log Group in CloudWatch you want the events to stream to

Your configuration should look like this once you have completed the above steps

How to Send Your Messages

  • Send your SMS with the “SendTextMessage” action
    • Set the “ConfigurationSetName” using either the ConfigurationSetName or ConfigurationSetArn
      • You can find these using the “DescribeConfigurationSets” action
      • This field is used for any country-specific registration requirements. Currently, this setting is only used when you send messages to recipients in India using a sender ID.
    • Use either PoolId, or PoolArn for “OriginationIdentity”

Conclusion

In this post you have learned how to create Configuration Sets that give you more control over how you send SMS. Using Configuration Sets allows you to simplify your sending while maintaining multiple sending configurations and event destinations . 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.

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

Resources
https://docs.aws.amazon.com/pinpoint/latest/apireference_smsvoicev2/Welcome.html
https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-originating-identities-choosing.html
https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-limitations-opt-out.html
https://docs.aws.amazon.com/pinpoint/latest/developerguide/sms-voice-v2-pools.html
https://docs.aws.amazon.com/pinpoint/latest/developerguide/sms-voice-v2-configuration-sets.html
https://docs.aws.amazon.com/pinpoint/latest/developerguide/sms-voice-v2-keywords.html

TAGS:
Tyler Holmes

Tyler Holmes