# Message and event destinations in AWS End User Messaging Social Message and event destinations An event destination is an Amazon SNS topic or Amazon Connect instance that WhatsApp events are sent to. When you turn on event publishing, all of your send and receive events are sent to the message and event destination. Use events to monitor, track, and analyze the status of outbound messages and incoming customer communications. Each WhatsApp Business Account (WABA) can have one event destination. All events from all resources associated to the WABA are logged to that event destination. For example, you could have a WABA with three phone numbers associated to it and all events from those phone numbers are logged to the one event destination. **Topics** + [ # Add a message and event destination to AWS End User Messaging Social ](managing-event-destinations-add.md) + [ # Message and event format in AWS End User Messaging Social ](managing-event-destination-dlrs.md) + [ # WhatsApp message status ](managing-event-destinations-status.md) # Add a message and event destination to AWS End User Messaging Social Add an event destination When you turn on message and event publishing, all of the events generated by your WhatsApp Business Account (WABA) are sent to the Amazon SNS topic. This includes events for each phone number associated to a WABA. Your WABA can have one Amazon SNS topic associated with it. ## Prerequisites Before you begin, the following prerequisites must be met to use either an Amazon SNS topic or Amazon Connect instance as a message and event destination. **Amazon SNS topic** + An Amazon SNS topic has been [created](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html) and [permissions](#managing-event-destinations-sns-policies) have been added. **Note** Amazon SNS FIFO topics are not supported. + **(Optional)** To use an Amazon SNS topic that is encrypted using AWS KMS keys you have to grant AWS End User Messaging Social permissions to the [existing key policy](#managing-event-destinations-topic-policies). **Amazon Connect instance** + An Amazon Connect instances has been [created](https://docs.aws.amazon.com/connect/latest/adminguide/tutorial1-set-up-your-instance.html) and [permissions](#managing-event-destinations-amazon-connect-policies) have been added. ## Add a message and event destination 1. Open the AWS End User Messaging Social console at [https://console.aws.amazon.com/social-messaging/](https://console.aws.amazon.com/social-messaging/). 1. Choose **Business account**, and then choose a WABA. 1. On the **Event destination** tab, choose **Edit destination**. 1. To turn on an event destination, choose **Enable**. 1. For **Destination type** choose either Amazon SNS or Amazon Connect 1. To send your events to an Amazon SNS destination, enter an existing topic ARN in **Topic ARN**. For example IAM policies, see [IAM policies for Amazon SNS topics](#managing-event-destinations-sns-policies). 1. For Amazon Connect 1. For **Connect instance** choose an instance from the drop down. 1. For **Two-way channel role**, choose either: 1. **Choose existing IAM role** – Choose an existing IAM policy from the **Existing IAM roles** drop down. For example IAM policies, see [IAM policies for Amazon Connect](#managing-event-destinations-amazon-connect-policies). 1. **Enter IAM role ARN** – Enter the ARN of the IAM policy into **Use existing IAM role Arn**. For example IAM policies, see [IAM policies for Amazon Connect](#managing-event-destinations-amazon-connect-policies). 1. Choose **Save changes**. ## Encrypted Amazon SNS topic policies You can use Amazon SNS topics that are encrypted using AWS KMS keys for an additional level of security. This added security can be helpful if your application handles private or sensitive data. For more information about encrypting Amazon SNS topics using AWS KMS keys, see [Enable compatibility between event sources from AWS services and encrypted topics](https://docs.aws.amazon.com/sns/latest/dg/sns-key-management.html#compatibility-with-aws-services) in the *Amazon Simple Notification Service Developer Guide*. **Note** Amazon SNS FIFO topics are not supported. The example statement uses the, optional but recommended, `SourceAccount` and `SourceArn` conditions to avoid the confused deputy problem and only the AWS End User Messaging Social owner account has access. For more information on the confused deputy problem, see [The confused deputy problem](https://docs.aws.amazon.com//IAM/latest/UserGuide/confused-deputy.html) in the *[IAM user guide](https://docs.aws.amazon.com//IAM/latest/UserGuide/introduction.html)*. The key that you use must be *symmetric*. Encrypted Amazon SNS topics don't support asymmetric AWS KMS keys. The key policy must be modified to allow AWS End User Messaging Social to use the key. Follow the directions in [Changing a key policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html), in the *AWS Key Management Service Developer Guide*, to add the following permissions to the existing key policy: ``` { "Effect": "Allow", "Principal": { "Service": "social-messaging.amazonaws.com" }, "Action": [ "kms:GenerateDataKey*", "kms:Decrypt" ], "Resource": "*", "Condition": { "StringEquals": { "aws:SourceAccount": "{ACCOUNT_ID}" }, "ArnLike": { "aws:SourceArn": "arn:{PARTITION}:social-messaging:{REGION}:{ACCOUNT_ID}:*" } } } ``` ## IAM policies for Amazon SNS topics To use an existing IAM role or to create a new role, attach the following policy to that role so that AWS End User Messaging Social can assume it. For information about how to modify the trust relationship of a role, see [Modifying a Role](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_manage.html) in the [https://docs.aws.amazon.com//IAM/latest/UserGuide/introduction.html](https://docs.aws.amazon.com//IAM/latest/UserGuide/introduction.html). The following is the **permission policy** for the IAM role. The permission policy allows for publishing to Amazon SNS topics. In the following IAM permission policy, make the following changes: + Replace *\$1PARTITION\$1* with the AWS partition that you use AWS End User Messaging Social in. + Replace *\$1REGION\$1* with the AWS Region that you use AWS End User Messaging Social in. + Replace *\$1ACCOUNT\$1* with the unique ID for your AWS account. + Replace *\$1TOPIC\$1NAME\$1* with the Amazon SNS topics that will receive messages. ``` { "Effect": "Allow", "Principal": { "Service": [ "social-messaging.amazonaws.com" ] }, "Action": "sns:Publish", "Resource": "arn:{PARTITION}:sns:{REGION}:{ACCOUNT}:{TOPIC_NAME}" } ``` ## IAM policies for Amazon Connect If you want AWS End User Messaging Social to use an existing IAM role or if you create a new role, attach the following policies to that role so that AWS End User Messaging Social can assume it. For information about how to modify an existing trust relationship of a role, see [Modifying a Role](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_manage.html) in the [https://docs.aws.amazon.com//IAM/latest/UserGuide/introduction.html](https://docs.aws.amazon.com//IAM/latest/UserGuide/introduction.html). This role is used for both sending events and importing phone numbers from AWS End User Messaging Social into Amazon Connect. To create new IAM polices, do the following: 1. Create a new **permission policy** by following the directions in [Creating policies using the JSON editor ](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html#access_policies_create-json-editor) in the IAM User Guide. 1. In step 5 use the **permission policy** for the IAM role to allow for publishing to Amazon Connect. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowOperationsForEventDelivery", "Effect": "Allow", "Action": [ "connect:SendIntegrationEvent" ], "Resource": "*" }, { "Sid": "AllowOperationsForPhoneNumberImport", "Effect": "Allow", "Action": [ "connect:ImportPhoneNumber", "social-messaging:GetLinkedWhatsAppBusinessAccountPhoneNumber", "social-messaging:TagResource" ], "Resource": "*" } ] } ``` ------ 1. Create a new **trust policy** by following the directions in [Creating a role using custom trust policies ](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html) in the IAM User Guide. 1. In step 4 use the **trust policy** for the IAM role. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "social-messaging.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } ``` ------ 1. In step 10 add the **permission policy** that you created in the previous step. ## Next steps Once you have set up your Amazon SNS topic, you must subscribe an endpoint to the topic. The endpoint will start to receive messages published to the associated topic. For more information on subscribing to a topic, see [Subscribing to an Amazon SNS topic](https://docs.aws.amazon.com//sns/latest/dg/sns-create-subscribe-endpoint-to-topic.html) in the *Amazon SNS Developer Guide*. # Message and event format in AWS End User Messaging Social Message and event format The JSON object for an event contains the AWS event header and WhatsApp JSON payload. For a list of the JSON WhatsApp notification payload and values, see [Webhooks Notification Payload Reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components) and [Message Status](https://developers.facebook.com/docs/whatsapp/conversation-types#message-status) in the *WhatsApp Business Platform Cloud API Reference*. ## AWS End User Messaging Social event header AWS End User Messaging Social event header The JSON object for an event contains the AWS event header and WhatsApp JSON. The header contains the AWS identifiers and ARNs of your WhatsApp Business Account (WABA) and phone number. ``` { "context": { "MetaWabaIds": [ { "wabaId": "1234567890abcde", "arn": "arn:aws:social-messaging:us-east-1:123456789012:waba/fb2594b8a7974770b128a409e2example" } ], "MetaPhoneNumberIds": [ { "metaPhoneNumberId": "abcde1234567890", "arn": "arn:aws:social-messaging:us-east-1:123456789012:phone-number-id/976c72a700aac43eaf573ae050example" } ] }, "whatsAppWebhookEntry": "{\"...JSON STRING....", "aws_account_id": "123456789012", "message_timestamp": "2025-01-08T23:30:43.271279391Z", "messageId": "6d69f07a-c317-4278-9d5c-6a84078419ec" } //Decoding the contents of whatsAppWebhookEntry { //WhatsApp notification payload } ``` In the preceding example event: + *1234567890abcde* is the WABA id from Meta. + *abcde1234567890* is the phone number id from Meta. + *fb2594b8a7974770b128a409e2example* is the ID of the WhatsApp Business Account (WABA). + *976c72a700aac43eaf573ae050example* is the ID of the phone number. ## Example WhatsApp JSON for receiving a message Example WhatsApp JSON for a message The following shows the event record for an incoming message from WhatsApp. The JSON received from WhatsApp in the `whatsAppWebhookEntry` is received as a JSON string and can be converted to JSON. For a list of fields and their meaning, see [Webhooks Notification Payload Reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components) in the *WhatsApp Business Platform Cloud API Reference*. ``` { "context": { "MetaWabaIds": [ { "wabaId": "1234567890abcde", "arn": "arn:aws:social-messaging:us-east-1:123456789012:waba/fb2594b8a7974770b128a409e2example" } ], "MetaPhoneNumberIds": [ { "metaPhoneNumberId": "abcde1234567890", "arn": "arn:aws:social-messaging:us-east-1:123456789012:phone-number-id/976c72a700aac43eaf573ae050example" } ] }, "whatsAppWebhookEntry": "{\"...JSON STRING....", "aws_account_id": "123456789012", "message_timestamp": "2025-01-08T23:30:43.271279391Z", "messageId": "6d69f07a-c317-4278-9d5c-6a84078419ec" } ``` You can use a tool, such as [jq](https://jqlang.org/), to convert the JSON string to JSON. The following is the `whatsAppWebhookEntry` in JSON form: ``` { "id": "503131219501234", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "14255550123", "phone_number_id": "46271669example" }, "statuses": [ { "id": "wamid.HBgLMTkxNzM5OTI3MzkVAgARGBJBMTM4NDdGRENEREI5Rexample", "status": "sent", "timestamp": "1736379042", "recipient_id": "01234567890", "conversation": { "id": "62374592e84cb58e52bdaed31example", "expiration_timestamp": "1736461020", "origin": { "type": "utility" } }, "pricing": { "billable": true, "pricing_model": "CBP", "category": "utility" } } ] }, "field": "messages" } ] } ``` ## Example WhatsApp JSON for receiving a media message Example WhatsApp JSON for a media message The following shows the event record for an incoming media message. To retrieve the media file, use the GetWhatsAppMessageMedia API command. For a list of fields and their meaning, see [Webhooks Notification Payload Reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components) ``` { //AWS End User Messaging Social header } //Decoding the contents of whatsAppWebhookEntry { "id": "365731266123456", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "12065550100", "phone_number_id": "321010217760100" }, "contacts": [ { "profile": { "name": "Diego" }, "wa_id": "12065550102" } ], "messages": [ { "from": "14255550150", "id": "wamid.HBgLMTQyNTY5ODgzMDIVAgASGCBDNzBDRjM5MDU2ODEwMDkwREY4ODBDRDE0RjVGRkexample", "timestamp": "1723506230", "type": "image", "image": { "mime_type": "image/jpeg", "sha256": "BTD0xlqSZ7l02o+/upusiNStlEZhA/urkvKf143Uqjk=", "id": "530339869524171" } } ] }, "field": "messages" } ] } ``` # WhatsApp message status Message status When you send a message, you receive status updates about the message. You have to enable event logging to receive these notifications, see [Message and event destinations in AWS End User Messaging SocialMessage and event destinations](managing-event-destinations.md). ## Message statuses The following table contains possible message statuses. **** | Status name | Description | | --- | --- | | accepted | The message has been accepted by WhatsApp for processing. | | deleted | The customer deleted the message, and you should also delete the message if it was downloaded to your server. | | delivered | The message was successfully delivered to the customer. | | failed | The message failed to send. | | Message retries exhausted, dropping message. | The message could not be handed off to WhatsApp within the 180-minute retry period and was dropped. | | read | The customer read the message. This status is only sent if the customer has read receipts turned on. | | sent | The message has been sent but is still in transit. | | warning | The message contains an item that is unavailable or doesn't exist. | ## Additional resources For more information, see [Message Status](https://developers.facebook.com/docs/whatsapp/conversation-types#message-status) in the *WhatsApp Business Platform Cloud API Reference*.