# Callbacks and events (/en/realtime-media/im/build/notifications-and-event-handling/callbacks-events) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). Chat supports HTTP callbacks (webhooks). You can listen for event callbacks and add app logics accordingly. Once a registered callback is triggered by a specified type of event, the Chat server sends an HTTP POST request to your app server, notifying you that the event occurs. The request body is a JSON string encoded in UTF-8 characters. This page introduces the events and callbacks in Chat. ## User login and logout events [#user-login-and-logout-events] When a user logs in to or logs out of the Chat app, the Chat server sends a callback to your app server. ### Log in to the app [#log-in-to-the-app] When a user logs in to the Chat app, the Chat server sends a callback to your app server. The sample code is as follows: ```json { "callId":"XXXX#XXXXe393c568-5ae5-4a0e-8a2c-008b52b49eed", "reason":"login", "security":"XXXXae2eXXXXced298883a0cf06d41b9", "os":"ios", "ip":"************", "host":"*******", "appkey":"XXXX#XXXX", "user":"XXXX#XXXXtstXXXX/ios_XXXX01fd-b5a4-84d5-ebeb-bf10XXXX0442", "version":"3.8.9.1", "timestamp":1642585154644, "status":"online" } ``` | Field | Data Type | Description | | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `callId` | String | The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated. | | `reason` | String | The reason that triggers the callback. `login` indicates that a user logs in to the app. | | `security` | String | The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on [Agora Console](https://console.agora.io/v2). | | `os` | String | The operating system of the device. Valid values: `ios`, `android`, `linux`, `win`, and `other.` | | `ip` | String | The IP address of the user who logs in to the app. | | `host` | String | The domain name assigned by the Chat service to access RESTful APIs. | | `appkey` | String | The key of the app. The unique identifier assigned to each app by the Chat service. | | `user` | String | The ID of the user. The unique identifier of each user in the Chat app, in the format of `{appKey}/{OS}_{deviceId}`. | | `version` | String | The version of the Chat SDK. | | `timestamp` | Long | The Unix timestamp when the Chat server receives the login request, in milliseconds. | | `status` | String | The current status of the user. `online` indicates that the user is online. | ### Log out of the app voluntarily [#log-out-of-the-app-voluntarily] When a user logs out of the Chat app, the Chat server sends a callback to your app server. The sample code is as follows: ```json { "callId":"XXXX#XXXX25b54a81-1376-4669-bb3d-178339a8f11b", "reason":"logout", "security":"XXXXd77eXXXXf26801627fdaadca987e", "os":"ios", "ip":"223.71.97.198:4XXXX", "host":"********", "appkey":"XXXX#XXXX", "user":"XXXX#XXXXtstXXXX/ios_XXXX0737-db3a-d2b5-da18-b604XXXX195b", "version":"3.8.9.1", "timestamp":1642648914742, "status":"offline" } ``` | Field | Data Type | Description | | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `callId` | String | The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated. | | `reason` | String | The reason that triggers the callback. `logout` indicates that a user logs out of the app. | | `security` | String | The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on [Agora Console](https://console.agora.io/v2). | | `os` | String | The operating system of the device. Valid values: `ios`, `android`, `linux`, `win`, and `other.` | | `ip` | String | The IP address of the user who logs out of the app. | | `host` | String | The domain name assigned by the Chat service to access RESTful APIs. | | `appkey` | String | The key of the app. The unique identifier assigned to each app by the Chat service. | | `user` | String | The ID of the user. The unique identifier of each user in the Chat app, in the format of `{appKey}/{OS}_{deviceId}`. | | `version` | String | The version of the Chat SDK. | | `timestamp` | Long | The Unix timestamp when the Chat server receives the logout request, in milliseconds. | | `status` | String | The current status of the user. `offline` indicates that the user is offline. | ### Log out of the app passively [#log-out-of-the-app-passively] When a user logs out of the Chat app due to being kicked out by another device, the Chat server sends a callback to your app server. The sample code is as follows: ```json { "callId":"XXXX#XXXX260ae3eb-ba31-4f01-9a62-8b3b05f3a16c", "reason":"replaced", "security":"XXXX00b1XXXX4fe76dbfdc664cbaa76b", "os":"ios","ip":"223.71.97.198:52709", "host":"msync@ebs-ali-beijing-msync40", "appkey":"XXXX#XXXX", "user":"XXXX#XXXXtst01XXXX/ios_XXXX01fd-b5a4-84d5-ebeb-bf10XXXX0442", "version":"3.8.9.1", "timestamp":1642648955563, "status":"offline" } ``` | Field | Data Type | Description | | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `callId` | String | The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated. | | `reason` | String | The reason that triggers the callback. `replaced` indicates that a user logs out of the app due to being kicked out by another device. | | `security` | String | The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on [Agora Console](https://console.agora.io/v2). | | `os` | String | The operating system of the device. Valid values: `ios`, `android`, `linux`, `win`, and `other.` | | `ip` | String | The IP address of the user. | | `host` | String | The domain name assigned by the Chat service to access RESTful APIs. | | `appkey` | String | The key of the app. The unique identifier assigned to each app by the Chat service. | | `user` | String | The ID of the user. The unique identifier of each user in the Chat app, in the format of `{appKey}/{OS}_{deviceId}`. | | `version` | String | The version of the Chat SDK. | | `timestamp` | Long | The Unix timestamp when the Chat server receives the logout request, in milliseconds. | | `status` | String | The current status of the user. `offline` indicates that the user is offline. | ## Message events [#message-events] ### Send a message [#send-a-message] When a user sends a message in a one-to-one chat, chat group, or chat room of the Chat app, the Chat server sends a callback to your app server. The sample code is as follows: ```json { "callId":"{appkey}_{uuid}", "eventType":"chat_offline", "timestamp":1600060847294, "chat_type":"groupchat", "group_id":"1693XXXX238921545", "from":"user1", "to":"user2", "msg_id":"8924XXXX42322", "payload":{ // The details of the callback. }, "securityVersion":"1.0.0", "security":"XXXX2c39XXXX9e7abc83958bcc3156d3" } ``` | Field | Data Type | Description | | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `callId` | String | The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated. | | `eventType` | String | The message type of the callback. `chat`: Uplink messages. The messages that are about to be sent by the Chat server to end devices. `chat_offline`: Offline messages. The messages that are not sent by the Chat server as end users are offline. | | `timestamp` | Long | The Unix timestamp when the Chat server receives the callback event, in milliseconds. | | `chat_type` | String | The type of chat. `chat`: One-to-one chats. `groupchat`: Chat groups and chat rooms. | | `group_id` | String | The ID of the chat group or chat room where the message is sent. This field only exists if `chat_type` is set to `groupchat`. | | `from` | String | The sender of the message. | | `to` | String | The recipient of the message. | | `msg_id` | String | The message ID of the callback event. This ID is the same as the `msg_id` when the message is sent. | | `payload` | Object | The structure of the callback event. This field varies according to the type of the message sent in a one-to-one chat, chat group, or chat room. See payload example below for details. | | `securityVersion` | String | This parameter is reserved for future use. | | `security` | String | The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on [Agora Console](https://console.agora.io/v2). | | `appkey` | String | The key of the app. The unique identifier assigned to each app by the Chat service. | | `host` | String | The domain name assigned by the Chat service to access RESTful APIs. | #### Send a text message [#send-a-text-message] When a user sends a text message in a one-to-one chat, chat group, or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "ext":{}, "bodies":[ { "msg":"rr", "type":"txt" } ] } ``` `ext` indicates the message extension in Object data type. `bodies` indicates the message body in Object data type, which contains the following fields: | Field | Data Type | Description | | :----- | :-------- | :------------------------------------------------------- | | `msg` | String | The content of the text message. | | `type` | String | The type of the message. `txt` indicates a text message. | #### Send an image message [#send-an-image-message] When a user sends an image message in a one-to-one chat, chat group, or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "ext":{}, "bodies":[ { "filename":"image", "size": { "width":746, "height":1325 }, "secret":"XXXXqnkRXXXXAUHNhFQyIhTJxWxvGOwyx1", "file_length":118179, "type":"img", "url":"https://a1.agora.com/" } ] } ``` `ext` indicates the message extension in Object data type. `bodies` indicates the message body in Object data type, which contains the following fields: | Field | Data Type | Description | | :------------ | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `filename` | String | The filename of the image. | | `secret` | String | The secret returned after uploading the image file. | | `size` | Json | The dimension of the image in pixels. `height`: The height of the image. `width`: The width of the image. | | `file_length` | Int | The size of the image in bytes. | | `url` | String | The URL of the image, in the format of `https://{host}/app-id/{app_id}/chatfiles/{file_uuid}`, where `file_uuid` is the ID of the image file. You can fetch `file_uuid` from the response body after the file is uploaded. | | `type` | String | The type of the message. `img` indicates an image message. | #### Send an audio message [#send-an-audio-message] When a user sends an audio message in a one-to-one chat, chat group, or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "ext":{}, "bodies":[ { "filename":"audio", "length":4, "secret":"XXXXynkRXXXX1e0Ksmmt2Ym6AzpRr9SxsUpF", "file_length":6374, "type":"audio", "url":"https://a1.agora.com/" } ] } ``` `ext` indicates the message extension in Object data type. `bodies` indicates the message body in Object data type, which contains the following fields: | Field | Data Type | Description | | :------------ | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `filename` | String | The filename of the audio. | | `secret` | String | The secret returned after uploading the audio file. | | `file_length` | Long | The size of the audio file in bytes. | | `length` | Int | The duration of the audio file in seconds. | | `url` | String | The URL of the audio file, in the format of `https://{host}/app-id/{app_id}/chatfiles/{file_uuid}`, where `file_uuid` is the ID of the audio file. You can fetch `file_uuid` from the response body after the file is uploaded. | | `type` | String | The type of the message. `audio` indicates an audio message. | #### Send a video message [#send-a-video-message] When a user sends a video message in a one-to-one chat, chat group, or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "ext":{}, "bodies":[ { "thumb_secret":"t1AEXXXXEeyS81-d10_HOpjSZc8TD-ud40XXXXOStQrr7Mbc", "filename":"video.mp4", "size": { "width":360, "height":480 }, "thumb":"https://a1.agora.com/agora-demo/shuang/chatfiles/XXXX0400-7a8b-11ec-8d83-7106XXXX33e6", "length":10, "secret":"XXXXgHqLXXXXBfuoalZCJPD7PVcoOu_RHTRa78bjU_KQAPr2", "file_length":601404, "type":"video", "url":"https://a1.agora.com/agora-demo/shuang/chatfiles/XXXX3270-7a8b-11ec-9735-6922XXXXb891" } ] } ``` `ext` indicates the message extension in Object data type. `bodies` indicates the message body in Object data type, which contains the following fields: | Field | Data Type | Description | | -------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `thumb_secret` | String | The secret returned after uploading the video thumbnail. | | `filename` | String | The filename of the video. | | `size` | Json | The dimension of the video thumbnail. `height`: The height of the thumbnail. `width`: The width of the thumbnail. | | `thumb` | String | The URL of the thumbnail, in the format of `https://{host}/app-id/{app_id}/chatfiles/{file_uuid}`, where `file_uuid` is the ID of the video thumbnail. You can fetch `file_uuid` from the response body after the video thumbnail is uploaded. | | `secret` | String | The secret returned after uploading the video file. | | `file_length` | Long | The size of the video file in bytes. | | `url` | String | The URL of the video file, in the format of `https://{host}/app-id/{app_id}/chatfiles/{file_uuid}`, where `file_uuid` is the ID of the video file. You can fetch `file_uuid` from the response body after the video file is uploaded. | | `type` | String | The type of the message. `video` indicates a video message. | #### Send a location message [#send-a-location-message] When a user sends a location message in a one-to-one chat, chat group, or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "ext":{}, "bodies":[ { "lng":116.32309156766605, "type":"loc", "addr":"********", "lat":39.96612729238626 } ] } ``` `ext` indicates the message extension in Object data type. `bodies` indicates the message body in Object data type, which contains the following fields: | Field | Data Type | Description | | ------ | --------- | ------------------------------------------------------------ | | `log` | String | The longitude of the location. | | `lat` | String | The latitude of the location. | | `addr` | String | The address of the location. | | `type` | String | The type of the message. `loc` indicates a location message. | #### Send a command message [#send-a-command-message] When a user sends a command message in a one-to-one chat, chat group, or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "ext":{}, "bodies":[ { "msg":"rr", "type":"cmd" } ] } ``` `ext` indicates the message extension in Object data type. `bodies` indicates the message body in Object data type, which contains the following fields: | Field | Data Type | Description | | :----- | :-------- | :---------------------------------------------------------- | | `msg` | String | The content of the command message. | | `type` | String | The type of the message. `cmd` indicates a command message. | #### Send a custom message [#send-a-custom-message] When a user sends a custom message in a one-to-one chat, chat group, or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "ext":{}, "bodies":[ { "customExts": [ {"name": 1 } ], "v2:customExts":{"k":"v","k1":"v1"}, "customEvent": "flower", "type": "custom" } ] } ``` `ext` indicates the message extension in Object data type. `bodies` indicates the message body in Object data type, which contains the following fields: | Field | Data Type | Description | | -------------------------- | --------- | ----------------------------------------------------------------------------------------------------------- | | `customExts/v2:customExts` | Json | The attribute of the custom event, in the `Map` format. The attribute can contain a maximum of 16 elements. | | `customEvent` | String | The type of the custom event. The type can be 1 to 32 characters. | | `type` | String | The type of the message. `custom` indicates a custom message. | ### Recall a message [#recall-a-message] When a user recalls a message in a one-to-one chat, chat group, or chat room of the Chat app, the Chat server sends a callback to your app server. The sample code is as follows: ```json { "chat_type":"recall", "callId":"orgname#appname_9664XXXX5536657404", "security":"ea7aXXXX14fbXXXX33d5f4f169eb4f8d", "payload": { "ext":{}, "ack_message_id":"9664XXXX0900644860", "bodies":[] }, "host":"******", "appkey":"orgname#appname", "from":"tst", "recall_id":"9664XXXX0900644860", "to":"1709XXXX2023810", "eventType":"chat", "msg_id":"9664XXXX5536657404", "timestamp":1642589932646 } ``` | Field | Data Type | Description | | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `callId` | String | The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated. | | `eventType` | String | The message type of the callback. `chat`: Uplink messages. The messages that are about to be sent by the Chat server to end devices. `chat_offline`: Offline messages. The messages that are not sent by the Chat server as the end user is offline. | | `timestamp` | Long | The Unix timestamp when the Chat server receives the callback event, in milliseconds. | | `chat_type` | String | The type of chat. `chat`: One-to-one chats. `groupchat`: Chat groups and chat rooms. | | `group_id` | String | The ID of the chat group or chat room where the message resides. This field only exists if `chat_type` is set to `groupchat`. | | `from` | String | The sender of the message. | | `to` | String | The recipient of the message. | | `recall_id` | String | The ID of the message to recall. | | `msg_id` | String | The message ID of the callback event. This ID is the same as the `msg_id` when the end user sends the message. | | `payload` | Object | The structure of the callback event that contains the following fields: `ext`: The message extension. This field is empty when recalling a message. `ack_message_id`: The ID of the message to recall. This ID is the same as `recall_id`. `bodies`: The body of the message callback. This field is empty when recalling a message. | | `securityVersion` | String | This parameter is reserved for future use. | | `security` | String | The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on [Agora Console](https://console.agora.io/v2). | | `appkey` | String | The key of the app. The unique identifier assigned to each app by the Chat service. | | `host` | String | The domain name assigned by the Chat service to access RESTful APIs. | ## Chat group and chat room events [#chat-group-and-chat-room-events] When a user performs operations on a chat group or chat room in the Chat app, the Chat server sends a callback to your app server. The sample code is as follows: ```json { "chat_type": "muc", "callId": "XXXX#XXXX", "security": "XXXX", "payload":{ // The details of the callback. }, "group_id": "1735XXXX6122369", "host": "XXXX", "appkey": "XXXX#XXXX", "from": "XXXX#XXXX_1111@easemob.com/android_8070d7b2-795eb6e63d", "to": "1111", "eventType": "chat", "msg_id": "9764XXXX3882744164", "timestamp": 1644914583273 } ``` | Field | Data Type | Description | | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `chat_type` | String | The type of the event. `muc` indicates a chat group or a chat room. | | `callId` | String | The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{file_uuid}`, where the value of `file_uuid` is randomly generated. | | `eventType` | String | The message type of the callback. `chat`: Uplink messages. The messages that are about to be sent by the Chat server to end devices. `chat_offline`: Offline messages. The messages that are not sent by the Chat server as the end user is offline. | | `timestamp` | Long | The Unix timestamp when the Chat server receives the callback event, in milliseconds. | | `group_id` | String | The ID of the chat group or chat room where the message resides. This field only exists if `chat_type` is set to `groupchat`. | | `from` | String | The sender of the message. | | `to` | String | The recipient of the message. | | `msg_id` | String | The message ID of the callback event. This ID is the same as the `msg_id` when sending the message. | | `payload` | Object | The content structure of the callback event that contains the following fields: `muc_id`: The unique identifier of the chat group or chat room in the Chat server, in the format of `{appkey}_{group_ID}@conference.easemob.com`. `reason`: Optional. The detailed information about the current operation. See payload example below for details. `is_chatroom`: Whether this event occurs in a chat room. `true`: Yes. `false`: No, this event occurs in a chat group. `operation`: The current operation. See payload example below for details. `status`: The status of the current operation. `description`: The status description. `error_code`: The status code. | | `securityVersion` | String | This parameter is reserved for future use. | | `security` | String | The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on [Agora Console](https://console.agora.io/v2). | | `appkey` | String | The key of the app. The unique identifier assigned to each app by the Chat service. | | `host` | String | The domain name assigned by the Chat service to access RESTful APIs. | ### Create a chat group or chat room [#create-a-chat-group-or-chat-room] This callback is triggered only if the multi-device service is enabled. Once a user creates a chat group or chat room on one device, the Chat server sends callbacks to the other devices, notifying about the creation of the chat group or chat room. When a user creates a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX_173556296122369@conference.easemob.com", "reason": "", "is_chatroom": false, // "create" indicates that the current operation is to create a chat group or chat room. "operation": "create", "status": { "description":"", "error_code": "ok" } } ``` ### Destroy a chat group or chat room [#destroy-a-chat-group-or-chat-room] When the owner destroys a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX_173548612157441@conference.easemob.com", "reason": "", "is_chatroom": false, // "destroy" indicates that the current operation is to destroy a chat group or chat room. "operation": "destroy", "status": { "description": "", "error_code": "ok" } } ``` ### Send a join request to a chat group [#send-a-join-request-to-a-chat-group] When a user sends a join request to a chat group, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX_.com", // The content of the join request. "reason": "join group123", "is_chatroom": false, // "apply" indicates that the current operation is to send a join request to a chat group or chat room. "operation": "apply", "status": { "description": "", "error_code": "ok" } } ``` ### Accept a join request [#accept-a-join-request] When the owner or an admin accepts a join request to the chat group, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX", "reason": "", "is_chatroom": false, // "apply_accept" indicates that the current operation is to accept a join request. "operation": "apply_accept", "status": { "description": "", "error_code": "ok" } } ``` ### Send a group invitation to a user [#send-a-group-invitation-to-a-user] When a user invites another user to a chat group, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX", // The content of the group invitation. "reason": "Hello", "is_chatroom": false, // "invite" indicates that the current operation is to send a group invitation to a user. "operation": "invite", "status": { "description": "", "error_code": "ok" } } ``` ### Accept a group invitation [#accept-a-group-invitation] When a user accepts a group invitation, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173549292683265XXXX", "reason": "", "is_chatroom": false, // "invite_accept" indicates that the current operation is to accept a group invitation. "operation": "invite_accept", "status": { "description": "", "error_code": "ok" } } ``` ### Decline a group invitation [#decline-a-group-invitation] When a user declines a group invitation, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173549292683265XXXX", "reason": "", "is_chatroom": false, // "invite_decline" indicates that the current operation is to decline a group invitation. "operation": "invite_decline", "status": { "description": "", "error_code": "ok" } } ``` ### Join a chat group or chat room [#join-a-chat-group-or-chat-room] When a user joins a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", "is_chatroom": false, // "presence" indicates that the current operation is to join a chat group or chat room. "operation": "presence", "status": { "description": "", "error_code": "ok" } } ``` ### Leave a chat group or chat room [#leave-a-chat-group-or-chat-room] When a member voluntarily leaves a group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", "is_chatroom": false, // "leave" indicates that the current operation is to leave a chat room. "operation": "leave", "status": { "description": "", "error_code": "ok" } } ``` When a member voluntarily or passively leaves a chat group or chat room, the Chat server sends the leave result to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", "is_chatroom": false, // "absence" indicates the result of leaving a chat group or chat room. "operation": "absence", "status": { "description": "", "error_code": "ok" } } ``` ### Remove a member from a chat group or chat room [#remove-a-member-from-a-chat-group-or-chat-room] When the owner or an admin removes a member from a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173549292683265XXXX", "is_chatroom": false, // "kick" indicates that the current operation is to remove a member from a chat group or chat room. "operation": "kick", "status": { "description": "", "error_code": "ok" } } ``` ### Add a member to the blocklist of a chat group or chat room [#add-a-member-to-the-blocklist-of-a-chat-group-or-chat-room] When the owner or an admin adds a member to the blocklist of a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173558358671361@conference.easemob.com", "reason": "", "is_chatroom": false, // "ban" indicates that the current operation is to add a member to the blocklist of a chat group or chat room. "operation": "ban", "status": { "description": "", "error_code": "ok" } } ``` ### Remove a member from the blocklist of a chat group or chat room [#remove-a-member-from-the-blocklist-of-a-chat-group-or-chat-room] When the owner or an admin removes a member from the blocklist of a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173549292683265XXXX", "reason": "undefined", "is_chatroom": false, // "allow" indicates that the current operation is to remove a member from the blocklist of a chat group or chat room. "operation": "allow", "status": { "description": "", "error_code": "ok" } } ``` ### Add a member to the allow list of a chat group or chat room [#add-a-member-to-the-allow-list-of-a-chat-group-or-chat-room] When the owner or an admin adds a member to the allow list of a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173549292683265XXXX", "is_chatroom": false, // "add_user_white_list" indicates that the current operation is to add a member to the allow list of a chat group or chat room. "operation": "add_user_white_list", "status": { "description": "", "error_code": "ok" } } ``` ### Remove a member from the allow list of a chat group or chat room [#remove-a-member-from-the-allow-list-of-a-chat-group-or-chat-room] When the owner or an admin removes a member from the allow list of a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173549292683265XXXX", "is_chatroom": false, // "remove_user_white_list" indicates that the current operation is to remove a member from the allow list of a chat group or chat room. "operation": "remove_user_white_list", "status": { "description": "", "error_code": "ok" } } ``` ### Mute a member in a chat group or chat room [#mute-a-member-in-a-chat-group-or-chat-room] When the owner or an admin mutes a member in a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", "reason": "", "is_chatroom": false, // "add_mute" indicates that the current operation is to mute a member. "operation": "add_mute", "status": { "description": "", "error_code": "ok" } } ``` ### Unmute a member in a chat group or chat room [#unmute-a-member-in-a-chat-group-or-chat-room] When the owner or an admin unmutes a member in a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", "reason": "", "is_chatroom": false, // "remove_mute" indicates that the current operation is to unmute a member. "operation": "remove_mute", "status": { "description": "", "error_code": "ok" } } ``` ### Mute a chat group or chat room [#mute-a-chat-group-or-chat-room] When a member mutes a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", "is_chatroom": false, // "block" indicates that the current operation is to mute a chat group or chat room. "operation": "block", "status": { "description": "", "error_code": "ok" } } ``` ### Unmute a chat group or chat room [#unmute-a-chat-group-or-chat-room] When a member unmutes a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", "is_chatroom": false, // "unblock" indicates that the current operation is to unmute a chat group or chat room. "operation": "unblock", "status": { "description": "", "error_code": "ok" } } ``` ### Mute a chat group or chat room globally [#mute-a-chat-group-or-chat-room-globally] When a chat group or chat room is globally muted, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173553668390913XXXX", "is_chatroom": false, // "ban_group" indicates that the current operation is to globally mute a chat group or chat room. "operation": "ban_group", "status": { "description": "", "error_code": "ok" } } ``` ### Unmute a chat group or chat room globally [#unmute-a-chat-group-or-chat-room-globally] When a chat group or chat room is globally unmuted, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173553668390913XXXX", "is_chatroom": false, // "remove_ban_group" indicates that the current operation is to globally unmute a chat group or chat room. "operation": "remove_ban_group", "status": { "description": "", "error_code": "ok" } } ``` ### Transfer the ownership [#transfer-the-ownership] When the owner transfers the ownership of a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", "is_chatroom": false, // "assing_owner" indicates that the current operation is to transfer the ownership of a chat group or chat room. "operation": "assing_owner", "status": { "description": "", "error_code": "ok" } } ``` ### Promote a member to an admin [#promote-a-member-to-an-admin] When the owner promotes a member to an admin in a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", "is_chatroom": false, // "add_admin" indicates that the current operation is to promote a member to an admin. "operation": "add_admin", "status": { "description": "", "error_code": "ok" } } ``` ### Demote an admin to a member [#demote-an-admin-to-a-member] When the owner demotes an admin to a member in a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", "is_chatroom": false, // "remove_admin" indicates that the current operation is to demote an admin to a member. "operation": "remove_admin", "status": { "description": "", "error_code": "ok" } } ``` ### Update the information of a chat group or chat room [#update-the-information-of-a-chat-group-or-chat-room] When the owner or an admin updates the information of a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173549200408577XXXX", "is_chatroom": false, // "update" indicates that the current operation is to update the information about a chat group or chat room. "operation": "update", "status": { "description": "", "error_code": "ok" } } ``` ### Update the announcements of a chat group or chat room [#update-the-announcements-of-a-chat-group-or-chat-room] When the owner or an admin updates the announcements of a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", // The updated announcement. "reason": "gogngao", "is_chatroom": false, // "update_announcement" indicates that the current operation is to update the announcement of a chat group or chat room. "operation": "update_announcement", "status": { "description": "", "error_code": "ok" } } ``` ### Delete the announcements of a chat group or chat room [#delete-the-announcements-of-a-chat-group-or-chat-room] When the owner or an admin deletes the announcements of a chat group or chat room, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", // The deleted announcement, which is empty. "reason": "", "is_chatroom": false, // "delete_announcement" indicates that the current operation is to delete the announcement of a chat group or chat room. "operation": "delete_announcement", "status": { "description": "", "error_code": "ok" } } ``` ### Upload a shared file to a chat group [#upload-a-shared-file-to-a-chat-group] When a user uploads a shared file to a chat group, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173560762007553XXXX", "reason": "{ \"data\":{ \"file_id\":\"79ddf840-8e2f-11ec-bec3-ad40868b03f9\", \"file_name\":\"a.csv\", \"file_owner\":\"@ppAdmin\", \"file_size\":6787, \"created\":1644909510085 } }", "is_chatroom": false, // "upload_file" indicates that the current operation is to upload a shared file to a chat group. "operation": "upload_file", "status": { "description": "", "error_code": "ok" } } ``` `reason` indicates the details of the shared file uploaded to a chat group, which contains the following fields: * `file_id`: The ID of the file. * `file_name`: The filename. * `file_owner`: The owner of the file, that is, the ID of the user who uploads the file. * `file_size`: The size of the file in bytes. * `created`: The Unix timestamp when the file is created, in milliseconds. ### Delete a shared file in a chat group [#delete-a-shared-file-in-a-chat-group] When a user deletes a shared file in a chat group, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "muc_id": "XXXX#XXXX173549292683265XXXX", // "reason" specifies the ID of the shared file to delete. This ID is the same as the "file_id" used when uploading the file. "reason": "79ddf840-8e2f-11ec-bec3-ad40868b03f9", "is_chatroom": false, // "delete_file" indicates that the current operation is to delete a shared file in a chat group. "operation": "delete_file", "status": { "description": "", "error_code": "ok" } } ``` ## User contact events [#user-contact-events] When a user performs operations on the contacts in the Chat app, the Chat server sends a callback to your app server. The sample code is as follows: ```json { "chat_type": "roster", "callId": "orgname#appname_9664XXXX5536657404", "security": "XXXXa9feXXXX69241e17b15e2783dbb1", "payload": { // The details of the callback. }, "host": "msync@ebs-ali-beijing-msync26", "appkey":"orgname#appname", "from":"tst", "to":"tst01", "eventType":"chat", "msg_id":"9664XXXX5536657404", "timestamp":1642589932646 } ``` | Field | Data Type | Description | | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `chat_type` | String | The type of the event. `roster` indicates an event occurred in user contacts. | | `callId` | String | The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated. | | `eventType` | String | The message type of the callback. `chat`: Uplink messages. The messages that are about to be sent by the Chat server to end devices. `chat_offline`: Offline messages. The messages that are not sent by the Chat server as the end user is offline. | | `timestamp` | Long | The Unix timestamp when the Chat server receives the callback event, in milliseconds. | | `from` | String | The user who operates the contact. | | `to` | String | The contact who is operated by the user. | | `msg_id` | String | The message ID of the callback event. This ID is the same as the `msg_id` when sending the message. | | `payload` | Object | The structure of the callback event. See payload example below for details. | | `security` | String | The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on [Agora Console](https://console.agora.io/v2). | | `appkey` | String | The key of the app. The unique identifier assigned to each app by the Chat service. | | `host` | String | The domain name assigned by the Chat service to access RESTful APIs. | ### Send a contact invitation [#send-a-contact-invitation] When a user adds a contact in the Chat app, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { "reason":"", // "add" indicates that the current operation is to add a contact. "operation":"add" } ``` ### Remove a contact [#remove-a-contact] When a user removes a contact in the Chat app, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { // The version of the contact list. "roster_ver":"XXXXD920XXXX5B51EB0B806E83BDD97F089B0092", // "remove" indicates that the current operation is to remove a contact. "operation":"remove" } ``` ### Accept a contact invitation [#accept-a-contact-invitation] When a user accepts the contact invitation from another user, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { // The version of the contact list. "roster_ver":"XXXX14FEXXXXA9ABC52CA86C5DE1601CF729BFD6", // "accept" indicates that the current operation is to accept the contact invitation. "operation":"accept" } ``` When another user accepts the contact invitation from a user, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { // The version of the contact list. "roster_ver": "XXXX718EXXXX3F0C572A5157CFC711D4F6FA490F", // "remote_accept" indicates that the current operation is to accept the contact invitation. "operation": "remote_accept" } ``` ### Decline a contact invitation [#decline-a-contact-invitation] When a user declines the contact invitation from another user, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { // The version of the contact list. "roster_ver":"XXXXEC24XXXX32B2EB1B654AA446930DB9BAFE59", // "decline" indicates that the current operation is to decline the contact invitation. "operation":"decline" } ``` When another user declines the contact invitation from a user, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { // The version of the contact list. "roster_ver": "1BD5718E9C9D3F0C572A5157CFC711D4F6FA490F", // "remote_decline" indicates that the current operation is to decline the contact invitation. "operation": "remote_decline" } ``` ### Add a contact to the blocklist [#add-a-contact-to-the-blocklist] When a user adds a contact to the blocklist, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { // "ban" indicates that the current operation is to add a contact to the blocklist. "operation":"ban", "status": { "error_code":"ok" } } ``` ### Remove a contact from the blocklist [#remove-a-contact-from-the-blocklist] When a user removes a contact from the blocklist, the Chat server sends a callback to your app server. The sample code of the `payload` field is as follows: ```json "payload": { // "allow" indicates that the current operation is to remove a contact from the blocklist. "operation":"allow", "status": { "error_code":"ok" } } ``` ## Receipt events [#receipt-events] When a user sends an receipt, the Chat server sends a callback to your app server. The sample code is as follows: ```json { "chat_type": "read_ack", "callId": "XXXX#XXXX968665325555943556", "security": "bd63XXXX8f72XXXX6d33e09a43aa4239", "payload": { "ext": {}, "ack_message_id": "9686XXXX3572037776", "bodies": [] }, "host": "msync@ebs-ali-beijing-msync45", "appkey": "XXXX#XXXX", "from": "1111", "to": "2222", "eventType": "chat", "msg_id": "9686XXXX5555943556", "timestamp": 1643099771248 } ``` | Field | Data Type | Description | | :---------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chat_type` | String | The type of the event. `read_ack`: Read receipts. `delivery_ack`: Delivery receipts. | | `callId` | String | The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated. | | `security` | String | The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on [Agora Console](https://console.agora.io/v2). | | `payload` | Object | The structure of the callback event that contains the following fields: `ext`: The message extension field. `ack_message_id`: The message ID of the receipt callback. `bodies`: The message body. | | `host` | String | The domain name assigned by the Chat service to access RESTful APIs. | | `appkey` | String | The key of the app. The unique identifier assigned to each app by the Chat service. | | `from` | String | The ID of the user who sends the receipt. | | `to` | String | The ID of the user who receives the receipt. | | `eventType` | String | The message type of the callback. `chat`: Uplink messages. The messages that are about to be sent by the Chat server to end devices. `chat_offline`: Offline messages. The messages that are not sent by the Chat server as the end user is offline. | | `timestamp` | long | The Unix timestamp when the Chat server receives the callback event, in milliseconds. | | `msg_id` | String | The message ID of the receipt. | ## Content moderation result [#content-moderation-result] When the message moderation is complete, the Chat server sends the moderation result to your app server. The sample code is as follows: ```json { "callId": "100220419126072#demo_54ae7e93-xxxx-xxxx-92f5-323e33187243", "moderationResult": "PASS", "providerResult": "PASS", "security": "1f4857f120b2789b7d0abcd372c4f9e8", "messageType": "txt", "messageId": "1F4MX6iSdI7VFnN7Hm0vrcr3Uwr", "targetType": "chat", "appkey": "100220419126072#lydemo", "source": { }, "eventType": "moderation", "from": "qa2", "to": "qa1", "url": "", "msg": "Hello", "timestamp": 1668766253245 } ``` | Parameter | Type | Description | | :----------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `callId` | String | The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated. | | `moderationResult` | String | The message handling result: - `PASS`: Send the message. - `REJECT`: Reject sending the message. - `EXCHANGE`: Replace the sensitive content in the message. - `RECALL`: Recall the voice or video that is sent. | | `providerResult` | String | The message moderation result: - `PASS`: The message does not contain inappropriate content. - `REVIEWED`: The message is suspected of containing inappropriate content. - `REJECT`: The message contains inappropriate content. | | `security` | String | The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of secret can be found on [Agora Console](https://console.agora.io/v2). | | `messageType` | String | The message text: - `txt`: Text message. - `img`: Image message. - `audio`: Voice message. - `video`: Video message. - `custom`: Custom message. | | `messageId` | String | Message ID. | | `targetType` | String | Conversation type: - `chat`: One-to-one chat. - `groupchat`: Group chat. - `chatroom`: Chat room. | | `appkey` | String | The key of the app. The unique identifier assigned to each app by the Chat service. | | `eventType` | String | The event type, which is `moderation` for the moderation service. | | `from` | String | The user ID of the message sender. | | `to` | String | The message recipient: - One-to-one chat: User ID of the message recipient. - Group chat: Group ID. - Chat room: Chat room ID. | | `msg` | String | The content of the text message. This parameter is valid only when `messageType` is `txt`. | | `url` | String | The URL of the attachment message, like a voice, video, or image message. This parameter is valid only when `messageType` is `img`, `audio`, or `video`. | | `timestamp` | Number | The Unix timestamp when the Chat server receives the callback event, in milliseconds. |