SMS
AWS SNS

How to send SMS messages with AWS SNS

Setup guide for SMS notifications with AWS SNS and Knock.

Knock integrates with AWS Simple Notification Service (SNS) to send SMS notifications to your recipients.

Features

  • Knock link tracking
  • Per environment configuration
  • Sandbox mode

Getting started

You can create a new AWS SNS channel in the dashboard under the Integrations > Channels section. From there, you'll need to take some steps in AWS before you can configure your SNS channel within Knock.

1

Choose an AWS Authentication Scheme

Knock supports two authentication schemes with AWS SNS:

To send notifications via AWS SNS using an IAM User, Knock requires the access key ID and a secret access key of an AWS user with SNS send permissions (you can use the sns:AmazonSNSFullAccess permission for this).

If you don't already have a user with send permissions, you can create an IAM user in AWS to use with the Knock API. You can learn more about creating IAM users in AWS here.

Once you've created your new IAM user, you'll need to provision them with the policy below.

Now that you have an AWS user created and provisioned with SNS send access, grab the access key ID and a secret access key of the user—we'll use these later when configuring the SNS channel within Knock.

To send notifications via AWS SNS by delegating an IAM Role in your AWS account to Knock, secured with an External ID:

  1. Create a new AWS Role:

    • For "Trusted Entity Type" choose "AWS Account."
    • Select "Another AWS account" and put "496685847699" in the Account ID.
    • Check "Require external ID" and enter the ID of the SNS channel you created in your Knock dashboard.
How Knock works diagram
  1. Attach the following permission policy to that role.

  2. Use that role's ARN when configuring your AWS SNS channel in Knock.

2

Configuring SNS in Knock

Now that you have either an AWS User's credentials or an AWS IAM Role to delegate to Knock, you're ready to configure your SNS channel in the Knock dashboard under the Integrations > Channels section.

Here are a few other things to keep in mind once you have your SNS channel configured in Knock:

  • SNS sandbox mode. By default, AWS places all new accounts in the SNS sandbox. While your account is in the sandbox, you can only send messages to verified destination phone numbers—keep this in mind if you're testing in development before you've moved your account out of the SNS sandbox. For more information on the SNS sandbox and how to move your account out of it, see the SNS sandbox documentation.
  • Deliverability tracking. We cannot currently track deliverability through SNS channels. This means that all notifications sent through SNS will show up as "Sent" in the Knock messages log, but not "Delivered".

Channel configuration

The following channel settings should be configured per environment. Navigate to Integrations > Channels in your dashboard, select your AWS SNS channel, then click "Manage configuration" under the environment that you'd like to configure.

Fields marked with an * are required.

Knock settings

Sandbox modeboolean
Whether to enable sandbox mode for your AWS SNS channel.
Knock link trackingboolean
Whether to enable Knocklink-click tracking.

Provider settings for AWS SNS

AWS regionenum*
The region your AWS account is in.
Authentication schemeenum*
The authentication scheme (Access Key or External ID) to use for your SNS channel.
Access key IDstring*
The access key ID from your AWS account. Required when using Access Key authentication.
Secret access keystring*
The secret access key from your AWS account. Required when using Access Key authentication.
AWS IAM Role ARN to assumestring*
The ARN of the role in your AWS Account that this channel will use. Required when using External ID authentication.
External IDstring*
The external ID for your AWS IAM Role. Required when using External ID authentication.
Message Typeenum
The message type of your SMS (Promotional or Transactional).
Sender IDstring
The AWS SNS Sender ID to send messages from.
Originator numberenum
The originator number type (Phone number or Short code) to send messages from.
Phone numberstring*
The phone number to send SMS messages from. Required when Originator number is set to Phone number.
Short codestring*
The AWS SNS short code to send SMS messages from. Required when Originator number is set to Short code.

Set optional per-environment conditions for this channel. These conditions are evaluated each time a workflow run encounters a step that uses this channel in the configured environment. If the conditions are not met, the step will be skipped.

Recipient data requirements

In order to send an SMS notification you'll need a valid phone_number property set on your recipient.