Skip to main content

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.

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

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
}

FieldData TypeDescription
callIdStringThe 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.
reasonStringThe reason that triggers the callback. login indicates that a user logs in to the app.
securityStringThe 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.
osStringThe operating system of the device. Valid values: ios, android, linux, win, and other.
ipStringThe IP address of the user who logs in to the app.
hostStringThe domain name assigned by the Chat service to access RESTful APIs.
appkeyStringThe key of the app. The unique identifier assigned to each app by the Chat service.
userStringThe ID of the user. The unique identifier of each user in the Chat app, in the format of {appKey}/{OS}_{deviceId}.
versionStringThe version of the Chat SDK.
timestampLongThe Unix timestamp when the Chat server receives the login request, in milliseconds.
statusStringThe current status of the user. online indicates that the user is online.

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:


_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
}

FieldData TypeDescription
callIdStringThe 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.
reasonStringThe reason that triggers the callback. logout indicates that a user logs out of the app.
securityStringThe 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.
osStringThe operating system of the device. Valid values: ios, android, linux, win, and other.
ipStringThe IP address of the user who logs out of the app.
hostStringThe domain name assigned by the Chat service to access RESTful APIs.
appkeyStringThe key of the app. The unique identifier assigned to each app by the Chat service.
userStringThe ID of the user. The unique identifier of each user in the Chat app, in the format of {appKey}/{OS}_{deviceId}.
versionStringThe version of the Chat SDK.
timestampLongThe Unix timestamp when the Chat server receives the logout request, in milliseconds.
statusStringThe current status of the user. offline indicates that the user is offline.

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:


_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
}

FieldData TypeDescription
callIdStringThe 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.
reasonStringThe reason that triggers the callback. replaced indicates that a user logs out of the app due to being kicked out by another device.
securityStringThe 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.
osStringThe operating system of the device. Valid values: ios, android, linux, win, and other.
ipStringThe IP address of the user.
hostStringThe domain name assigned by the Chat service to access RESTful APIs.
appkeyStringThe key of the app. The unique identifier assigned to each app by the Chat service.
userStringThe ID of the user. The unique identifier of each user in the Chat app, in the format of {appKey}/{OS}_{deviceId}.
versionStringThe version of the Chat SDK.
timestampLongThe Unix timestamp when the Chat server receives the logout request, in milliseconds.
statusStringThe current status of the user. offline indicates that the user is offline.

Message events

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:


_15
{
_15
"callId":"{appkey}_{file_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
}

FieldData TypeDescription
callIdStringThe 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.
eventTypeStringThe 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.
timestampLongThe Unix timestamp when the Chat server receives the callback event, in milliseconds.
chat_typeStringThe type of chat.
  • chat: One-to-one chats.
  • groupchat: Chat groups and chat rooms.
group_idStringThe ID of the chat group or chat room where the message is sent. This field only exists if chat_type is set to groupchat.
fromStringThe sender of the message.
toStringThe recipient of the message.
msg_idStringThe message ID of the callback event. This ID is the same as the msg_id when the message is sent.
payloadObjectThe 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.
securityVersionStringThis parameter is reserved for future use.
securityStringThe 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.
appkeyStringThe key of the app. The unique identifier assigned to each app by the Chat service.
hostStringThe domain name assigned by the Chat service to access RESTful APIs.

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:


_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:

FieldData TypeDescription
msgStringThe content of the text message.
typeStringThe type of the message. txt indicates a text 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:


_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:

FieldData TypeDescription
filenameStringThe filename of the image.
secretStringThe secret returned after uploading the image file.
sizeJsonThe dimension of the image in pixels.
  • height: The height of the image.
  • width: The width of the image.
file_lengthIntThe size of the image in bytes.
urlStringThe 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.
typeStringThe type of the message. img indicates an image 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:


_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:

FieldData TypeDescription
filenameStringThe filename of the audio.
secretStringThe secret returned after uploading the audio file.
file_lengthLongThe size of the audio file in bytes.
lengthIntThe duration of the audio file in seconds.
urlStringThe 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.
typeStringThe type of the message. audio indicates an audio 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:


_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:

FieldData TypeDescription
thumb_secretStringThe secret returned after uploading the video thumbnail.
filenameStringThe filename of the video.
sizeJsonThe dimension of the video thumbnail.
  • height: The height of the thumbnail.
  • width: The width of the thumbnail.
thumbStringThe 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.
secretStringThe secret returned after uploading the video file.
file_lengthLongThe size of the video file in bytes.
urlStringThe 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.
typeStringThe type of the message. video indicates a video 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:


_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:

FieldData TypeDescription
logStringThe longitude of the location.
latStringThe latitude of the location.
addrStringThe address of the location.
typeStringThe type of the message. loc indicates a location 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:


_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:

FieldData TypeDescription
msgStringThe content of the command message.
typeStringThe type of the message. cmd indicates a command 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:


_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:

FieldData TypeDescription
customExts/v2:customExtsJsonThe attribute of the custom event, in the Map<String, String> format. The attribute can contain a maximum of 16 elements.
customEventStringThe type of the custom event. The type can be 1 to 32 characters.
typeStringThe type of the message. custom indicates a custom 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:


_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
}

FieldData TypeDescription
callIdStringThe 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.
eventTypeStringThe 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.
timestampLongThe Unix timestamp when the Chat server receives the callback event, in milliseconds.
chat_typeStringThe type of chat.
  • chat: One-to-one chats.
  • groupchat: Chat groups and chat rooms.
group_idStringThe ID of the chat group or chat room where the message resides. This field only exists if chat_type is set to groupchat.
fromStringThe sender of the message.
toStringThe recipient of the message.
recall_idStringThe ID of the message to recall.
msg_idStringThe message ID of the callback event. This ID is the same as the msg_id when the end user sends the message.
payloadObjectThe 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.
securityVersionStringThis parameter is reserved for future use.
securityStringThe 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.
appkeyStringThe key of the app. The unique identifier assigned to each app by the Chat service.
hostStringThe domain name assigned by the Chat service to access RESTful APIs.

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:


_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
}

FieldData TypeDescription
chat_typeStringThe type of the event. muc indicates a chat group or a chat room.
callIdStringThe 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.
eventTypeStringThe 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.
timestampLongThe Unix timestamp when the Chat server receives the callback event, in milliseconds.
group_idStringThe ID of the chat group or chat room where the message resides. This field only exists if chat_type is set to groupchat.
fromStringThe sender of the message.
toStringThe recipient of the message.
msg_idStringThe message ID of the callback event. This ID is the same as the msg_id when sending the message.
payloadObjectThe 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.
securityVersionStringThis parameter is reserved for future use.
securityStringThe 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.
appkeyStringThe key of the app. The unique identifier assigned to each app by the Chat service.
hostStringThe domain name assigned by the Chat service to access RESTful APIs.

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

Add a member to the block list of a chat group or chat room

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
}

Remove a member from the block list of a chat group or chat room

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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


_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
}

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:


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

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:


_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
}

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:


_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
}

FieldData TypeDescription
chat_typeStringThe type of the event. roster indicates an event occurred in user contacts.
callIdStringThe 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.
eventTypeStringThe 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.
timestampLongThe Unix timestamp when the Chat server receives the callback event, in milliseconds.
fromStringThe user who operates the contact.
toStringThe contact who is operated by the user.
msg_idStringThe message ID of the callback event. This ID is the same as the msg_id when sending the message.
payloadObjectThe structure of the callback event. See payload example below for details.
securityStringThe 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.
appkeyStringThe key of the app. The unique identifier assigned to each app by the Chat service.
hostStringThe domain name assigned by the Chat service to access RESTful APIs.

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:


_6
"payload":
_6
{
_6
"reason":"",
_6
// "add" indicates that the current operation is to add a contact.
_6
"operation":"add"
_6
}

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:


_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
}

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:


_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
}

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:


_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
}

Add a contact to the block list

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
}

Remove a contact from the block list

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
}

Receipt events

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
}

FieldData TypeDescription
chat_typeStringThe type of the event.
  • read_ack: Read receipts.
  • delivery_ack: Delivery receipts.
callIdStringThe 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.
securityStringThe 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.
payloadObjectThe 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.
hostStringThe domain name assigned by the Chat service to access RESTful APIs.
appkeyStringThe key of the app. The unique identifier assigned to each app by the Chat service.
fromStringThe ID of the user who sends the receipt.
toStringThe ID of the user who receives the receipt.
eventTypeStringThe 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.
timestamplongThe Unix timestamp when the Chat server receives the callback event, in milliseconds.
msg_idStringThe message ID of the receipt.