Overview

This article will show you how to use AWS Simple Notification Service (SNS) with Notivize.

In order to track notification deliveries properly there are a few manual steps that you'll need to take, but they are pretty easy and we'll walk through them step by step.

You'll need an IAM user with the correct permissions to get started.

AWS IAM User

In order for us to be able to create the required resources for sending SMS notifications via SNS and tracking delivery metrics, we will need an AWS access key id and secret key with the following permissions:

1. AmazonSNSFullAccess

SNS delivery metrics tracking

Setup SNS delivery status logs

1. Login into your AWS account
2. Go to the SNS console: https://console.aws.amazon.com/sns/v3/home#/dashboard
3. Click on "Text Messaging (SMS)"

4. Scroll down and click on "Edit Preferences"

5. Expand the "Delivery Status logging" panel, select "Create new service role", and then click on "Create new roles"

6. In the new tab, keep the default values and click on "Allow"

7. Close the tab
8. The new role ARN will be populated and you can click on "Save changes"

Create Cloudwatch Log Group

📘 Pre-requesite

You must have purchased an origination number that has SMS capabilities.

See details at https://docs.aws.amazon.com/sns/latest/dg/channels-sms-originating-identities-origination-numbers.html

1. Go to the SNS console
2. Click on "Origination numbers" and copy the number you will be using to send a test text message

3. Click on "Text messaging (SMS)" in the sidebar and click "Publish new message"

4. Fill in the required fields and click "Publish message"

5. Go to the Cloudwatch console and click on "Log groups" in the side nav to check that the log group has been created (the name should be similar to the one in the screenshot)

Integrate with Notivize

1. Go to https://home.notivize.com
2. Sign in into your account
3. Go to "Settings"
4. Click on "Link Account" from the SNS card

5. Give the service a name you can remember easily. Use the IAM user credentials to fill in AWS ACCESS KEY ID and AWS SECRET ACCESS KEY, and set Region Name to the region you want to publish SMSes from.
6. Click Link SNS Account

You have now successfully linked your SNS account with Notivize! 🎉 You are good to go and now you can select it as a service when creating/editing notifications. ✨
Don't stop here though, make sure you go through the next section (it's short, we promise!) to be able to track your delivery metrics in Notivize.

❗️ Integration Failure

If you get an error or the status of your integration shows "Inactive", make sure you have given your IAM user the correct permissions and try again.
You can also contact us at help@notivize.com, we'd be happy to help!

Forward delivery metrics to Notivize

Create a Lambda function

In order for Notivize to be able to track your delivery metrics properly, you will need to create a lambda function that parses the SNS cloudwatch logs and forwards the interesting parts.

1. Log in into your AWS account
2. Go to the Lambda console: https://console.aws.amazon.com/lambda/home#/functions
3. Click "Create function"

4. Select "Author from scratch", give it a useful name (e.g. forward-sns-metrics-to-notivize)
5. Choose "Python 3.8" as Runtime
6. Click "Create Function"

7. In the file lambda_function.py, copy/paste the following code:

import base64
import gzip
import json
import logging

import urllib3


NOTIVIZE_URL = "https://messaging-api.notivize.com/aws/sns/outcomes"


def lambda_handler(event, context):
    results = []

    # Extracting data from logs
    log_data = base64.b64decode(event["awslogs"]["data"])
    log_data = gzip.decompress(log_data)
    log_data = json.loads(log_data)

    http = urllib3.PoolManager()

    for record in log_data["logEvents"]:
        message = json.loads(record["message"])
        logging.debug(message)
        body = json.dumps({
          "eventType": "ExternalSMSSNS",
          "messageId": message["notification"]["messageId"],
          "status": line["status"],
        })
        response = http.request("POST", NOTIVIZE_URL, body=body)
        logging.debug(f"{response.status} {response.data}")

8. Save the file and click "Deploy"

Connect the Cloudwatch logs to the Lambda function

1. Go to the Cloudwatch console and click on "Log groups"
2. Search for the log group ending with "DirectPublishToPhoneNumber" and click on it
3. Click on the "Subscription Filters" tab
4. Click on Create and select "Create Lambda Subscription filter"

5. Select the lambda function we previously created as the destination
6. Give a name to your subscription (e.g. forward-logs-to-notivize)
7. Click on "Start Streaming"

❗️ Additional Costs

Note: you'll be charged for the lambda usage. Unfortunately, this is the only way currently to be able to forward delivery information from SNS.