Chat Room Management | AgoraChat Documentation Beta

Edit me

Chat provides a Platform API to manage chat rooms in APP.

There is a limit on the number of chat rooms that can be created for a single APP, if you need to increase it, you can contact the business to resolve it according to your specific business. Only 500 chat rooms can be added to a single user ID.

Chat Room Data Structure

Name	Type	Description
id	String	Chat room ID, a unique identifier for the chat room, generated by the Chat server.
name	String	The name of the chat room, any string.
description	String	Description of the chat room, any string.
maxusers	Integer	Chat room membership limit, set when creating a chat room, can be modified. Default value 200, maximum 5000.
affiliations_count	Integer	Total number of current members.
affiliations	Array	A list of existing members, including owner and member.
owner	String	The username of the chat room creator. e.g.{"owner": "13800138001"}.
member	String	The username of the chat room member. e.g. {"member":"xc6xrnbzci"}.

Chat Room Roles

In addition to chat room creator (owner) and general chat room members, a new chat room administrator role has been added.

Chat room roles have a range of permissions: creator > chat room administrator > general chat room member

The chat room creator has all chat room permissions
The chat room administrator has permissions to add/remove blacklists, add/remove bans, etc.
Creators + Administrators 100 in total, i.e. Administrators can add up to 99

Platform API online testing instructions

The Platform API used in the IM chat room integration process The documentation details the Platform APIs that need to be used for IM chat room integration, which can be found by using the Platform API embedded in the documentation.

Managing Chat Rooms

Chat provides several interfaces to complete chat room related integrations, including the ability to create, fetch, modify, delete and other management functions for chat rooms.

Name	Request	Description
Get all chat rooms in the APP	/{org_name}/{app_name}/chatrooms	Get all the chat room information under the application
Get the chat rooms users have joined	/{org_name}/{app_name}/users/{username}/joined_chatrooms	Get all the chat rooms this user has joined by user name
Get chat room details	/{org_name}/{app_name}/chatrooms/{chatroom_id}	Get the details of this chat room based on the chat room ID
Create a chat room	/{org_name}/{app_name}/chatrooms	Create a new chat room
Modify chat room information	/{org_name}/{app_name}/chatrooms/{chatroom_id}	Modify some of the information in the chat room
Delete Chat Room	/{org_name}/{app_name}/chatrooms/{chatroom_id}	Delete a chat room

Get all the chat rooms in the APP

Interface to get information about all chat rooms under the app

HTTP Request

GET	/{org_name}/{app_name}/chatrooms

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

View the information contained in the data field in the return value.

Parameter	Description
id	Chat room ID, a unique identifier for the chat room, generated by the Chat server.
name	The name of the chat room, any string.
owner	The username of the creator of the chat room. e.g. {"owner": "user1"}.
affiliations_count	Total number of existing chat room members.

Request Example

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easecdn.com/chat-demo/testapp/chatrooms'

Examples of possible returned results

Returns a value of 200, indicating that the chat room acquisition was successful

{
  "action": "get",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms",
  "entities": [],
  "data": [
    {
      "id": "66211860774913",
      "name": "testchatroom1",
      "owner": "user1",
      "affiliations_count": 2
    },
    {
      "id": "66211882795010",
      "name": "testchatroom2",
      "owner": "user2",
      "affiliations_count": 2
    }
  ],
  "timestamp": 1542543050037,
  "duration": 0,
  "organization": "chat-demo",
  "applicationName": "testapp",
  "count": 2
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542543133343,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx , it may mean that the interface is flow-limited, please pause slightly and retry. See interface flow restriction instructions for details

Testing online with Platform API

Get the chat rooms a user has joined

Get all the chat rooms a user has joined based on the user’s name

HTTP Request

GET	/{org_name}/{app_name}/users/{username}/joined_chatrooms

You need to fill in {username} in the request, you need to set the IM user name obtained

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

View the information contained in the data field in the return value.

Parameter	Description
id	Chat room ID, a unique identifier for the chat room, generated by the Chat server.
name	The name of the chat room, any string.

Request Example

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easecdn.com/chat-demo/testapp/users/user1/joined_chatrooms'

Examples of possible returned results

Returns a value of 200, indicating a successful chat room acquisition

{
  "action": "get",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easecdn.com/chat-demo/testapp/users/user1/joined_chatrooms",
  "entities": [],
  "data": [
    {
      "id": "66211860774913",
      "name": "testchatroom1"
    },
    {
      "id": "66211882795010",
      "name": "testchatroom2"
    }
  ],
  "timestamp": 1542543479121,
  "duration": 0,
  "organization": "chat-demo",
  "applicationName": "testapp",
  "count": 2
}

Return value 404, this user does not exist

{
  "error": "resource_not_found",
  "timestamp": 1542543527326,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "username user10 doesn't exist!"
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542543599009,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx , it may mean that the interface is flow-limited, please pause slightly and retry. See interface flow restriction instructions for details

Testing online with Platform API

Get chat room details

You can fetch the details of one or more chat rooms. When fetching the details of multiple chatrooms, the details of all existing chatrooms are returned, while for non-existent chatrooms the response body returns “chatroom id doesn’t exist”.

HTTP Request

GET	/{org_name}/{app_name}/chatrooms/{chatroom_id}

You need to fill in the request with {chatroom_id}, the chatroom ID you need to get.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

View the information contained in the data field in the return value

Parameter	Description
id	Chat room ID, a unique identifier for the chat room, generated by the Chat server.
name	The name of the chat room, any string.
description	Description of the chat room, any string.
membersonly	Does the group owner or group administrator need to approve joining the chat room. true: yes, false: no.
allowinvites	Whether to allow chatroom members to invite people to join this chatroom. true: allows chatroom members to invite people to join this chatroom, false: only the chatroom administrator can add people to the chatroom.
maxusers	Chat room membership limit, set when creating a chat room, can be modified.
owner	The username of the chat room creator. e.g. {"owner": "user1"}.
member	The username of the chat room member. e.g. {"member": "user2"}.
affiliations_count	Total number of existing chat room members.
affiliations	A list of existing members, containing owner and member. e.g. "affiliations":[{"owner": "user1"},{"member":"user2"},{"member":"user3"}].

Example request

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/66211860774913'

Examples of possible returned results

Returns a value of 200, indicating that the chat room details were obtained successfully

{
  "action": "get",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/66211860774913",
  "entities": [],
  "data": [
    {
      "id": "66211860774913",
      "name": "testchatroom1",
      "description": "test",
      "membersonly": false,
      "allowinvites": false,
      "maxusers": 200,
      "owner": "user1",
      "created": 1542542951527,
      "custom": "",
      "affiliations_count": 2,
      "affiliations": [
        {
          "member": "user2"
        },
        {
          "owner": "user1"
        }
      ],
      "public": true
    }
  ],
  "timestamp": 1542543844873,
  "duration": 0,
  "organization": "chat-demo",
  "applicationName": "testapp",
  "count": 1
}

Return value 404, this chat ID does not exist

{
  "error": "service_resource_not_found",
  "timestamp": 1542543915642,
  "duration": 0,
  "exception": "com.easemob.group.exception.ServiceResourceNotFoundException",
  "error_description": "do not find this group:6621186077491"
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542543956477,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx , it may mean that the interface is flow-limited, please pause slightly and retry. See interface flow restriction instructions for details

Testing online with Platform API

Create a chat room

Create a chat room and set the chat room name, chat room description, public/private chat room properties, maximum number of chat room members (including administrators), whether approval is required to join the public chat room, administrators, and chat room members.

HTTP Request

POST	/{org_name}/{app_name}/chatrooms

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

Parameter	Description
name	The name of the chat room, this attribute is required
description	Chat room description, this attribute is required
maxusers	Maximum number of chat room members (including chat room creators), the value is of type Numeric, the default value is 200, the maximum value is 5000, this attribute is optional
owner	Administrator of the chat room, this attribute is required
members	Chat room members, this property is optional, but if added, at least one of the array elements

Response Body

View the information contained in the data field in the return value.

Parameter	Description
id	The ID of the chat room created

Request Example

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' -d '{ 
   "name": "testchatroom1",  
   "description": "test",  
   "maxusers": 300,  
   "owner": "user1",  
   "members": [  
     "user2"  
   ]  
 }' 'http://a1.easecdn.com/chat-demo/testapp/chatrooms'

Examples of possible returned results

Returns a value of 200, indicating that the chat room was created successfully

{
  "action": "post",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms",
  "entities": [],
  "data": {
    "id": "66213271109633"
  },
  "timestamp": 1542544296075,
  "duration": 0,
  "organization": "chat-demo",
  "applicationName": "testapp"
}

Returns 404, the chat room administrator or member does not exist

{
  "error": "resource_not_found",
  "timestamp": 1542544372951,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "username user10 doesn't exist!"
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542544470520,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx , it may mean that the interface is flow-limited, please pause slightly and retry. See interface flow restriction instructions for details

Testing online with Platform API

Modify chat room information

The request body only receives name, description, maxusers attributes. Passing other fields, or fields that cannot be modified, will throw an exception. If the chat room does not exist, an error is returned.

HTTP Request

PUT	/{org_name}/{app_name}/chatrooms/{chatroom_id}

You need to fill in {chatroom_id}, the chatroom ID that needs to be modified, when you request it.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

Parameter	Description
name	Chat room name, the value cannot contain a slash ("/") when modified
description	Chat room description, the value cannot contain a slash ("/") when modified
maxusers	Maximum number of chat room members (including chat room creator), value is of type numeric

Response Body

View the information contained in the data field in the return value

Parameter	Description
groupname	The name of the chat room, true means the modification was successful, false means the modification failed
description	Description of the chat room, true means the modification was successful, false means the modification failed
maxusers	Maximum number of chat room members (including chat room creator), true means the modification was successful, false means the modification failed

Request Example

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' -d '{  
   "name": "testchatroom",  
   "description": "test",  
   "maxusers": 300  
 }' 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/66211860774913'

Examples of possible returned results

Returns a value of 200, indicating that the chat room information was modified successfully

{
  "action": "put",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/66211860774913",
  "entities": [],
  "data": {
    "description": true,
    "maxusers": true,
    "groupname": true
  },
  "timestamp": 1542544817352,
  "duration": 69,
  "organization": "chat-demo",
  "applicationName": "testapp"
}

Returns 403, indicating that the maximum number of modified members does not meet the requirement

{
  "error": "forbidden_op",
  "timestamp": 1542544871049,
  "duration": 0,
  "exception": "com.easemob.group.exception.ForbiddenOpException",
  "error_description": "current user count is larger than the maxUsers that you want to update !"
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542544961403,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx , it may mean that the interface is flow-limited, please pause slightly and retry. See interface flow restriction instructions for details

Testing online with Platform API

Deleting a Chat Room

Deletes a single chat room. If the deleted chat room does not exist, an error is returned.

HTTP Request

DELETE	/{org_name}/{app_name}/chatrooms/{chatroom_id}

You need to fill in the request with {chatroom_id}, the ID of the chatroom that needs to be deleted.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Example

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/66211860774913'

Examples of possible returned results

Returns a value of 200, indicating successful deletion of the chat room

{
  "action": "delete",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/66211860774913",
  "entities": [],
  "data": {
    "success": true,
    "id": "66211860774913"
  },
  "timestamp": 1542545100474,
  "duration": 0,
  "organization": "chat-demo",
  "applicationName": "testapp"
}

Returns a value of 404, indicating that the chat room ID does not exist

{
  "error": "resource_not_found",
  "timestamp": 1542545148716,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "grpID 6621186077491 does not exist!"
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542545181581,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx , it may mean that the interface is flow-limited, please pause slightly and retry. See interface flow restriction instructions for details

Testing online with Platform API

Manage Chat Room Members

Chat provides multiple interfaces to manage chat room members, including adding and removing chat room member relationship lists

Name	Request	Description
Paging to get chat room members	/{org_name}/{app_name}/chatrooms/{chatroom_id}/users	Paging to get a list of members of a chat room
Adding individual chat room members	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}	Adding Users to the Chat Room Member List
Add chat room members'	/{org_name}/{app_name}/chatrooms/{chatroomid}/users	Add users' to chat room member list
Deleting individual chat room members	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}	Remove a user from the list of chat room members
Delete chat room members'	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{usernames}	Delete users' from the list of chat room members
Get a list of chat room administrators	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin	Get a list of chat room administrators
Add Chat Room Administrator	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin	Add users to the chat room administrator list
Remove chat room administrator	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin/{oldadmin}	Remove users from the chat room administrator list

Paging Chat Room Members

Interface to paginate the list of chat room members.

HTTP Request

GET	/{org_name}/{app_name}/chatrooms/{chatroom_id}/users

You need to fill in {chatroom_id}, the chatroom ID you need to get, when you request it

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

Parameter	Description
member	Chat Room Member ID

Request Example

curl -X GET 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/users?pagenum=2&pagesize=2' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Examples of possible returned results

Returns a value of 200, indicating success in getting chat room members

{
    "action": "get",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "params": {
        "pagesize": ["2"],
        "pagenum": ["2"]
    },
    "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/users",
    "entities": [],
    "data": [{
        "member": "user1"
    },
    {
        "member": "user2"
    }],
    "timestamp": 1489074511416,
    "duration": 0,
    "organization": "chat-demo",
    "applicationName": "testapp",
    "count": 2
}

If the return result is 429, 503 or other 5xx , it may mean that the interface is flow-limited, please pause slightly and retry. See interface flow restriction instructions for details

Testing online with Platform API

Adding Individual Chat Room Members

Adding a member to a chat room one at a time does not add the same member repeatedly. If the user is already a member of the chat room, the addition will fail and an error will be returned.

HTTP Request

POST	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}

You need to fill in the request with {chatroomid}, the ID of the chatroom you want to add and {username}, the IM username to be added.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

View the information contained in the data field in the return value

Parameter	Description
result	Add result, true means add success, false means add failure
action	The action to perform, add_member means add a member to the chat room
id	Chat room ID, a unique identifier for the chat room, generated by the Chat server
user	Users added to the chat room

Request Example

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/66213271109633/users/user1'

Examples of possible returned results

Returns a value of 200, indicating that the chat room member was added successfully

{
  "action": "post",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/66213271109633/users/user1",
  "entities": [],
  "data": {
    "result": true,
    "action": "add_member",
    "id": "66213271109633",
    "user": "user1"
  },
  "timestamp": 1542554038353,
  "duration": 0,
  "organization": "chat-demo",
  "applicationName": "testapp"
}

Returns a value of 404, indicating that the added user or chat room does not exist

{
  "error": "resource_not_found",
  "timestamp": 1542554114398,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "username user10 doesn't exist!"
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542554229364,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx , it may mean that the interface is flow-limited, please pause slightly and retry. See interface flow restriction instructions for details

Testing online with Platform API

Add chat room members’

Add multiple users to the chat room, up to 60 users at a time.

HTTP Request

POST	/{org_name}/{app_name}/chatrooms/{chatroomid}/users

You need to fill in the request with {chatroomid}, the ID of the chatroom you want to add and {username}, the IM username to be added.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

Parameter	Description
usernames	Added user name

Response Body

View the information contained in the data field in the return value

Parameter	Description
usernames	Added user name

Request Example

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' -d '{  
   "usernames": [  
     "user1","user2"  
   ]  
 }' 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/66213271109633/users'

Examples of possible returned results

Returns a value of 200, indicating that the chat room member was added successfully

{
  "action": "post",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/66213271109633/users",
  "entities": [],
  "data": {
    "newmembers": [
      "user1",
      "user2"
    ],
    "action": "add_member",
    "id": "66213271109633"
  },
  "timestamp": 1542554537237,
  "duration": 9,
  "organization": "chat-demo",
  "applicationName": "testapp"
}

Returns a value of 404, indicating that the added user or chat room does not exist

{
  "error": "resource_not_found",
  "timestamp": 1542554590006,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "grpID 6621327110963 does not exist!"
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542554611900,
  "duration": 1,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx , it may mean that the interface is flow-limited, please pause slightly and retry. See interface flow restriction instructions for details

Testing online with Platform API

Deleting a single chat room member

Deletes a member from a chat room. If the deleted user is not in the chat room, or if the chat room does not exist, an error will be returned.

HTTP Request

DELETE	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}

You need to fill in {username} corresponding to the IM username that needs to be deleted when requesting.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Example

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/66213271109633/users/user1'

Examples of possible returned results

Returns a value of 200, indicating that the chat room member was deleted successfully

{
  "action": "delete",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/66213271109633/users/user1",
  "entities": [],
  "data": {
    "result": true,
    "action": "remove_member",
    "user": "user1",
    "id": "66213271109633"
  },
  "timestamp": 1542555744726,
  "duration": 1,
  "organization": "chat-demo",
  "applicationName": "testapp"
}

Returns a value of 404, indicating that the chat room ID does not exist

{
  "error": "resource_not_found",
  "timestamp": 1542555822284,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "grpID 6621327110963 does not exist!"
}

Returns a value of 403, indicating that the deleted user does not exist

{
  "error": "resource_not_found",
  "timestamp": 1542555822284,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "grpID 6621327110963 does not exist!"
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542555910183,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx , it may mean that the interface is flow-limited, please pause slightly and retry. See interface flow restriction instructions for details

Testing online with Platform API

Delete Chat Room Members’

Deletes multiple members from a chat room. If the deleted user is not in the chat room, or if the chat room does not exist, an error will be returned.

Pass up to 100 Chat letter ids at a time.

HTTP Request

DELETE	/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{usernames}

You need to fill in {usernames} corresponding to the IM user name that needs to be deleted during the request.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Example

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/66213271109633/users/user1%2Cuser2'

Examples of possible returned results

Returns a value of 200, indicating that the chat room member was deleted successfully

{
  "action": "delete",
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",
  "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/66213271109633/users/user1%2Cuser2",
  "entities": [],
  "data": [
    {
      "result": false,
      "action": "remove_member",
      "reason": "user: user1 doesn't exist in group: 66213271109633",
      "user": "user1",
      "id": "66213271109633"
    },
    {
      "result": true,
      "action": "remove_member",
      "user": "user2",
      "id": "66213271109633"
    }
  ],
  "timestamp": 1542556177147,
  "duration": 0,
  "organization": "chat-demo",
  "applicationName": "testapp"
}

Returns a value of 404, indicating that the chat room ID does not exist

{
  "error": "resource_not_found",
  "timestamp": 1542556220010,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "grpID 6621327110963 does not exist!"
}

Returns a value of 403, indicating that the deleted user does not exist

{
  "error": "forbidden_op",
  "timestamp": 1542556235498,
  "duration": 0,
  "exception": "com.easemob.group.exception.ForbiddenOpException",
  "error_description": "users [user10, user2] are not members of this group!"
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542556279096,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx , it may mean that the interface is flow-limited, please pause slightly and retry. See interface flow restriction instructions for details

Testing online with Platform API

Get the list of chat room administrators

Interface to get the list of chat room administrators.

HTTP Request

GET	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin

You need to fill in {chatroom_id}, the chatroom ID you need to get, when you request it.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

View the information contained in the data field in the return value

Parameter	Description
data	Chat Room Administrator User ID

Request Example

curl -X GET 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/admin' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Examples of possible returned results

Returns a value of 200, indicating success in obtaining a chat room administrator

{
    "action": "get",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/admin",
    "entities": [],
    "data": ["user1"],
    "timestamp": 1489073361210,
    "duration": 0,
    "organization": "chat-demo",
    "applicationName": "testapp",
    "count": 1
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

[Online testing using the Platform API]

Adding a Chat Room Administrator

Promotes a chat room member role to a chat room administrator.

HTTP Request

POST	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin

You need to fill in {chatroom_id} when requesting the chatroom ID of the administrator.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

Parameter	Description
newadmin	User ID to add as chat room administrator

Response Body

Parameter	Description
result	Operation result; success: added successfully
newadmin	User ID added as chat room administrator

Request Example

curl -X POST 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/admin' -d '{"newadmin":"user1"}' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Examples of possible results returned

Returns a value of 200, indicating that adding a chat room administrator was successful

{
    "action": "post",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/admin",
    "entities": [],
    "data": {
        "result": "success",
        "newadmin": "user1"
    },
    "timestamp": 1489073130083,
    "duration": 1,
    "organization": "chat-demo",
    "applicationName": "testapp"
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

[Online testing using the Platform API]

Remove Chat Room Administrator

Downgrades the user’s role from chat room administrator to regular chat room member.

HTTP Request

DELETE	/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin/{oldadmin}

You need to fill in the request with {chatroom_id}, the chatroom ID of the administrator to be removed and {oldadmin}, the username of the administrator to be removed.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Example

curl -X DELETE 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/admin/user1' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Examples of possible results returned

Returns a value of 200, indicating successful removal by the chat room administrator

{
    "action": "delete",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/admin/user1",
    "entities": [],
    "data": {
        "result": "success",
        "oldadmin": "user1"
    },
    "timestamp": 1489073432732,
    "duration": 1,
    "organization": "chat-demo",
    "applicationName": "testapp"
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

[Online testing using the Platform API]

Managing Mute

Chat provides several interfaces for managing chat room ban lists, including getting, adding, and removing users from the ban list

Name	Request	Description
Get the mute list	/{org_name}/{app_name}/chatrooms/{chatroom_id}/mute	Get the list of muted messages in the chat room
Add a mute	/{org_name}/{app_name}/chatrooms/{chatroom_id}/mute	Add users to the mute list of the chat room
Remove mute	/{org_name}/{app_name}/chatrooms/{chatroom_id}/mute/{member1}(,{member2},...)	Remove a user from the chat room's mute list

Add mute

Mutes a user. When a user is muted, they will not be able to send messages in the chat room.

HTTP Request

POST	/{org_name}/{app_name}/chatrooms/{chatroom_id}/mute

You need to fill in {chatroom_id} when requesting the chatroom ID that you need to add the ban to.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

Parameter	Description
mute_duration	The duration of the mute, in milliseconds, if "-1" means permanent (the actual expiration time is the fixed timestamp 4638873600000, i.e. 2117-01-01 00:00:00)
usernames	ID of the user to be added to the mute

Response Body

Parameter	Description
result	Operation result; true: add success; false: add failure
expire	Timestamp of the mute expiration (number of milliseconds from January 1, 1970. If the value of the ban time pass is "-1", then the timestamp is a fixed 4638873600000, see the description of the mute_duration parameter)
user	ID of the muted user

Request Example

curl -X POST 'HTTP://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/mute' -d '{"usernames":["user1"], "mute_duration":86400000}' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Examples of possible returned results

Returns a value of 200, indicating that the mute was added successfully

{
    "action": "post",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/mute",
    "entities": [],
    "data": [{
        "result": true,
        "expire": 1489158589481,
        "user": "user1"
    }],
    "timestamp": 1489072189508,
    "duration": 0,
    "organization": "chat-demo",
    "applicationName": "testapp"
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

[Online testing using the Platform API]

Remove mutes

Removes the user from the mute list. After removal, the user can send messages in the chat room normally.

HTTP Request

DELETE	/{org_name}/{app_name}/chatrooms/{chatroom_id}/mute/{member1}(,{member2},...)

You need to fill in {chatroom_id} when requesting the chatroom ID that needs to be removed from the mute，

and {member1}(,{member2},… to remove the muted username.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Example

curl -X DELETE 'HTTP://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/mute/user1'  -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Examples of possible results returned

Returns a value of 200, indicating successful removal of the mute

{
    "action": "delete",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/mute/user1",
    "entities": [],
    "data": [{
        "result": true,
        "user": "user1"
    }],
    "timestamp": 1489072695859,
    "duration": 0,
    "organization": "chat-demo",
    "applicationName": "testapp"
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

[Online testing using the Platform API]

Get the list of muted users

Gets the list of muted users in the current chat room.

HTTP Request

GET	/{org_name}/{app_name}/chatrooms/{chatroom_id}/mute

You need to fill in {chatroom_id} when requesting the chatroom ID that needs to get the muted list.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

Parameter	Description
expire	Timestamp of the ban expiration (number of milliseconds from January 1, 1970. If the value of the mute time pass is "-1", then the timestamp is a fixed 4638873600000, see the description of the mute_duration parameter)
user	ID of the muted user

Request Example

curl -X GET 'HTTP://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/mute' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Examples of possible returned results

Returns a value of 200, indicating that getting the ban list was successful

{
    "action": "post",
    "application": "527cd7e0-04b3-11e7-9f59-ef10ecd81ff0",
    "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/1265710621211/mute",
    "entities": [],
    "data": [{
        "expire": 1489158589481,
        "user": "user1"
    },
    {
        "expire": 1489158589481,
        "user": "user2"
    }],
    "timestamp": 1489072802179,
    "duration": 0,
    "organization": "chat-demo",
    "applicationName": "testapp"
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

[Online testing using the Platform API]

Managing Super Administrators

Chat provides several interfaces for managing chat room super administrators, including getting, adding, and removing them. Superadmin status gives permission to create chat rooms to normal users, who by default do not have permission to create chat rooms.

name	request	Description
Get the list of super administrators	/{org_name}/{app_name}/chatrooms/super_admin	Get the list of super administrators
Add Super Administrator	/{org_name}/{app_name}/chatrooms/super_admin	Add users to the Super Administrator list
Remove Super Administrator	/{org_name}/{app_name}/chatrooms/super_admin/{superAdmin}	Remove users from the Super Administrator list list

Paging the list of chat room super-administrators

Interface to paginate the list of super admins in a chat room.

HTTP Request

GET	/{org_name}/{app_name}/chatrooms/super_admin

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

Parameter	Description
data	Chat Room Super Admin ID List

Request Example

curl -X GET 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/super_admin?pagenum=2&pagesize=2' -H 'Authorization: Bearer YWMtG4T5wkOTEeST5V-9lp7f-wAAAUnafsqrQFnCU4gI0-rQImw4523fWqIasd1'

Examples of possible returned results

Returns a value of 200, indicating success in getting chat room members

{
    "action": "get",
    "application": "9fa492a0-40b1-11e5-b1b9-a76b05da6904",
    "params": {
        "pagesize": [
            "2"
        ],
        "pagenum": [
            "2"
        ]
    },
    "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/super_admin",
    "entities": [],
    "data": [
        "hxtest1",
        "hxtest11",
        "hxtest10"
    ],
    "timestamp": 1596187292391,
    "duration": 0,
    "organization": "chat-demo",
    "applicationName": "testapp",
    "count": 3
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

[Online testing using the Platform API]

Adding Super Admins

Adds super administrator status to the user for the chat room.

HTTP Request

POST	/{org_name}/{app_name}/chatrooms/super_admin

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

Parameter	Description
superadmin	Added user name

Response Body

View the information contained in the data field in the return value

Parameter	Description
result	Add result, true means add success, false means add failure

Request Example

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/super_admin'

Examples of possible returned results

Returns a value of 200, indicating that the chat room member was added successfully

{
    "action": "post",
    "application": "9fa492a0-40b1-11e5-b1b9-a76b05da6904",
    "uri": "http://a1.easecdn.com/chat-demo/testapp/hxdemo2/chatrooms/super_admin",
    "entities": [],
    "data": {
        "result": "success",
        "resource": ""
    },
    "timestamp": 1596187658017,
    "duration": 1,
    "organization": "chat-demo",
    "applicationName": "testapp"
}

Returns a value of 404, indicating that the added user or chat room does not exist

{
  "error": "resource_not_found",
  "timestamp": 1542554114398,
  "duration": 0,
  "exception": "com.easemob.group.exception.ResourceNotFoundException",
  "error_description": "username user10 doesn't exist!"
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542554229364,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

[Online testing using the Platform API]

Remove Super Admin

Remove the super administrator.

HTTP Request

DELETE	/{org_name}/{app_name}/chatrooms/super_admin/{superAdmin}

You need to fill in the request with the corresponding {superAdmin}, the IM user name that needs to be deleted.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Example

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easecdn.com/chat-demo/testapp/chatrooms/super_admin/user1'

Examples of possible returned results

Returns a value of 200, indicating that the chat room member was deleted successfully

{
    "action": "delete",
    "application": "9fa492a0-40b1-11e5-b1b9-a76b05da6904",
    "uri": "http://a1.easecdn.com/chat-demo/testapp/chatrooms/super_admin/hxtest10",
    "entities": [],
    "data": {
        "newSuperAdmin": "user1",
        "resource": ""
    },
    "timestamp": 1596187855832,
    "duration": 0,
    "organization": "chat-demo",
    "applicationName": "testapp"
}

Return value 401, unauthorized [no token, token error, token expired]

{
  "error": "group_authorization",
  "timestamp": 1542555910183,
  "duration": 0,
  "exception": "com.easemob.group.exception.GroupAuthorizationException",
  "error_description": "this token is bad, or has expired!"
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

[Online testing using the Platform API]