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

7 minute read
0

I want to monitor the status of the voice messages that I send through Amazon Pinpoint.

I want to monitor the status of the voice messages that I send through Amazon Pinpoint.

Resolution

To log the status of Amazon Pinpoint voice messages, configure a configuration set and event destination. Then, map the event destination to your configuration set. This configuration allows you to receive the response information for 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 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.

To configure an Amazon SNS topic 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 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. To use the AWS CLI to create a new Amazon SNS topic, run the create-topic command:

    aws sns create-topic --name pinpointsmsvoice
  3. Add the following permission in your SNS topic access policy. This policy allows 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 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. After 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

To 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 any name for your configuration set.

  2. Run the create-log-group command to create a new CloudWatch log group that receives voice message logs:

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

    -or-

    Use an existing CloudWatch log group and get the ARN with the following steps:
    Open the CloudWatch console.
    In the 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.

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

  4. Update the IAM role trust policy with the following permissions statement:

    {
      "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: This policy allows the SMS voice service to assume the IAM role.

  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: This permissions 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 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 named matching.json for MatchingEventTypes. Specify the events that you want to receive, or specify "ALL" to receive all events:

    [
    "ALL"
    ]

    Note: Replace VoiceCW with your configuration's set's name.

  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
  9. To test the setup, use the SendVoiceMessage V2 API operation to send an Amazon Pinpoint voice message. The event appears in the CloudWatch log group after a few minutes.

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

To 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. 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 permissions 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: This 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 AWS Region, ACCOUNT_ID with your account ID, KINESIS_FIREHOSE_NAME with the name of your Firehose delivery stream, and IAM_ROLE with your IAM role name.

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

  8. 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"
    ]
  9. 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

    Note: Replace VoiceKinesis with your configuration sets name.

  10. To test the setup, use the SendVoiceMessage V2 API operation to send an Amazon Pinpoint voice message. The event appears in the Amazon S3 bucket that you configured when you created the Firehose delivery stream after a few minutes.

AWS OFFICIAL
AWS OFFICIALUpdated 2 months ago
2 Comments

Is this response applicable to sms (txt) messages as opposed to voice? If so, what modifications would be required? Is it as simple as utilizing MatchingEventTypes in matching.json for each of the three solutions?

replied a year ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
MODERATOR
replied a year ago