How do I set up logging for Amazon Pinpoint voice messages for Amazon Pinpoint SMS and Voice v2 API?

Last updated: 2022-08-31

I want to monitor the status of the voice messages that I send through Amazon Pinpoint. How do I set that up?

Resolution

To log the status of Amazon Pinpoint voice messages, you must configure a configuration set and event destination. After the event destination is set up, it must be mapped to your configuration set. This allows you to receive the response information about the voice messages that you send through Amazon Pinpoint.

You can configure any of the following AWS resources as Amazon Pinpoint voice event destinations:

To configure an event destination, use either the Amazon Pinpoint SMS and voice messaging v2 APIs or one of the AWS SDKs.

Note: The following resolution applies only to Amazon Pinpoint SMS and Voice v2 API. For Amazon Pinpoint SMS and Voice v1 API, see How do I set up logging for Amazon Pinpoint voice messages for Amazon Pinpoint SMS and Voice v1 API?

Configure an Amazon SNS topic as an Amazon Pinpoint voice event destination

1.    Create a configuration set by running the following create-configuration-set (pinpoint-sms-voice v2) AWS CLI command:

Note: You can replace VoiceSNS with any name for your configuration set.

aws pinpoint-sms-voice-v2 create-configuration-set —configuration-set-name VoiceSNS

2.    Subscribe the endpoint for which you want to receive voice message logs to an Amazon SNS topic. The SNS topic can be either a new or existing topic. For instructions, see To subscribe an endpoint to an Amazon SNS topic.

Note: To create a new Amazon SNS topic using the AWS CLI, run the following create-topic command:

aws sns create-topic --name pinpointsmsvoice

3.    You must have the following permission in your SNS topic access policy. This allows the Amazon Pinpoint SMS voice service to deliver logs:

Important: Replace with your AWS Region. Replace with your AWS account ID. Replace pinpointsmsvoice with the name of your SNS topic.

{
  "Sid": "pinpointsmsvoice",
  "Effect": "Allow",
  "Principal": {
    "Service": "sms-voice.amazonaws.com"
  },
  "Action": "SNS:Publish",
  "Resource": "arn:aws:<region>:<AccountID>:pinpointsmsvoice"
}

4.    In a text editor, create an input request file named matching.json for MatchingEventTypes. Specify the events you want to receive, or specify "ALL" to receive all events as shown below.

[
"ALL"
]

5.    Map the event destination to the configuration-set-name by running the following create-event-destination command:

Important: Replace with your AWS Region. Replace with your AWS account ID. Replace pinpointsmsvoice with the name of your Amazon SNS topic.

aws pinpoint-sms-voice-v2 create-event-destination —configuration-set-name VoiceSNS —event-destination-name VoiceSNS —matching-event-types file://matching.json —sns-destination TopicArn=arn:aws:sns:<region>:<AccountId>:pinpointsmsvoice

6.    Test the setup by sending an Amazon Pinpoint voice message using the SendVoiceMessage v2 API operation. After a few minutes, the event appears in the endpoint that's subscribed to the SNS topic.

Configure CloudWatch Logs as an Amazon Pinpoint voice event destination

1.    Create a configuration set by running the following create-configuration-set (pinpoint-sms-voice v2) AWS CLI command:

Note: You can replace VoiceCW with any name for your configuration set.

aws pinpoint-sms-voice-v2 create-configuration-set —configuration-set-name VoiceCW

2.    Create a new CloudWatch log group to receive voice message logs by running the following create-log-group:

aws logs create-log-group —log-group-name /aws/pinpoint/voice

-or-

Use an existing CloudWatch log group to complete the following steps.

3.    Get your CloudWatch log group's ARN by doing the following:

Open the CloudWatch console.

In the left navigation pane, choose Logs. Then, choose Log groups.

In the Log group column, choose your log group's name.

In the Log group details pane, copy the ARN value. This is your log group's ARN.

4.    Create a new AWS Identity and Access Management (IAM) role for the Amazon Pinpoint service to assume. For instructions, see Creating a role for an AWS service (console) or Creating a role for a service (AWS CLI). When configuring the role, modify the role's trust policy so that it includes the following permissions statement in the policy's principal section:

Note: This permissions statement allows the sms-voice service to assume the IAM role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "sms-voice.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

5.    Modify the IAM role's permissions policy so that it includes the following permissions statement:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogStream",
        "logs:CreateLogGroup",
        "logs:DescribeLogStreams",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:*:*:*"
    }
  ]
}

Note: This permissions statement grants permissions to call specific CloudWatch Logs API operations. For more information, see the CloudWatch Logs permissions reference.

6.    In a text editor, create an input request file named CloudWatchDestination.json. Then, copy and paste the following destination parameters into the file:

Important: Replace with your AWS Region. Replace with your AWS account ID. Replace with the IAM role's name.

{
  "IamRoleArn": "arn:aws:iam::<AccountID>:role/<IAM role name>",
  "LogGroupArn": "arn:aws:logs:<region>:<AccountID>:log-group:pinpointsmsvoice:"
}

7.    In a text editor, create an input request file named matching.json for MatchingEventTypes. Specify the events you want to receive or specify "ALL" to receive all events as shown below.

[
"ALL"
]

Important: Make sure that you replace VoiceCW with your configuration's set's name.

8.    Map the event destination to the configuration-set-name by running the following create-event-destination command:

aws pinpoint-sms-voice-v2 create-event-destination —configuration-set-name VoiceCW —event-destination-name CloudWatch_Destination —matching-event-types file://matching.json --cloud-watch-logs-destination file://CloudWatchDestination.json

9.    Test the setup by sending an Amazon Pinpoint voice message using the SendVoiceMessage v2 API operation. After a few minutes, the event appears in the endpoint that's subscribed to the Amazon SNS topic.

Configure a Kinesis Data Firehose stream as an Amazon Pinpoint voice event destination

1.    Create a configuration set by running the following create-configuration-set (pinpoint-sms-voice v2) AWS CLI command:

Note: You can replace VoiceKinesis with any name for your configuration set.

aws pinpoint-sms-voice-v2 create-configuration-set —configuration-set-name VoiceKinesis

2.    Create a Kinesis Data Firehose delivery stream. For the Destination setting, choose Amazon Simple Storage Service (Amazon S3).

Important: Accept the default IAM service role. Then, copy the name of the IAM service role to your clipboard. You need role name for the following steps.

3.    Modify the IAM role's permissions policy so that it includes the following permissions statement in the policy's principal section:

Note: This permissions statement grants the sms-voice service to assume the IAM role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "firehose.amazonaws.com",
          "sms-voice.amazonaws.com"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Did this article help?


Do you need billing or technical support?