Send data to Amazon Pinpoint

Amazon Pinpoint is a flexible and scalable communications service for inbound and outbound marketing. Use Amazon Pinpoint to connect with your customers over SMS channels.

This topic describes the steps that are required to send phone numbers and SMS message strings to Amazon Pinpoint from Amperity:

  1. Get details

  2. Configure Amazon Pinpoint

  3. Add webhook destination

  4. Add data template

How this destination works

Use the Amazon Pinpoint destination to send phone numbers and promotional messages from Amperity to a Lambda function that validates each phone number, after which a message is sent to each valid phone number.

Send phone numbers and messages from Amperity to Amazon Pinpoint.

An Amazon Pinpoint destination works like this:

  1. Use a query to return a list of phone numbers, along with associated messages. For example:

    SELECT
  phone AS "phone_number"
  ,CONCAT('Hello ', given_name) AS "message"
FROM Merged_Customers

  2. Configure a webhook destination to send data to a Lambda function that is running in AWS Lambda.

  3. Deploy a Lambda function to AWS Lambda. The Lambda function may be deployed as a serverless application (recommended) or it may be a custom Lambda function that you have built using the open source toolkit provided by Amperity, and then uploaded to AWS Lambda.

  4. Configure the Lambda function to run against the data that is sent from Amperity. The Lambda function will validate each phone number.

  5. The Lambda function sends validated results to Amazon Pinpoint, after which a message is sent to each valid phone number.

Get details

Amazon Pinpoint requires the following configuration details:

Detail one.

Amazon Pinpoint must be enabled in your Amazon AWS account and be configured to send SMS messages to your customers. (SMS messages are configured to be sent using the PROMOTIONAL message type in Amazon Pinpoint.)
Detail one.

A Lambda function must be uploaded to AWS Lambda that is running in your Amazon AWS account, and then configured to be available to Amperity.
Detail one.

A webhook destination that is configured in your Amperity tenant that sends query results to a Lambda function running in AWS Lambda.

Configure Amazon Pinpoint

To configure Amazon Pinpoint, you must complete one of the following series of steps:

  1. Use the pre-built serverless application

  2. Manual configuration

Serverless application

The AWS Serverless Application Repository is a managed repository for pre-built serverless applications. Find an application, configure it, and then deploy it to your Amazon AWS account.

Amperity manages a pre-built serverless application for Amazon Pinpoint. Use this application to send valid phone numbers and messages from Amperity to Amazon Pinpoint.

To deploy a serverless application

  1. Log in to your Amazon AWS account.

  2. Open the AWS Serverless Application Repository.

  3. Search for the amperity-amazon-pinpoint-runner, and then open it. On the “amperity-amazon-pinpoint-runner” page, click Deploy to deploy the application to your Amazon AWS account.

  4. Open the AWS Lambda console, and then open the “amperity-amazon-pinpoint-runner” Lambda function, and then click Configure.

  5. On the Configuration page, click Environment variables, and then click Edit.

  6. Add the following values for each key-pair:

    Key

    Description

    PINPOINT_APP_ID

    The project ID for Amazon Pinpoint. For example: “Ab1CD2eF3hI4JKLmNo5”.

    PINPOINT_ORIGINATION_NUMBER

    The Amazon Pinpoint origination number. For example: “+12137897890”.

    PINPOINT_REGION

    The region in which Amazon Pinpoint is located. For example: “us-east-1”.

  7. Click Save.

Manual configuration

A manual configuration requires more steps than deploying a serverless application, but enables the use of a custom Lambda function and the ability to define inline policies.

To manually configure Amazon Pinpoint, do each of the following steps:

  1. Add basic function to your AWS Lambda console

  2. Get Lambda function template

  3. Upload function to AWS Lambda

  4. Configure function in AWS Lambda

  5. Add the API gateway

  6. Set AWS Lambda environment variables

  7. Define inline policy

Add function to AWS Lambda

Add a basic function to your AWS Lambda console using only the default function without any customization.

To add a function to AWS Lambda

  1. Log in to your Amazon AWS account.

  2. Open the AWS Lambda console, and then click Create function.

  3. Select Author from scratch.

  4. Under Basic information, specify the function name, runtime, and architecture. For example:

    Function name “Amperity function for Amazon Pinpoint”

    Runtime “Python 3.9”

    Architecture “x86_64”

  5. Click Save.

Get Lambda function template

Amperity provides a pre-built collection of Lambda functions that is available from an open-source repository on GitHub.

Note

Lambda functions are built using Python. Amazon AWS provides runtimes for Python that include an SDK, along with credentials from an AWS Identity and Access Management (IAM) role that you manage.

To get the Lambda function template

  1. Clone the open source amperity-lambda-runner repository or download it as a ZIP file.

  2. In the repo, navigate to “/src/lambdas/lambda_handlers/”, and then open “amazon_pinpoint.py”.

  3. You may use this file directly (requiring only configuration updates) or you may customize it to support your desired workflow.

Upload function to AWS Lambda

You must upload the application code (and any dependencies) to AWS Lambda as a ZIP file archive.

To upload a Lambda function to AWS Lambda

  1. Add the application code and dependencies to a ZIP file archive.

    Tip

    To build the ZIP file for Amazon Pinpoint, run the following command from your amperity-lambda-runner directory:

    sh util/lambda-build.sh filename=amazon_pinpoint.py

    This will create a ZIP file that contains the following files: amazon_pinpoint.py, amperity_runner.py, and helpers.py.

  2. Open the AWS Lambda console, and then open the Code tab.

  3. Click Upload from, and then click ZIP file.

  4. Find the ZIP file archive that contains the application code (and any dependencies), and then click Upload.

  5. Click Save.

Configure function in AWS Lambda

AWS Lambda must be updated for the name of the Amazon Pinpoint application and to specify a timeout value.

To configure the Lambda function in AWS Lambda

  1. Open the AWS Lambda console, and then open the Code tab.

  2. Under Runtime settings, select Edit.

  3. Under Handler, add “app.amazon_pinpoint”, and then click Save.

  4. In the AWS Lambda console, open the Configuration tab.

  5. Under General configuration, select Edit.

  6. Set the Timeout value to “15 min 0 sec”, and then click Save.

Add the API gateway

Amazon API Gateway provides tools for creating and documenting web APIs that route HTTP requests to AWS Lambda functions. An API gateway is required to use webhook destinations.

To add an API gateway

  1. Open the AWS Lambda console.

  2. Open the Lambda function for Amazon Pinpoint.

  3. Click Add trigger.

  4. From the drop-down menu, select “API Gateway”, and then select the following:

    Setting

    Value

    Intent

    Create a new API

    API type

    REST API

    Security

    API Key

  5. Click Add.

    You will need these values when configuring the webhook destination in Amperity.

Set AWS Lambda environment variables

Use AWS Lambda environment variables provide to the Lambda function the name of the project, the origination number, and the region.

To set environment variables

  1. Open the AWS Lambda console.

  2. Open the Lambda function for Amazon Pinpoint.

  3. Click Configuration.

  4. On the Configuration page, click Environment variables, and then click Edit.

  5. Click Add environment variable, and then set the following key-value pairs:

    Key

    Description

    PINPOINT_APP_ID

    The project ID for Amazon Pinpoint. For example: “Ab1CD2eF3hI4JKLmNo5”.

    PINPOINT_ORIGINATION_NUMBER

    The Amazon Pinpoint origination number. For example: “+12137897890”.

    PINPOINT_REGION

    The region in which Amazon Pinpoint is located. For example: “us-east-1”.

  6. Click Save.

Define inline policy

You can use inline policies to manage access to the Lambda function in AWS Lambda.

To define an inline policy

  1. Open the AWS Lambda console.

  2. Open the Lambda function for Amazon Pinpoint.

  3. Click Configuration.

  4. On the Configuration page, under Execution role, and then click the name of the role to be used with this Lambda function.

  5. Click Add permissions, and then click Create inline policy.

  6. Select the following values:

    Service

    Amazon Pinpoint

    Actions

    All Pinpoint actions (mobiletargeting:*)

    Resources

    All resources

  7. Click Review policy, add a name for the policy (like “Amperity Amazon Pinpoint”), and then click Create policy.

Add webhook destination

Use a webhook destination to send query results from Amperity to a Lambda function running in AWS Lambda in your instance of Amazon AWS.

To add a destination

  1. From the Destinations tab, click Add Destination. This opens the Add Destination dialog box.

  2. Enter the name of the destination and a description. For example, “Amazon Pinpoint” and “Send phone numbers and SMS message strings in Amazon Pinpoint”.

  3. From the Plugin drop-down, select “Webhook”.

  4. The “webhook” credential type is selected automatically.

  5. From the Credential drop-down, select a credential that has already been configured for this destination or click Create a new credential, which opens the Create New Credential dialog box. For new credentials, enter a name for the credential, the API key, and the webhook URL. (The webhook URL is the endpoint for the API gateway.) Click Save.

    Tip

    The API key and webhook URL settings are available from your AWS Lambda console. Log in to your AWS Lambda console, and then click Configuration. The API key is in the Details section and the webhook URL is in the Triggers section.

    For example:

    API key AB1c2D3eFGH4j5KL6

    Webhook URL https://acme.execute-api.us-east-123.amazonaws.com/Prod/run/

  6. Select Allow business users to use this destination.

    This allows users who have been assigned to the Amp360 User and/or AmpIQ User policies to use this destination with orchestrations and/or campaigns.

  7. Select Allow business users with limited PII access to send data.

    This allows users who have been assigned to the Restrict PII access policy option to use this destination with orchestrations and/or campaigns.

  8. Click Save.

Add data template

A data template defines how columns in Amperity data structures are sent to downstream workflows. A data template is part of the configuration for sending query and segment results from Amperity to an external location.

To add a data template

Step 1.

From the Destinations tab, open the menu for a destination that is configured for Amazon Pinpoint, and then select Add data template.

This opens the Add Data Template dialog box.

Step 1

Enter the name of the data template and a description. For example: “Amazon Pinpoint” and “Send phone numbers and SMS message strings to Amazon Pinpoint.”.
Step 2.

Verify business user access to queries and orchestrations and access to segments and campaigns.

A business user may also have restricted access to PII, which prevents them from viewing and sending customer profile data.

Step 2.

If business user access was not configured as part of the destination, you may configure access from the data template.
Step 3.

Verify all configuration settings.

Important

Under Webhook settings, if Webhook Settings is empty, set it to empty curly braces: {}.

Verify settings for the data template.

Note

When the settings required by Amazon Pinpoint were are not configured as part of the destination, you must configure them as part of the data template before making this destination available to campaigns.
Step 4.

Review all settings, and then click Save.

Save the data template.

After you have saved the data template, and depending on how you configured it, business users can send query results to Amazon Pinpoint.