How do I set up logging for Amazon Pinpoint voice messages?

Last updated: 2022-04-26

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

Short description

To log the status of Amazon Pinpoint voice messages, you must configure an event destination. After the event destination is set up, it receives 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, you can use either the Amazon Pinpoint SMS and voice messaging APIs or one of the AWS SDKs.

Resolution

The following example procedures show how to use the Amazon Pinpoint SMS and voice messaging APIs to create an event destination. For each example setup to work, you must use the SendVoiceMessage API operation to send voice messages. The API request must also pass your configuration set's name in the ConfigurationSetName parameter. For example code, see Send voice messages in the Amazon Pinpoint Developer Guide.

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you're using the most recent AWS CLI version. If voice logs aren't populating after you complete any of these procedures, then see the following article: Why are my Amazon Pinpoint voice message logs not populating?

To configure an Amazon SNS topic as an Amazon Pinpoint voice event destination

1.    Create a configuration set by running the following create-configuration-set AWS CLI command:

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

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

2.    Subscribe the endpoint that you want to receive voice message logs to either an existing Amazon SNS topic or a new topic. For instructions, see To subscribe an endpoint to an Amazon SNS topic in the Amazon SNS Developer Guide.

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.    In a text editor, create an input request file named SNSDestination.json. Then, copy and paste the following destination parameters into the file:

Important: Replace <region> with your AWS Region. Replace <AccountID> with your AWS account ID. Replace pinpointsmsvoice with the name of your Amazon SNS topic. You can edit the MatchingEventTypes values to include only the event types that you want to log.

{
    "Enabled": true,
    "MatchingEventTypes": ["INITIATED_CALL", "RINGING", "ANSWERED", "COMPLETED_CALL", "BUSY", "FAILED", "NO_ANSWER"],
    "SnsDestination": {
        "TopicArn": "arn:aws:sns:<region>:<AccountID>:pinpointsmsvoice"
    }
}

4.    Map the configuration set to the destination parameters by running the following create-configuration-set-event-destination command:

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

aws pinpoint-sms-voice create-configuration-set-event-destination --configuration-set-name VoiceSNS --event-destination-name SNS_Destination --event-destination file://SNSDestination.json

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

Important: Make sure that the API request's ConfigurationSetName parameter matches your configuration set's name.

To configure CloudWatch Logs as an Amazon Pinpoint voice event destination

1.    Create a configuration set by running the following create-configuration-set AWS CLI command:

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

aws pinpoint-sms-voice 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 command:

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 <region> with your AWS Region. Replace <AccountID> with your AWS account ID. Replace <IAM role name> with the IAM role's name. You can edit the MatchingEventTypes values to include only the event types that you want to log.

{
    "Enabled": true,
    "MatchingEventTypes": ["INITIATED_CALL", "RINGING", "ANSWERED", "COMPLETED_CALL", "BUSY", "FAILED", "NO_ANSWER"],
    "CloudWatchLogsDestination": {
        "LogGroupArn": "arn:aws:logs:<region>:<AccountID>:log-group/aws/pinpoint/voice:*",
        "IamRoleArn": "arn:aws:iam::<AccountID>:role/<IAM role name>"
    }
}

7.    Map the configuration set to the destination parameters by running the following create-configuration-set-event-destination command:

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

aws pinpoint-sms-voice create-configuration-set-event-destination --configuration-set-name VoiceCW --event-destination-name CloudWatch_Destination --event-destination file://CloudWatchDestination.json

8.    Test the setup by sending an Amazon Pinpoint voice message using the SendVoiceMessage API operation. After a few minutes, the event appears in the CloudWatch log group.

To 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 AWS CLI command:

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

aws pinpoint-sms-voice 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 default IAM service role's trust 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"
    }
  ]
}

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:

Important: Replace <region> with your AWS Region. Replace <AccountID> with your AWS account ID. Replace Name_of_Kinesis_Firehose with the name of your Amazon Kinesis Data Firehose stream. Replace <IAM role name> with your IAM role's name. You can edit the MatchingEventTypes values to include only the event types that you want to log.

{
    "Enabled": true,
    "MatchingEventTypes": ["INITIATED_CALL","RINGING","ANSWERED","COMPLETED_CALL","BUSY","FAILED","NO_ANSWER"],
    "KinesisFirehoseDestination": {
        "DeliveryStreamArn": "arn:aws:firehose:<region>:<AccountID>:deliverystream/<Name_of_Kinesis_Firehose>",
        "IamRoleArn": "arn:aws:iam::<AccountID>:role/service-role/<IAM role name>"
    }
}

6.    Map the configuration set to the destination parameters by running the following create-configuration-set-event-destination command:

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

aws pinpoint-sms-voice create-configuration-set-event-destination --configuration-set-name VoiceKinesis --event-destination-name KinesisFirehose_Destination --event-destination file://KinesisFirehoseDestination.json

7.    Test the setup by sending an Amazon Pinpoint voice message using the SendVoiceMessage API operation. After a few minutes, the event appears in the Amazon S3 bucket that you configured when creating the Kinesis Data Firehose stream.


Did this article help?


Do you need billing or technical support?