Skip to content

Commit cee4378

Browse files
v-shilsv-shils
authored
Merge pull request #280967 from memontic-ms/memontic/acs-update-events
Update ACS Advanced Messaging events
2 parents 57c2214 + 2165416 commit cee4378

File tree

1 file changed

+162
-22
lines changed

1 file changed

+162
-22
lines changed

‎articles/event-grid/communication-services-advanced-messaging-events.md

Lines changed: 162 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -2,42 +2,120 @@
22
title: Azure Communication Services - Advanced Messaging events
33
description: This article describes how to use Azure Communication Services as an Event Grid event source for Advanced Messaging Events.
44
ms.topic: conceptual
5-
ms.date: 09/30/2022
5+
ms.date: 07/15/2024
66
author: shamkh
77
ms.author: shamkh
88
---
99

1010
# Azure Communication Services - Advanced Messaging events
1111

12-
This article provides the properties and schema for communication services advanced messaging events. For an introduction to event schemas, see [Azure Event Grid event schema](event-schema.md).
12+
This article provides the properties and schema for Communication Services Advanced Messaging events. For an introduction to event schemas, see [Azure Event Grid event schema](event-schema.md).
1313

1414
## Event types
1515

1616
Azure Communication Services emits the following Advanced Messaging event types:
1717

18-
| Event type | Description |
19-
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
20-
| Microsoft.Communication.AdvancedMessageReceived | Published when Communication Service receives a WhatsApp message. |
21-
| Microsoft.Communication.AdvancedMessageDeliveryStatusUpdated | Published when the WhatsApp sends status of message notification as sent/read/failed. |
18+
| Event type | Description |
19+
|-----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
20+
| [Microsoft.Communication.AdvancedMessageReceived](#microsoftcommunicationadvancedmessagereceived-event) | Published when Communication Services Advanced Messaging receives a message. |
21+
| [Microsoft.Communication.AdvancedMessageDeliveryStatusUpdated](#microsoftcommunicationadvancedmessagedeliverystatusupdated-event) | Published when Communication Services Advanced Messaging receives a status update for a previously sent message notification. |
2222

2323
## Event responses
2424

2525
When an event is triggered, the Event Grid service sends data about that event to subscribing endpoints.
2626

2727
This section contains an example of what that data would look like for each event.
2828

29-
### Microsoft.Communication.AdvancedMessageReceived event
29+
### Microsoft.Communication.AdvancedMessageReceived event
30+
31+
Published when Communication Services Advanced Messaging receives a message.
32+
33+
Example scenario: A WhatsApp user sends a WhatsApp message to a WhatsApp Business Number that is connected to an active Advanced Messaging channel in a Communication Services resource. As a result, a `Microsoft.Communication.AdvancedMessageReceived` with the contents of the user's WhatsApp message is published.
34+
35+
#### Attribute list
36+
37+
Details for the attributes specific to `Microsoft.Communication.AdvancedMessageReceived` events.
38+
39+
| Attribute | Type | Nullable | Description |
40+
|:------------------|:-------------------------------------------:|:--------:|---------------------------------------------------------------------------|
41+
| channelType | `string` | ✔️ | Channel type of the channel that the message was sent on. Ex. "whatsapp". |
42+
| from | `string` | ✔️ | Sender ID that sent the message. |
43+
| to | `string` | ✔️ | The channel ID that received the message, formatted as a GUID. |
44+
| receivedTimestamp | `DateTimeOffset` | ✔️ | Timestamp of the message. |
45+
| content | `string` | ✔️ | The text content in the message. |
46+
| media | [`MediaContent`](#mediacontent) | ✔️ | Contains details about the received media. |
47+
| context | [`MessageContext`](#messagecontext) | ✔️ | Contains details about the received media. |
48+
| button | [`ButtonContent`](#buttoncontent) | ✔️ | Contains details about the received media. |
49+
| interactive | [`InteractiveContent`](#interactivecontent) | ✔️ | Contains details about the received media. |
50+
51+
##### MediaContent
52+
53+
| Attribute | Type | Nullable | Description |
54+
|:----------|:--------:|:--------:|--------------------------------------------------------------------------------------|
55+
| mimeType | `string` | ❌ | MIME type of the media. Used to determine the correct file type for media downloads. |
56+
| id | `string` | ❌ | Media ID. Used to retrieve media for download, formatted as a GUID. |
57+
| fileName | `string` | ✔️ | The filename of the underlying media file as specified when uploaded. |
58+
| caption | `string` | ✔️ | Caption text for the media object, if supported and provided. |
59+
60+
##### MessageContext
61+
62+
| Attribute | Type | Nullable | Description |
63+
|:----------|:--------:|:--------:|---------------------------------------------------------------------|
64+
| from | `string` | ✔️ | The WhatsApp ID for the customer who replied to an inbound message. |
65+
| id | `string` | ✔️ | The message ID for the sent message for an inbound reply. |
66+
67+
##### ButtonContent
68+
69+
| Attribute | Type | Nullable | Description |
70+
|:----------|:--------:|:--------:|----------------------------------------------------------------------------|
71+
| text | `string` | ✔️ | The text of the button. |
72+
| payload | `string` | ✔️ | The payload, set up by the business, of the button that the user selected. |
73+
74+
##### InteractiveContent
75+
76+
| Attribute | Type | Nullable | Description |
77+
|:------------|:-----------------------------------------------------------------:|:--------:|---------------------------------------------------|
78+
| type | [`InteractiveReplyType`](#interactivereplytype) | ✔️ | Type of the interactive content. |
79+
| buttonReply | [`InteractiveButtonReplyContent`](#interactivebuttonreplycontent) | ✔️ | Sent when a customer selects a button. |
80+
| listReply | [`InteractiveListReplyContent`](#interactivelistreplycontent) | ✔️ | Sent when a customer selects an item from a list. |
81+
82+
##### InteractiveReplyType
83+
84+
| Value | Description |
85+
|:------------|--------------------------------------|
86+
| buttonReply | The interactive content is a button. |
87+
| listReply | The interactive content is a list. |
88+
| unknown | The interactive content is unknown. |
89+
90+
##### InteractiveButtonReplyContent
91+
92+
| Attribute | Type | Nullable | Description |
93+
|:----------|:--------:|:--------:|----------------------|
94+
| id | `string` | ✔️ | ID of the button. |
95+
| title | `string` | ✔️ | Title of the button. |
96+
97+
##### InteractiveListReplyContent
98+
99+
| Attribute | Type | Nullable | Description |
100+
|:------------|:--------:|:--------:|----------------------------------|
101+
| id | `string` | ✔️ | ID of the selected list item. |
102+
| title | `string` | ✔️ | Title of the selected list item. |
103+
| description | `string` | ✔️ | Description of the selected row. |
104+
105+
#### Examples
106+
107+
##### Text message received
30108

31109
```json
32110
[{
33-
"id": "fdc64eca-390d-4974-abd6-1a13ccbe3160",
34-
"topic": "/subscriptions/{subscription-id}/resourcegroups/{resourcegroup-name}/providers/microsoft.communication/communicationservices/acsxplatmsg-test",
35-
"subject": "advancedMessage/sender/{sender@id}/recipient/00000000-0000-0000-0000-000000000000",
111+
"id": "00000000-0000-0000-0000-000000000000",
112+
"topic": "/subscriptions/{subscription-id}/resourcegroups/{resourcegroup-name}/providers/microsoft.communication/communicationservices/{communication-services-resource-name}",
113+
"subject": "advancedMessage/sender/{sender@id}/recipient/11111111-1111-1111-1111-111111111111",
36114
"data": {
37115
"content": "Hello",
38116
"channelType": "whatsapp",
39117
"from": "{sender@id}",
40-
"to": "00000000-0000-0000-0000-000000000000",
118+
"to": "11111111-1111-1111-1111-111111111111",
41119
"receivedTimestamp": "2023-07-06T18:30:19+00:00"
42120
},
43121
"eventType": "Microsoft.Communication.AdvancedMessageReceived",
@@ -47,15 +125,78 @@ This section contains an example of what that data would look like for each even
47125
}]
48126
```
49127

50-
### Microsoft.Communication.AdvancedMessageDeliveryStatusUpdated event
128+
##### Media message received
51129

52130
```json
53131
[{
54-
"id": "48cd6446-01dd-479f-939c-171c86c46700",
55-
"topic": "/subscriptions/{subscription-id}/resourcegroups/{resourcegroup-name}/providers/microsoft.communication/communicationservices/acsxplatmsg-test",
56-
"subject": "advancedMessage/00000000-0000-0000-0000-000000000000/status/Failed",
132+
"id": "00000000-0000-0000-0000-000000000000",
133+
"topic": "/subscriptions/{subscription-id}/resourcegroups/{resourcegroup-name}/providers/microsoft.communication/communicationservices/{communication-services-resource-name}",
134+
"subject": "advancedMessage/sender/{sender@id}/recipient/11111111-1111-1111-1111-111111111111",
57135
"data": {
58-
"messageId": "00000000-0000-0000-0000-000000000000",
136+
"channelType": "whatsapp",
137+
"media": {
138+
"mimeType": "image/jpeg",
139+
"id": "22222222-2222-2222-2222-222222222222",
140+
"caption": "This is a media caption"
141+
},
142+
"from": "{sender@id}",
143+
"to": "11111111-1111-1111-1111-111111111111",
144+
"receivedTimestamp": "2023-07-06T18:30:19+00:00"
145+
},
146+
"eventType": "Microsoft.Communication.AdvancedMessageReceived",
147+
"dataVersion": "1.0",
148+
"metadataVersion": "1",
149+
"eventTime": "2023-07-06T18:30:22.1921716Z"
150+
}]
151+
```
152+
153+
### Microsoft.Communication.AdvancedMessageDeliveryStatusUpdated event
154+
155+
Published when Communication Services Advanced Messaging receives a status update for a previously sent message notification.
156+
157+
Example scenario: Contoso uses an active Advanced Messaging channel connected to a WhatsApp Business Account to send a WhatsApp message to a WhatsApp user. WhatsApp then replies to Contoso's Advanced Messaging channel with the status of the previously sent message. As a result, a `Microsoft.Communication.AdvancedMessageDeliveryStatusUpdated` event containing the message status is published.
158+
159+
#### Attribute list
160+
161+
Details for the attributes specific to `Microsoft.Communication.AdvancedMessageReceived` events.
162+
163+
| Attribute | Type | Nullable | Description |
164+
|:------------------|:-----------------------------------------:|:--------:|----------------------------------------------------------------------------------------------------------------------------------------|
165+
| channelType | `string` | ✔️ | Channel type of the channel that the message was sent on. |
166+
| from | `string` | ✔️ | The channel ID that sent the message, formatted as a GUID. |
167+
| to | `string` | ✔️ | Recipient ID that the message was sent to. |
168+
| receivedTimestamp | `DateTimeOffset` | ✔️ | Timestamp of the message. |
169+
| messageId | `string` | ✔️ | The ID of the message, formatted as a GUID. |
170+
| status | `string` | ✔️ | Status of the message. Possible values include `Sent`, `Delivered`, `Read`, and `Failed`. For more information, see [Status](#status). |
171+
| error | [`ChannelEventError`](#channeleventerror) | ✔️ | Contains the details of an error. |
172+
173+
##### ChannelEventError
174+
175+
| Attribute | Type | Nullable | Description |
176+
|:---------------|:--------:|:--------:|---------------------------------------------|
177+
| channelCode | `string` | ✔️ | The error code received on this channel. |
178+
| channelMessage | `string` | ✔️ | The error message received on this channel. |
179+
180+
##### Status
181+
182+
| Value | Description |
183+
|:----------|---------------------------------------------------------|
184+
| Sent | The messaging service sent the message to the recipient |
185+
| Delivered | The message recipient received the message |
186+
| Read | The message recipient read the message |
187+
| Failed | The message failed to send correctly |
188+
189+
#### Examples
190+
191+
##### Update for message delivery
192+
193+
```json
194+
[{
195+
"id": "00000000-0000-0000-0000-000000000000",
196+
"topic": "/subscriptions/{subscription-id}/resourcegroups/{resourcegroup-name}/providers/microsoft.communication/communicationservices/{communication-services-resource-name}",
197+
"subject": "advancedMessage/22222222-2222-2222-2222-222222222222/status/Sent",
198+
"data": {
199+
"messageId": "22222222-2222-2222-2222-222222222222",
59200
"status": "Sent",
60201
"channelType": "whatsapp",
61202
"from": "{sender@id}",
@@ -69,13 +210,15 @@ This section contains an example of what that data would look like for each even
69210
}]
70211
```
71212

213+
##### Update for message delivery with failure
214+
72215
```json
73216
[{
74-
"id": "48cd6446-01dd-479f-939c-171c86c46700",
217+
"id": "00000000-0000-0000-0000-000000000000",
75218
"topic": "/subscriptions/{subscription-id}/resourcegroups/{resourcegroup-name}/providers/microsoft.communication/communicationservices/acsxplatmsg-test",
76-
"subject": "advancedMessage/00000000-0000-0000-0000-000000000000/status/Failed",
219+
"subject": "advancedMessage/22222222-2222-2222-2222-222222222222/status/Failed",
77220
"data": {
78-
"messageId": "00000000-0000-0000-0000-000000000000",
221+
"messageId": "22222222-2222-2222-2222-222222222222",
79222
"status": "Failed",
80223
"channelType": "whatsapp",
81224
"from": "{sender@id}",
@@ -93,9 +236,6 @@ This section contains an example of what that data would look like for each even
93236
}]
94237
```
95238

96-
> [!NOTE]
97-
> Possible values for `Status` are `Sent`, `Delivered`, `Read` and `Failed`.
98-
99239

100240
## Quickstart
101241
For a quickstart that shows how to subscribe for Advanced Messaging events using web hooks, see [Quickstart: Handle Advanced Messaging events](../communication-services/quickstarts/advanced-messaging/whatsapp/handle-advanced-messaging-events.md).

0 commit comments

Comments
 (0)