Callbacks and events

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.

When a user logs in to or logs out of the Chat app, the Chat server sends a callback to your app server.

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:

_13

{

_13

"callId":"XXXX#XXXXe393c568-5ae5-4a0e-8a2c-008b52b49eed",

_13

"reason":"login",

_13

"security":"XXXXae2eXXXXced298883a0cf06d41b9",

_13

"os":"ios",

_13

"ip":"************",

_13

"host":"*******",

_13

"appkey":"XXXX#XXXX",

_13

"user":"XXXX#XXXXtstXXXX/ios_XXXX01fd-b5a4-84d5-ebeb-bf10XXXX0442",

_13

"version":"3.8.9.1",

_13

"timestamp":1642585154644,

_13

"status":"online"

_13

}

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.
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.

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:

_13

{

_13

"callId":"XXXX#XXXX25b54a81-1376-4669-bb3d-178339a8f11b",

_13

"reason":"logout",

_13

"security":"XXXXd77eXXXXf26801627fdaadca987e",

_13

"os":"ios",

_13

"ip":"223.71.97.198:4XXXX",

_13

"host":"********",

_13

"appkey":"XXXX#XXXX",

_13

"user":"XXXX#XXXXtstXXXX/ios_XXXX0737-db3a-d2b5-da18-b604XXXX195b",

_13

"version":"3.8.9.1",

_13

"timestamp":1642648914742,

_13

"status":"offline"

_13

}

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.
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.

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:

_12

{

_12

"callId":"XXXX#XXXX260ae3eb-ba31-4f01-9a62-8b3b05f3a16c",

_12

"reason":"replaced",

_12

"security":"XXXX00b1XXXX4fe76dbfdc664cbaa76b",

_12

"os":"ios","ip":"223.71.97.198:52709",

_12

"host":"msync@ebs-ali-beijing-msync40",

_12

"appkey":"XXXX#XXXX",

_12

"user":"XXXX#XXXXtst01XXXX/ios_XXXX01fd-b5a4-84d5-ebeb-bf10XXXX0442",

_12

"version":"3.8.9.1",

_12

"timestamp":1642648955563,

_12

"status":"offline"

_12

}

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.
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.

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:

_15

{

_15

"callId":"{appkey}_{uuid}",

_15

"eventType":"chat_offline",

_15

"timestamp":1600060847294,

_15

"chat_type":"groupchat",

_15

"group_id":"1693XXXX238921545",

_15

"from":"user1",

_15

"to":"user2",

_15

"msg_id":"8924XXXX42322",

_15

"payload":{

_15

// The details of the callback.

_15

},

_15

"securityVersion":"1.0.0",

_15

"security":"XXXX2c39XXXX9e7abc83958bcc3156d3"

_15

}

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.
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.

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:

_10

"payload":

_10

{

_10

"ext":{},

_10

"bodies":[

_10

{

_10

"msg":"rr",

_10

"type":"txt"

_10

}

_10

]

_10

}

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.

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:

_18

"payload":

_18

{

_18

"ext":{},

_18

"bodies":[

_18

{

_18

"filename":"image",

_18

"size":

_18

{

_18

"width":746,

_18

"height":1325

_18

},

_18

"secret":"XXXXqnkRXXXXAUHNhFQyIhTJxWxvGOwyx1",

_18

"file_length":118179,

_18

"type":"img",

_18

"url":"https://a1.agora.com/"

_18

}

_18

]

_18

}

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}/{org_name}/{app_name}/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.

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:

_14

"payload":

_14

{

_14

"ext":{},

_14

"bodies":[

_14

{

_14

"filename":"audio",

_14

"length":4,

_14

"secret":"XXXXynkRXXXX1e0Ksmmt2Ym6AzpRr9SxsUpF",

_14

"file_length":6374,

_14

"type":"audio",

_14

"url":"https://a1.agora.com/"

_14

}

_14

]

_14

}

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}/{org_name}/{app_name}/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.

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:

_21

"payload":

_21

{

_21

"ext":{},

_21

"bodies":[

_21

{

_21

"thumb_secret":"t1AEXXXXEeyS81-d10_HOpjSZc8TD-ud40XXXXOStQrr7Mbc",

_21

"filename":"video.mp4",

_21

"size":

_21

{

_21

"width":360,

_21

"height":480

_21

},

_21

"thumb":"https://a1.agora.com/agora-demo/shuang/chatfiles/XXXX0400-7a8b-11ec-8d83-7106XXXX33e6",

_21

"length":10,

_21

"secret":"XXXXgHqLXXXXBfuoalZCJPD7PVcoOu_RHTRa78bjU_KQAPr2",

_21

"file_length":601404,

_21

"type":"video",

_21

"url":"https://a1.agora.com/agora-demo/shuang/chatfiles/XXXX3270-7a8b-11ec-9735-6922XXXXb891"

_21

}

_21

]

_21

}

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}/{org_name}/{app_name}/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}/{org_name}/{app_name}/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.

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:

_12

"payload":

_12

{

_12

"ext":{},

_12

"bodies":[

_12

{

_12

"lng":116.32309156766605,

_12

"type":"loc",

_12

"addr":"********",

_12

"lat":39.96612729238626

_12

}

_12

]

_12

}

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.

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:

_10

"payload":

_10

{

_10

"ext":{},

_10

"bodies":[

_10

{

_10

"msg":"rr",

_10

"type":"cmd"

_10

}

_10

]

_10

}

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.

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:

_12

"payload":

_12

{

_12

"ext":{},

_12

"bodies":[

_12

{

_12

"customExts": [ {"name": 1 } ],

_12

"v2:customExts":{"k":"v","k1":"v1"},

_12

"customEvent": "flower",

_12

"type": "custom"

_12

}

_12

]

_12

}

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<String, String> 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.

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:

_19

{

_19

"chat_type":"recall",

_19

"callId":"orgname#appname_9664XXXX5536657404",

_19

"security":"ea7aXXXX14fbXXXX33d5f4f169eb4f8d",

_19

"payload":

_19

{

_19

"ext":{},

_19

"ack_message_id":"9664XXXX0900644860",

_19

"bodies":[]

_19

},

_19

"host":"******",

_19

"appkey":"orgname#appname",

_19

"from":"tst",

_19

"recall_id":"9664XXXX0900644860",

_19

"to":"1709XXXX2023810",

_19

"eventType":"chat",

_19

"msg_id":"9664XXXX5536657404",

_19

"timestamp":1642589932646

_19

}

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 filed 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.
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.

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:

_16

{

_16

"chat_type": "muc",

_16

"callId": "XXXX#XXXX",

_16

"security": "XXXX",

_16

"payload":{

_16

// The details of the callback.

_16

},

_16

"group_id": "1735XXXX6122369",

_16

"host": "XXXX",

_16

"appkey": "XXXX#XXXX",

_16

"from": "XXXX#XXXX_1111@easemob.com/android_8070d7b2-795eb6e63d",

_16

"to": "1111",

_16

"eventType": "chat",

_16

"msg_id": "9764XXXX3882744164",

_16

"timestamp": 1644914583273

_16

}

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.
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.

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:

_13

"payload":

_13

{

_13

"muc_id": "XXXX#XXXX_173556296122369@conference.easemob.com",

_13

"reason": "",

_13

"is_chatroom": false,

_13

// "create" indicates that the current operation is to create a chat group or chat room.

_13

"operation": "create",

_13

"status":

_13

{

_13

"description":"",

_13

"error_code": "ok"

_13

}

_13

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX_173548612157441@conference.easemob.com",

_12

"reason": "",

_12

"is_chatroom": false,

_12

// "destroy" indicates that the current operation is to destroy a chat group or chat room.

_12

"operation": "destroy",

_12

"status": {

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_14

"payload":

_14

{

_14

"muc_id": "XXXX#XXXX_.com",

_14

// The content of the join request.

_14

"reason": "join group123",

_14

"is_chatroom": false,

_14

// "apply" indicates that the current operation is to send a join request to a chat group or chat room.

_14

"operation": "apply",

_14

"status":

_14

{

_14

"description": "",

_14

"error_code": "ok"

_14

}

_14

}

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:

_13

"payload":

_13

{

_13

"muc_id": "XXXX#XXXX",

_13

"reason": "",

_13

"is_chatroom": false,

_13

// "apply_accept" indicates that the current operation is to accept a join request.

_13

"operation": "apply_accept",

_13

"status":

_13

{

_13

"description": "",

_13

"error_code": "ok"

_13

}

_13

}

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:

_13

"payload":

_13

{

_13

"muc_id": "XXXX#XXXX",

_13

// The content of the group invitation.

_13

"reason": "Hello",

_13

"is_chatroom": false,

_13

// "invite" indicates that the current operation is to send a group invitation to a user.

_13

"operation": "invite",

_13

"status": {

_13

"description": "",

_13

"error_code": "ok"

_13

}

_13

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173549292683265XXXX",

_12

"reason": "",

_12

"is_chatroom": false,

_12

// "invite_accept" indicates that the current operation is to accept a group invitation.

_12

"operation": "invite_accept",

_12

"status": {

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173549292683265XXXX",

_12

"reason": "",

_12

"is_chatroom": false,

_12

// "invite_decline" indicates that the current operation is to decline a group invitation.

_12

"operation": "invite_decline",

_12

"status": {

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173560762007553XXXX",

_12

"is_chatroom": false,

_12

// "presence" indicates that the current operation is to join a chat group or chat room.

_12

"operation": "presence",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173560762007553XXXX",

_12

"is_chatroom": false,

_12

// "leave" indicates that the current operation is to leave a chat room.

_12

"operation": "leave",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173560762007553XXXX",

_12

"is_chatroom": false,

_12

// "absence" indicates the result of leaving a chat group or chat room.

_12

"operation": "absence",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173549292683265XXXX",

_12

"is_chatroom": false,

_12

// "kick" indicates that the current operation is to remove a member from a chat group or chat room.

_12

"operation": "kick",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

When the owner or an admin adds a member to the block 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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173558358671361@conference.easemob.com",

_12

"reason": "",

_12

"is_chatroom": false,

_12

// "ban" indicates that the current operation is to add a member to the block list of a chat group or chat room.

_12

"operation": "ban",

_12

"status": {

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

When the owner or an admin removes a member from the block 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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173549292683265XXXX",

_12

"reason": "undefined",

_12

"is_chatroom": false,

_12

// "allow" indicates that the current operation is to remove a member from the block list of a chat group or chat room.

_12

"operation": "allow",

_12

"status": {

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173549292683265XXXX",

_12

"is_chatroom": false,

_12

// "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.

_12

"operation": "add_user_white_list",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173549292683265XXXX",

_12

"is_chatroom": false,

_12

// "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.

_12

"operation": "remove_user_white_list",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_13

"payload":

_13

{

_13

"muc_id": "XXXX#XXXX173560762007553XXXX",

_13

"reason": "",

_13

"is_chatroom": false,

_13

// "add_mute" indicates that the current operation is to mute a member.

_13

"operation": "add_mute",

_13

"status":

_13

{

_13

"description": "",

_13

"error_code": "ok"

_13

}

_13

}

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:

_13

"payload":

_13

{

_13

"muc_id": "XXXX#XXXX173560762007553XXXX",

_13

"reason": "",

_13

"is_chatroom": false,

_13

// "remove_mute" indicates that the current operation is to unmute a member.

_13

"operation": "remove_mute",

_13

"status":

_13

{

_13

"description": "",

_13

"error_code": "ok"

_13

}

_13

}

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:

_11

"payload":

_11

{

_11

"muc_id": "XXXX#XXXX173560762007553XXXX",

_11

"is_chatroom": false,

_11

// "block" indicates that the current operation is to mute a chat group or chat room.

_11

"operation": "block",

_11

"status": {

_11

"description": "",

_11

"error_code": "ok"

_11

}

_11

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173560762007553XXXX",

_12

"is_chatroom": false,

_12

// "unblock" indicates that the current operation is to unmute a chat group or chat room.

_12

"operation": "unblock",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173553668390913XXXX",

_12

"is_chatroom": false,

_12

// "ban_group" indicates that the current operation is to globally mute a chat group or chat room.

_12

"operation": "ban_group",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173553668390913XXXX",

_12

"is_chatroom": false,

_12

// "remove_ban_group" indicates that the current operation is to globally unmute a chat group or chat room.

_12

"operation": "remove_ban_group",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173560762007553XXXX",

_12

"is_chatroom": false,

_12

// "assing_owner" indicates that the current operation is to transfer the ownership of a chat group or chat room.

_12

"operation": "assing_owner",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173560762007553XXXX",

_12

"is_chatroom": false,

_12

// "add_admin" indicates that the current operation is to promote a member to an admin.

_12

"operation": "add_admin",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173560762007553XXXX",

_12

"is_chatroom": false,

_12

// "remove_admin" indicates that the current operation is to demote an admin to a member.

_12

"operation": "remove_admin",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_12

"payload":

_12

{

_12

"muc_id": "XXXX#XXXX173549200408577XXXX",

_12

"is_chatroom": false,

_12

// "update" indicates that the current operation is to update the information about a chat group or chat room.

_12

"operation": "update",

_12

"status":

_12

{

_12

"description": "",

_12

"error_code": "ok"

_12

}

_12

}

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:

_14

"payload":

_14

{

_14

"muc_id": "XXXX#XXXX173560762007553XXXX",

_14

// The updated announcement.

_14

"reason": "gogngao",

_14

"is_chatroom": false,

_14

// "update_announcement" indicates that the current operation is to update the announcement of a chat group or chat room.

_14

"operation": "update_announcement",

_14

"status":

_14

{

_14

"description": "",

_14

"error_code": "ok"

_14

}

_14

}

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:

_14

"payload":

_14

{

_14

"muc_id": "XXXX#XXXX173560762007553XXXX",

_14

// The deleted announcement, which is empty.

_14

"reason": "",

_14

"is_chatroom": false,

_14

// "delete_announcement" indicates that the current operation is to delete the announcement of a chat group or chat room.

_14

"operation": "delete_announcement",

_14

"status":

_14

{

_14

"description": "",

_14

"error_code": "ok"

_14

}

_14

}

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:

_21

"payload":

_21

{

_21

"muc_id": "XXXX#XXXX173560762007553XXXX",

_21

"reason": "{

_21

\"data\":{

_21

\"file_id\":\"79ddf840-8e2f-11ec-bec3-ad40868b03f9\",

_21

\"file_name\":\"a.csv\",

_21

\"file_owner\":\"@ppAdmin\",

_21

\"file_size\":6787,

_21

\"created\":1644909510085

_21

}

_21

}",

_21

"is_chatroom": false,

_21

// "upload_file" indicates that the current operation is to upload a shared file to a chat group.

_21

"operation": "upload_file",

_21

"status":

_21

{

_21

"description": "",

_21

"error_code": "ok"

_21

}

_21

}

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.

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:

_14

"payload":

_14

{

_14

"muc_id": "XXXX#XXXX173549292683265XXXX",

_14

// "reason" specifies the ID of the shared file to delete. This ID is the same as the "file_id" used when uploading the file.

_14

"reason": "79ddf840-8e2f-11ec-bec3-ad40868b03f9",

_14

"is_chatroom": false,

_14

// "delete_file" indicates that the current operation is to delete a shared file in a chat group.

_14

"operation": "delete_file",

_14

"status":

_14

{

_14

"description": "",

_14

"error_code": "ok"

_14

}

_14

}

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:

_15

{

_15

"chat_type": "roster",

_15

"callId": "orgname#appname_9664XXXX5536657404",

_15

"security": "XXXXa9feXXXX69241e17b15e2783dbb1",

_15

"payload": {

_15

// The details of the callback.

_15

},

_15

"host": "msync@ebs-ali-beijing-msync26",

_15

"appkey":"orgname#appname",

_15

"from":"tst",

_15

"to":"tst01",

_15

"eventType":"chat",

_15

"msg_id":"9664XXXX5536657404",

_15

"timestamp":1642589932646

_15

}

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.
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.

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:

_6

"payload":

_6

{

_6

"reason":"",

_6

// "add" indicates that the current operation is to add a contact.

_6

"operation":"add"

_6

}

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:

_7

"payload":

_7

{

_7

// The version of the contact list.

_7

"roster_ver":"XXXXD920XXXX5B51EB0B806E83BDD97F089B0092",

_7

// "remove" indicates that the current operation is to remove a contact.

_7

"operation":"remove"

_7

}

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:

_7

"payload":

_7

{

_7

// The version of the contact list.

_7

"roster_ver":"XXXX14FEXXXXA9ABC52CA86C5DE1601CF729BFD6",

_7

// "accept" indicates that the current operation is to accept the contact invitation.

_7

"operation":"accept"

_7

}

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:

_6

"payload": {

_6

// The version of the contact list.

_6

"roster_ver": "XXXX718EXXXX3F0C572A5157CFC711D4F6FA490F",

_6

// "remote_accept" indicates that the current operation is to accept the contact invitation.

_6

"operation": "remote_accept"

_6

}

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:

_7

"payload":

_7

{

_7

// The version of the contact list.

_7

"roster_ver":"XXXXEC24XXXX32B2EB1B654AA446930DB9BAFE59",

_7

// "decline" indicates that the current operation is to decline the contact invitation.

_7

"operation":"decline"

_7

}

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:

_6

"payload": {

_6

// The version of the contact list.

_6

"roster_ver": "1BD5718E9C9D3F0C572A5157CFC711D4F6FA490F",

_6

// "remote_decline" indicates that the current operation is to decline the contact invitation.

_6

"operation": "remote_decline"

_6

}

When a user adds a contact to the block list, the Chat server sends a callback to your app server. The sample code of the payload field is as follows:

_9

"payload":

_9

{

_9

// "ban" indicates that the current operation is to add a contact to the block list.

_9

"operation":"ban",

_9

"status":

_9

{

_9

"error_code":"ok"

_9

}

_9

}

When a user removes a contact from the block list, the Chat server sends a callback to your app server. The sample code of the payload field is as follows:

_9

"payload":

_9

{

_9

// "allow" indicates that the current operation is to remove a contact from the block list.

_9

"operation":"allow",

_9

"status":

_9

{

_9

"error_code":"ok"

_9

}

_9

}

When a user sends an receipt, the Chat server sends a callback to your app server. The sample code is as follows:

_17

{

_17

"chat_type": "read_ack",

_17

"callId": "XXXX#XXXX968665325555943556",

_17

"security": "bd63XXXX8f72XXXX6d33e09a43aa4239",

_17

"payload": {

_17

"ext": {},

_17

"ack_message_id": "9686XXXX3572037776",

_17

"bodies": []

_17

},

_17

"host": "msync@ebs-ali-beijing-msync45",

_17

"appkey": "XXXX#XXXX",

_17

"from": "1111",

_17

"to": "2222",

_17

"eventType": "chat",

_17

"msg_id": "9686XXXX5555943556",

_17

"timestamp": 1643099771248

_17

}

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.
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.

When the message moderation is complete, the Chat server sends the moderation result to your app server.

The sample code is as follows:

_19

{

_19

"callId": "100220419126072#demo_54ae7e93-xxxx-xxxx-92f5-323e33187243",

_19

"moderationResult": "PASS",

_19

"providerResult": "PASS",

_19

"security": "1f4857f120b2789b7d0abcd372c4f9e8",

_19

"messageType": "txt",

_19

"messageId": "1F4MX6iSdI7VFnN7Hm0vrcr3Uwr",

_19

"targetType": "chat",

_19

"appkey": "100220419126072#lydemo",

_19

"source": {

_19

_19

},

_19

"eventType": "moderation",

_19

"from": "qa2",

_19

"to": "qa1",

_19

"url": "",

_19

"msg": "Hello",

_19

"timestamp": 1668766253245

_19

}

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.
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.<br/> - groupchat: Group chat.<br/> - 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.