How do I set up logging for AWS End User Messaging voice messages with Amazon Pinpoint?

Resolution

To log the status of Amazon Pinpoint voice messages, create a configuration set and event destination. Then, map the event destination to your configuration set. Use the configuration to receive response information for the voice messages that you send through Amazon Pinpoint.

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

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

To configure an event destination, use either the AWS End User Messaging APIs or one of the AWS SDKs.

Note: The following voice messages logging configuration applies only to AWS End User Messaging. For SMS and Voice v1, 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

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Complete the following steps:

1. To create a configuration set, run the create-configuration-set command:

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

   Note: Replace VoiceSNS with the name for your configuration set.

2. Subscribe the endpoint that you want to log voice messages to an Amazon SNS topic. The SNS topic can be either a new or existing topic.

3. Add the following permissions to your SNS topic access policy to allow the AWS End User Messaging voice service to deliver logs:

   {
     "Effect": "Allow",
     "Principal": {
       "Service": "sms-voice.amazonaws.com"
     },
     "Action": "sns:Publish",
     "Resource": "arn:aws:sns:us-east-1:ACCOUNT_ID:pinpointsmsvoice",
     "Condition": {
       "StringEquals": {
         "aws:SourceAccount": "ACCOUNT_ID"
       },
       "ArnLike": {
         "aws:SourceArn": "arn:aws:sms-voice:us-east-1:ACCOUNT_ID:configuration-set/VoiceSNS"
       }
     }
   }

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

4. In a text editor, create an input request file that's 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 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, ACCOUNT_ID with your account ID, and 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. The event appears in the endpoint that's subscribed to the SNS topic after a few minutes.

Configure CloudWatch Logs as an Amazon Pinpoint voice event destination

Complete the following steps:

1. To create a configuration set, run the create-configuration-set command:

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

   Note: Replace VoiceCW with the name of your configuration set.

2. To create a log group, run the create-log-group command: 

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

   Note: Replace log-group-name with the name of your log group. In the command's output, note the log group's Amazon Resource Name (ARN) to use in a later step. If you're using an existing log group, then call the LogGroup API operation to get the ARN.

3. Create a new AWS Identity and Access Management (IAM) role for the Amazon Pinpoint service to assume.

4. Update the IAM role trust policy with the following statement to allow 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",
         "Condition": {
           "StringEquals": {
             "aws:SourceAccount": "ACCOUNT_ID"
           },
           "ArnLike": {
             "aws:SourceArn": "arn:aws:sms-voice:us-east-1:ACCOUNT_ID:configuration-set/VoiceCW"
           }
         }
       }
     ]
   }

   Note: Replace us-east-1 with your Region, ACCOUNT_ID with your account ID, and VoiceCW with your configuration set.

5. Update the IAM role permissions policy with the following statement:

   {    "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "logs:CreateLogStream",
                   "logs:DescribeLogStreams",
                   "logs:PutLogEvents"
               ],
               "Resource": [
                   "arn:aws:logs:us-east-1:ACCOUNT_ID:log-group:/aws/pinpoint/voice:*"
               ]
           }
       ]
   }

   Note: Replace us-east-1 with your Region, ACCOUNT_ID with your account ID. The preceding policy 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 that's 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:/aws/pinpoint/voice" }`

   Note: Replace the value for IamRoleArn with your IAM role ARN. Replace the value for LogGroupArn with the ARN of the CloudWatch log group that you want to send events to.

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

   [
   "ALL"
   ]

8. Run the create-event-destination command to map the event destination to the configuration-set-name:

   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

   Note: Replace VoiceCW with the name for your configuration set.

9. 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 CloudWatch log group.

Configure a Firehose delivery stream as an Amazon Pinpoint voice event destination

Complete the following steps:

1. To create a configuration set, run the create-configuration-set command:

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

   Note: Replace VoiceKinesis with the name of your configuration set.

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

3. Create a new IAM role for the Amazon Pinpoint service to assume.

4. Update the IAM role trust policy with the following statement in the policy's principal section:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Service": "sms-voice.amazonaws.com"
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "aws:SourceAccount": "ACCOUNT_ID"
           },
           "ArnLike": {
             "aws:SourceArn": "arn:aws:sms-voice:us-east-1:ACCOUNT_ID:configuration-set/VoiceKinesis"
           }
         }
       }
     ]
   }

   Note: Replace us-east-1 with your Region, ACCOUNT_ID with your account ID. The preceding policy allows the SMS voice service to assume the IAM role.

5. Update the IAM role permissions policy to include the Firehose delivery stream ARN:

   {    "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "firehose:PutRecord",
               "Resource": "arn:aws:firehose:us-east-1:ACCOUNT_ID:deliverystream/KINESIS_FIREHOSE_NAME"
           }
       ]
   }

   Note: Replace ACCOUNT_ID with your account ID and KINESIS_FIREHOSE_NAME with the name of your Firehose delivery stream ARN.

6. 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::ACCOUNT_ID:role/IAM_ROLE",
       "DeliveryStreamArn": "arn:aws:firehose:us-east-1:ACCOUNT_ID:deliverystream/KINESIS_FIREHOSE_NAME"
   }

   Note: Replace us-east-1 with your Region, ACCOUNT_ID with your account ID, KINESIS_FIREHOSE_NAME with your Firehose delivery stream name, and IAM_ROLE with your IAM role 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"
   ]

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

   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

   Note: Replace VoiceKinesis with your configuration sets name.

9. 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 Firehose delivery stream.