Two-way SMS messaging
AWS End User Messaging 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 for processing.
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.
Sender IDs do not support two-way SMS messaging.
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.
Two-way MMS is not available.
Amazon Connect for two-way SMS is available in the AWS Regions listed in Chat messaging: SMS subtype in the Amazon Connect administrator guide.
IAM policies for Amazon SNS topics
If you want AWS End User Messaging SMS to use an existing IAM role or if you create a new role, attach the following policies to that role so that AWS End User Messaging 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, 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 AWS End User Messaging SMS in. -
Replace
region
with the AWS Region that you use AWS End User Messaging 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 AWS End User Messaging 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 AWS End User Messaging 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 AWS End User Messaging 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 AWS End User Messaging 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
When your number receives an SMS message, AWS End User Messaging 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 |
---|---|
|
The phone number that sent the incoming message to you (in other words, your customer's phone number). |
|
The phone number that the customer sent the message to (your dedicated phone number). |
|
The registered keyword that's associated with your dedicated phone number. |
|
The message that the customer sent to you. |
|
The unique identifier for the incoming message. |
|
The unique identifier of the message that the customer is responding to. |
IAM policies for Amazon Connect
If you want AWS End User Messaging SMS to use an existing IAM role or if you create a new role, attach the following policies to that role so that AWS End User Messaging SMS can assume it. For information about how to modify an exsiting trust relationship of a role, see Modifying a Role in the IAM user guide.
To create new IAM polices, do the following:
-
Create a new permission policy by following the directions in Creating policies using the JSON editor in the IAM User Guide.
-
In step 4 use the permission policy defined below.
-
-
Create a new trust policy by following the directions in Creating a role using custom trust policies in the IAM User Guide.
-
In step 4 use the trust policy defined below.
-
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
" } } } ] }