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

Resolution

To log the status of Amazon Pinpoint voice messages, you must configure a configuration set and event destination. After you set up the event destination, map it 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:

• Amazon Simple Notification Service (Amazon SNS) topics
• Amazon CloudWatch Logs
• Amazon Kinesis Data Firehose streams

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.    To create a configuration set, run the following create-configuration-set (pinpoint-sms-voice v2) AWS CLI command:

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

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

2.    Subscribe the endpoint for which you want to log voice messages 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:

`{   "Sid": "pinpointsmsvoice",   "Effect": "Allow",   "Principal": {     "Service": "sms-voice.amazonaws.com"   },   "Action": "SNS:Publish",   "Resource": "arn:aws:sns:us-east-1:ACCOUNT_ID:`pinpointsmsvoice`" }`

Note: Replace us-east-1 with your AWS Region. Replace ACCOUNT_ID with your AWS account ID. Replace pinpointsmsvoice with the name of your SNS topic.

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

[
"ALL"
]

5.    To map the event destination to the configuration-set-name, run the following create-event-destination command:

`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:`us-east-1:ACCOUNT\_ID:pinpointsmsvoice

Note: Replace us-east-1 with your Region. Replace ACCOUNT_ID with your AWS account ID. Replace pinpointsmsvoice with the name of your SNS topic.

6.    To test the setup, use the SendVoiceMessage v2 API operation to send an Amazon Pinpoint voice message. 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.    To create a configuration set, run the following create-configuration-set (pinpoint-sms-voice v2) AWS CLI command:

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

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

2.    Create a new CloudWatch log group that receives voice message logs. Run 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 Amazon Resource Names (ARN): 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 you configure the role, modify the role's trust policy so that it includes the following permissions statement in the policy's principal section:

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

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

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, enter the following destination parameters into the file:

`{   "IamRoleArn": "arn:aws:iam::ACCOUNT_ID:role/IAM_ROLE",   "LogGroupArn": "arn:aws:logs:us-east-1:ACCOUNT_ID:LOG_GROUP:`pinpointsmsvoice`:" }`

Note: Replace the value for IamRoleArn with your IAM role ARN. Replace the value for LogGroupArn with your log group ARN and SNS topic name.

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

[
"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. To do this, run 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.    To create a configuration set, run the following create-configuration-set (pinpoint-sms-voice v2) AWS CLI command:

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

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

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:

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

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

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

Important: Don't remove any of the IAM service role's default permissions statements.

{
     "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": "firehose:*",
      "Resource": "*"
}

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

{

  "IamRoleArn": "arn:aws:iam::191418023309:role/IAM_ROLE",
  "DeliveryStreamArn": "arn:aws:firehose:us-east-1:ACCOUNT_ID:deliverystream/KINESIS_FIREHOSE_NAME"
}

Note: Replace us-east-1 with your Region. Replace ACCOUNT_ID with your AWS account ID. Replace KINESIS_FIREHOSE_NAME with the name of your Kinesis Data Firehose stream. Replace IAM_ROLE with your IAM role's name.

6.    To map the event destination to the configuration-set-name, run the create-event-destination command with an input request file.

In a text editor, create an input request file named matching.json for MatchingEventTypes. Specify the events that you want to receive, or specify ALL to receive all events:

[
"ALL"
]

Then, run the create-event-destination command:

aws pinpoint-sms-voice-v2 create-event-destination --configuration-set-name VoiceKinesis --event-destination-name KinesisFirehose_Destination --matching-event-types file://matching.json --kinesis-firehose-destination file://KinesisFirehoseDestination.json

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

7.    To test the setup, use the SendVoiceMessage v2 API operation to send an Amazon Pinpoint voice message. After a few minutes, the event appears in the Amazon S3 bucket that you configured when you created the Kinesis Data Firehose stream.