View a markdown version of this page

Monitoring - AWS End User Messaging
Monitoring with CloudWatchSend events to a destination with a configuration setSend events to a destination with Amazon EventBridgeMessage feedbackLogging API calls with CloudTrail

Monitoring

AWS End User Messaging gives you two complementary views of your MMS messaging, plus a record of your API activity and a way to report message outcomes. This topic describes how to set up each one.

Ways to monitor your MMS messaging
What you monitorHow it works

Overall delivery health

Amazon CloudWatch metrics aggregate your sending into near real-time numbers, such as media spend and messages received, that you watch on dashboards and alarm on.

Granular per-message events

Message events report what happened to each individual message as it is sent and delivered. You route them to a destination with a configuration set, or consume them from Amazon EventBridge.

API activity

AWS CloudTrail logs the AWS End User Messaging API calls made in your account.

Outcome feedback

Message feedback lets you report whether each message reached its intended outcome, so you can track conversion and improve the deliverability signals AWS End User Messaging uses.

Monitoring with CloudWatch

You can monitor AWS End User Messaging using CloudWatch, which collects raw data and processes it into readable, near real-time metrics. CloudWatch retains metric data for 15 months, so you can access historical information and gain a better perspective on how your application is performing. The namespace for AWS End User Messaging metrics is AWS/SMSVoice. The following table lists common MMS metrics. For the complete list, see the AWS/SMSVoice namespace in the CloudWatch console.

Common MMS metrics (AWS/SMSVoice namespace)
MetricDescription
MediaMessageMonthlySpend

The month-to-date spend on MMS messages, in US Dollars.

NumberOfMessagesReceived

The number of inbound messages received, including replies to an MMS message.

Messages expecting feedback

The number of messages sent with message feedback enabled that are awaiting an outcome. For more information, see Message feedback.

Note

AWS End User Messaging uses an AWS Identity and Access Management (IAM) service-linked role to publish metrics to CloudWatch. The service creates this role for you the first time you perform an action that publishes metrics, so in most cases you do not need to create it yourself.

Note

For some metrics, the result might be approximate due to the distributed nature of the service. The exact set of CloudWatch delivery metrics emitted for MMS [needs SME confirmation].

Filter metrics by origination identity type

Several metrics in the AWS/SMSVoice namespace support the OriginationIdentityType dimension, which lets you filter and group a metric by the type of origination identity that sent the message. For MMS this applies to the media message part metrics (NumberOfMediaMessagePartsSent and NumberOfMediaMessagePartsDelivered) and to MediaMessagesBlockedByProtect.

Use this dimension to compare sending and delivery across the identity types you use, for example to see how many parts were sent through a phone pool versus a sender ID. The dimension takes the following values.

OriginationIdentityType dimension values
ValueDescription
PHONE_NUMBER Messages sent using a phone number (long code, short code, or toll-free number).
SENDER_ID Messages sent using a sender ID.
POOL Messages sent using a phone pool. When you send through a pool, AWS End User Messaging selects the appropriate origination identity automatically.

With CloudWatch, you can also create alarms that trigger based on metric thresholds. For example, you can create an alarm on a sending metric so that if more than a chosen number of messages are sent in one hour, an email notification is sent to an Amazon SNS topic. For more information, see Using Amazon CloudWatch alarms in the Amazon CloudWatch User Guide.

Console
To create an alarm that notifies you when a metric exceeds a threshold

  1. Open the CloudWatch console.

  2. Choose Alarms in the navigation pane, and then choose Create alarm.

  3. Choose Select metric, choose the AWS/SMSVoice namespace, and choose the metric that you want to set an alarm for.

  4. Set the statistic to Sum, the period to 1 hour, the condition to Static and Greater than, and enter the threshold value.

  5. For the alarm action, choose an existing Amazon SNS topic to notify or create a new one, enter a name for the alarm, and choose Create alarm.

AWS CLI

Use the put-metric-alarm command. The following example alarms on an MMS metric and notifies an Amazon SNS topic.

$ aws cloudwatch put-metric-alarm \
> --alarm-name HighMediaSpend \
> --namespace AWS/SMSVoice \
> --metric-name MediaMessageMonthlySpend \
> --statistic Maximum \
> --period 3600 \
> --evaluation-periods 1 \
> --threshold 100 \
> --comparison-operator GreaterThanThreshold \
> --alarm-actions arn:aws:sns:us-east-1:111122223333:snsTopic

Send events to a destination with a configuration set

AWS End User Messaging emits an event for each message as it moves through sending and delivery. You route these events to a destination by creating a configuration set, adding one or more event destinations to it, and then specifying that configuration set when you send. The supported event destinations are Amazon CloudWatch, Amazon Data Firehose, and Amazon SNS.

To route events, create a configuration set, add one or more event destinations to it, and then specify that configuration set when you send. Both steps are shown in each tab.

Console
To create a configuration set and add an event destination

  1. Open the AWS End User Messaging console at https://console.aws.amazon.com/end-user-messaging/.

  2. In the navigation pane, under Configurations, choose Configuration sets, and then choose Create configuration set.

  3. For Configuration set name, enter a descriptive name, and then choose Create configuration set.

  4. On the Configuration set details page, choose Add destination event.

  5. Under Event details, enter a name, and for Destination type choose Amazon SNS (or CloudWatch or Firehose), then choose a new or existing Amazon SNS topic.

  6. Under Event types, choose the MMS events you want to send, or choose all events.

  7. Choose Add event destination.

AWS CLI

First, create the configuration set with the create-configuration-set command.

$ aws pinpoint-sms-voice-v2 create-configuration-set \
> --configuration-set-name configurationSet

Then add an event destination with the create-event-destination command. The following example adds an Amazon SNS destination; you can also send events to CloudWatch or Firehose. Set --matching-event-types to the event types you want to send.

$ aws pinpoint-sms-voice-v2 create-event-destination \
> --event-destination-name eventDestinationName \
> --configuration-set-name configurationSet \
> --matching-event-types eventTypes \
> --sns-destination TopicArn=arn:aws:sns:us-east-1:111122223333:snsTopic

For the complete list of event types and what each one means, see Event types for SMS, MMS, and voice. For the required IAM roles for each destination type, see Event destinations in AWS End User Messaging.

Send events to a destination with Amazon EventBridge

Unlike the other destinations, you do not add Amazon EventBridge to a configuration set. AWS End User Messaging sends events to Amazon EventBridge automatically, on your account's default event bus. To act on them, write Amazon EventBridge rules on the default bus that match the event type and route to a target such as Lambda, Amazon SNS, or Firehose. AWS End User Messaging sends media delivery status events, including Media Message Delivery Status Updated.

Console
To create a rule for AWS End User Messaging events

  1. Open the Amazon EventBridge console and choose Rules, then Create rule.

  2. Keep the default event bus, give the rule a name, and for the event pattern choose Custom pattern. Match "source": ["aws.sms-voice"] and the detail-type values you want.

  3. Choose a target, such as a Lambda function, Amazon SNS topic, or Firehose stream, and then create the rule.

AWS CLI

Create the rule with the put-rule command, then attach a target with put-targets.

$ aws events put-rule \
> --name mms-delivery-status \
> --event-pattern '{"source":["aws.sms-voice"],"detail-type":["Media Message Delivery Status Updated"]}'

$ aws events put-targets \
> --rule mms-delivery-status \
> --targets Id=1,Arn=arn:aws:lambda:us-east-1:111122223333:function:processEvent

For the full field reference and an example record for every event type, see Messaging Events.

Message feedback

Delivery metrics and events tell you a message was delivered, but not whether it achieved its purpose, such as whether the recipient opened or acted on the message. Message feedback closes that loop: after you send, you report the final outcome, and AWS End User Messaging uses that signal to improve how it routes your traffic.

You can enable message feedback in two ways:

  • Per message, at send time. Add --message-feedback-enabled to an individual send request to turn it on for that message only.

  • For every message, on a configuration set. Turn the setting on in a configuration set so that every message you send with that configuration set has feedback enabled.

After you enable it, report the outcome once you know it. The following tabs show the configuration set setting in the console and the per-send flag in the AWS CLI.

Console
To enable message feedback on a configuration set

  1. Open the AWS End User Messaging console at https://console.aws.amazon.com/end-user-messaging/.

  2. In the navigation pane, under Configurations, choose Configuration sets, and then choose your configuration set.

  3. Choose the Set settings tab, and then choose Edit settings.

  4. For Message feedback, enable the setting, and then choose Save changes.

You report the outcome with the API or AWS CLI (put-message-feedback); there is no console action for reporting an individual message outcome.

AWS CLI

To enable feedback for a single message, add --message-feedback-enabled to your send command. To enable it for every message instead, turn the setting on in a configuration set (see the Console tab) and send with that configuration set.

$ aws pinpoint-sms-voice-v2 send-media-message \
> --destination-phone-number +12065550150 \
> --origination-identity +14255550120 \
> --media-urls s3://amzn-s3-demo-bucket/image.jpg \
> --message-feedback-enabled

When you have a signal that the customer received or acted on the message, report the outcome with the put-message-feedback command, using the message ID from the send response. Set the status to RECEIVED or FAILED.

$ aws pinpoint-sms-voice-v2 put-message-feedback \
> --message-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
> --message-feedback-status RECEIVED

If you do not update the record within one hour it is automatically set to FAILED, and the CloudWatch feedback metrics update only after the record is set to RECEIVED or FAILED. For the full setup and outcome values, see Message feedback.

Logging API calls with CloudTrail

AWS CloudTrail captures API calls and related events made by or on behalf of your AWS account and delivers the log files to an Amazon S3 bucket that you specify. You can identify which users and accounts called AWS End User Messaging, the source IP address from which the calls were made, and when the calls occurred. For more information, see the AWS CloudTrail User Guide.