Docs

Integrations

Push

Amazon SNS

How to send push notifications to Amazon SNS

How to send push notifications with Amazon SNS and Knock.

This page walks through how to configure an Amazon Simple Notification Service (Amazon SNS) provider in Knock to send mobile push notifications. You'll need an Amazon SNS channel in your Knock dashboard to follow along.

Getting started

You can create a new Amazon SNS channel in the dashboard under the Channels and sources page in your account settings. From there, you'll need to take some steps in AWS before you can configure your SNS channel within Knock.

Choose an AWS Authentication Scheme

Knock supports two authentication schemes with Amazon SNS:

To send notifications via Amazon 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 Amazon SNS by delegating an IAM Role in your AWS account to Knock, secured with an External ID:

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.

Configuring a new AWS role with an external ID

Attach the following permission policy to that role.
Use that role's ARN when configuring your Amazon SNS channel 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 Channels and sources page in your account settings.

Channel configuration

The following channel settings should be configured per environment. Navigate to Channels and sources in your dashboard account settings, select your Amazon 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 Amazon SNS channel.

Knock token deregistrationboolean

Whether to enable Knock token deregistration.

Provider settings for Amazon SNS

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.

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.

In order to use Amazon SNS with Knock, you'll need the ARNs of the platform endpoints you created using your platform applications configured in SNS and the device tokens of your users. See Setting up an Amazon SNS platform endpoint for mobile notifications for more details on creating platform endpoints.

Once you have an endpoint ARN, you can use the Knock SDK to set the channel data for your recipient, passing an array of endpoint ARNs as target_arns.

Managing platform endpoints and device tokens

By default, Knock makes no assumptions about managing your platform endpoints and corresponding device tokens. This means you are responsible for disabling a platform endpoint when a recipient opts out of notifications on a device or when their token expires. We recommend following Amazon's guidance on managing platform endpoints.

However, Knock does provide an opt-in token deregistration feature to make managing endpoint ARNs easier. When this feature is enabled on an Amazon SNS channel and a message bounces due to a platform endpoint being disabled, Knock will automatically remove the ARN of that platform endpoint from the recipient's channel data.

You can configure token deregistration on a per-environment basis in your channel's environment configurations. See our token deregistration documentation for more details on enabling and working with this feature.

Data passed to Amazon SNS

When sending a notification to Amazon SNS, we also pass through the following attributes:

Property	Type	Description
knock_message_id*	string	The message ID of the corresponding Knock message
data *	string	Any key/value data passed through in your trigger call

Silent/background notifications

We support sending Amazon SNS notifications as "silent", data-only notifications within Knock. You can enable this per push notification template by clicking the gear icon (⚙️) at the top of the template editor to open the template settings modal.

When silent push is enabled, we'll no longer pass through the message payload, but all properties in the data payload described above will still be sent with your notification.

Using overrides to customize notifications

We have full support for overriding the payload sent to Amazon SNS for adding things like badge counts, extra data properties, and sound files. To set push overrides, click the gear icon (⚙️) at the top of the template editor to open the template settings modal. Push overrides support Liquid for injecting data properties and referencing attributes on your recipients.

By default, overrides are merged into the notification payload sent to Amazon SNS's Publish API. If you want to fully replace the payload rather than merge additional properties, you'll also need to set a replace __strategy__:

When testing with a sandbox/development APNs environment, you'll need to include both APNS and APNS_SANDBOX keys in your overrides:

If you wish to add custom APNs headers, you can do so by overriding the MessageAttributes property:

See the Amazon SNS docs for a full list of valid message attributes.

Channel data requirements

In order to use a configured Amazon SNS channel, you must store a list of one or more platform endpoint ARNs for the user or the object that you wish to deliver a notification to. See Setting up an Amazon SNS platform endpoint for mobile notifications for more details on creating platform endpoints.

Property	Type	Description
target_arns*	string[]	One or more platform endpoint ARNs associated with a platform application and a device token