Two-way SMS messaging - Amazon Pinpoint SMS
IAM policies for Amazon SNS topicsAmazon SNS topic policies for Amazon SNS topicsExample of a two-way SMS message payload for Amazon SNS topicsIAM policies for Amazon Connect

Two-way SMS messaging

Amazon Pinpoint SMS includes support for two-way SMS. When you set up two-way SMS, you can receive incoming messages from your customers. You can also use two-way messaging together with other AWS services, such as Lambda and Amazon Lex, to create interactive text messaging experiences.

When one of your customers sends a message to your phone number, the message body is sent to an Amazon SNS topic or Amazon Connect instance for processing.

Note

  • Two-way SMS is only available in certain countries and regions. For more information about two-way SMS support by country or region, see SMS and MMS country capabilities and limitations.

  • Amazon Connect for two-way SMS is available in the AWS Regions listed in Chat messaging: SMS subtype in the Amazon Connect Administrator Guide.

  • Two-way MMS is not supported but your phone number can still receive incoming SMS messages in response to an outbound MMS message.

Two-way SMS messaging (Console)

To enable two-way SMS using the Amazon Pinpoint SMS console, follow these steps:

Enable two-way SMS

  1. Open the Amazon Pinpoint SMS console at https://console.aws.amazon.com/sms-voice/.

  2. In the navigation pane, under Configurations, choose Phone numbers.

  3. On the Phone numbers page, choose a phone number.

  4. On the Two-way SMS tab, choose the Edit settings button.

  5. On the Edit settings page, choose Enable two-way message.

  6. For Destination type, choose either Amazon SNS or Amazon Connect.

    • For Amazon SNS choose either New Amazon SNS topic or Existing Amazon SNS topic and then for Two-way channel role, choose either Choose existing IAM role or Use Amazon SNS topic policies.

      • New Amazon SNS topic – If you choose this option, Amazon Pinpoint SMS creates a topic in your account. The topic is automatically created with all of the required permissions. For more information on Amazon SNS topics see Configuring Amazon SNS in the Amazon Simple Notification Service Developer Guide.

      • Existing Amazon SNS topic – If you choose this option, you must choose an existing Amazon SNS topic from the Incoming messages destination dropdown.

      • For Two-way channel role, choose either:

    • For Amazon Connect, in Two-way channel role, choose Choose existing IAM roles.

      • In the Existing IAM roles drop down choose an existing IAM role as the message destination. For example IAM policies, see IAM policies for Amazon Connect .

  7. Choose Save changes.

  8. (Optional) If you've chosen Amazon Connect as the Destination type then in the Import Phone Number to Amazon Connect window:

    1. For the Incoming messages destination dropdown choose the Amazon Connect instance that will receive incoming messages.

    2. Choose Import Phone Number.

Two-way SMS messaging (AWS CLI)

You can use the update-phone-number command to enable two-way SMS.

At the command line, enter the following command:

$ aws pinpoint-sms-voice-v2 update-phone-number \
> --phone-number-id PhoneNumber \
> --two-way-enabled True \
> --two-way-channel-arn TwoWayARN \
> --two-way-channel-role TwoChannelWayRole

In the preceding command, make the following changes:

  • Replace PhoneNumber with the PhoneNumberID or Amazon Resource Name (ARN) of the of the phone number.

  • Replace TwoWayARN with the Amazon Resource Name (ARN) to receive the incoming SMS messages. For example Amazon SNS policies, see Amazon SNS topic policies for Amazon SNS topics. To set Amazon Connect as the inbound destination set TwoWayARN to connect.region.amazonaws.com. Replace region with the AWS Region the Amazon Connect instance is hosted in.

  • Replace TwoChannelWayRole with the Amazon Resource Name (ARN) of the IAM role to use. For example SNS permission policies, see IAM policies for Amazon SNS topics and for example Amazon Connect policies, see IAM policies for Amazon Connect. This parameter is only required if you choose to use IAM permission policies.

IAM policies for Amazon SNS topics

If you want Amazon Pinpoint SMS to use an existing IAM role or if you create a new role, attach the following policies to that role so that Amazon Pinpoint SMS can assume it. For information about how to modify the trust relationship of a role, see Modifying a Role in the IAM user guide.

The following is the trust policy for the IAM role. In the following IAM policy, make the following changes:

  • Replace accountId with the unique ID for your AWS account.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SMSVoice",
      "Effect": "Allow",
      "Principal": {
        "Service": "sms-voice.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "accountId"
        }
      }
    }
  ]
}

The following is the permission policy for the IAM role. The SMSVoiceAllowSNSPublish Sid is a permission policy to allow for publishing to Amazon SNS topics and the SMSVoiceAllowEncryptedSNSTopics Sid is an option for encrypted Amazon SNS topics.

In the following IAM permission policy, make the following changes:

  • Replace partition with the AWS partition that you use Amazon Pinpoint SMS in.

  • Replace region with the AWS Region that you use Amazon Pinpoint SMS in.

  • Replace accountId with the unique ID for your AWS account.

  • Replace snsTopicArn with the Amazon SNS topics that will receive messages.

{
    "Version": "2012-10-17",
    "Statement": [        
        {
            "Sid": "SMSVoiceAllowSNSPublish",
            "Effect": "Allow",
            "Action": "sns:Publish",
            "Resource": "arn:partition:sns:region:accountId:snsTopicArn",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "accountId"
                }
            }
        },
        {
            "Sid": "SMSVoiceAllowEncryptedSNSTopics",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:GenerateDataKey*"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "kms:EncryptionContext:aws:sns:topicArn": "arn:partition:sns:region:accountId:snsTopicArn",
                    "aws:CalledViaLast": "sns.amazonaws.com"
                }
            }
        }
    ]
}

Amazon SNS topic policies for Amazon SNS topics

The Amazon SNS topic requires the appropriate topic policy to grant access to Amazon Pinpoint SMS if they are not provided in the TwoChannelWayRole parameter.

{
  "Effect": "Allow",
  "Principal": {
    "Service": "sms-voice.amazonaws.com"
  },
  "Action": "sns:Publish",
  "Resource": "snsTopicArn"  
}

In the preceding example, make the following changes:

  • Replace snsTopicArn with the Amazon SNS topic that will send and receive messages.

Note

Amazon SNS FIFO topics are not supported.

Although Amazon Pinpoint SMS data is encrypted, you can use Amazon SNS topics that are encrypted using AWS KMS keys for an additional level of security. This added security can be helpful if your application handles private or sensitive data.

You need to perform some additional setup steps to use encrypted Amazon SNS topics with two-way messaging.

The following example statement uses the, optional but recommended, SourceAccount and SourceArn conditions to avoid the confused deputy problem and only the Amazon Pinpoint SMS owner account has access. For more information on the confused deputy problem, see The confused deputy problem in the IAM user guide.

First, the key that you use must be symmetric. Encrypted Amazon SNS topics don't support asymmetric AWS KMS keys.

Second, the key policy must be modified to allow Amazon Pinpoint SMS to use the key. Add the following permissions to the existing key policy:

{
    "Effect": "Allow",
    "Principal": {
        "Service": "sms-voice.amazonaws.com"
    },
    "Action": [
        "kms:GenerateDataKey*",
        "kms:Decrypt"
    ],
    "Resource": "*",
    "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "accountId"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:sms-voice:region:accountId:*"
        }
     }
}

For more information about editing key policies, see Changing a key policy in the AWS Key Management Service Developer Guide.

For more information about encrypting Amazon SNS topics using AWS KMS keys, see Enable compatibility between event sources from AWS services and encrypted topics in the Amazon Simple Notification Service Developer Guide.

Example of a two-way SMS message payload for Amazon SNS topics

When your number receives an SMS message, Amazon Pinpoint SMS sends a JSON payload to an Amazon SNS topic that you designate. The JSON payload contains the message and related data, as in the following example:

{
  "originationNumber":"+14255550182",
  "destinationNumber":"+12125550101",
  "messageKeyword":"JOIN",
  "messageBody":"EXAMPLE",
  "inboundMessageId":"cae173d2-66b9-564c-8309-21f858e9fb84",
  "previousPublishedMessageId":"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

The incoming message payload contains the following information:

Property Description

originationNumber

The phone number that sent the incoming message to you (in other words, your customer's phone number).

destinationNumber

The phone number that the customer sent the message to (your dedicated phone number).

messageKeyword

The registered keyword that's associated with your dedicated phone number.

messageBody

The message that the customer sent to you.

inboundMessageId

The unique identifier for the incoming message.

previousPublishedMessageId

The unique identifier of the message that the customer is responding to.

IAM policies for Amazon Connect

If you want Amazon Pinpoint SMS to use an existing IAM role or if you create a new role, attach the following policies to that role so that Amazon Pinpoint SMS can assume it. For information about how to modify an existing trust relationship of a role, see Modifying a Role in the IAM user guide.

To create new IAM polices, do the following:

  1. Create a new permission policy by following the directions in Creating policies using the JSON editor in the IAM User Guide.

    1. In step 4 use the permission policy defined below.

  2. Create a new trust policy by following the directions in Creating a role using custom trust policies in the IAM User Guide.

    1. In step 4 use the trust policy defined below.

    2. In step 11 add the permission policy that you created in the previous step.

The following is the permission policy for the IAM role to allow for publishing to Amazon Connect.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "connect:SendChatIntegrationEvent"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

The following is the trust policy for the IAM role, make the following changes:

  • Replace accountId with the unique ID for your AWS account.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SMSVoice",
      "Effect": "Allow",
      "Principal": {
        "Service": "sms-voice.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "accountId"
        }
      }
    }
  ]
}