Manage chat room members

This page shows how to manage chat room members by calling the Chat RESTful APIs, including adding, retrieving, and deleting chat room members and revoking administrative privileges of chat room administrators. Before calling the following methods, ensure that you understand the call frequency limit of the Chat RESTful APIs described in Limitations.

Description of chat room member roles

Role	Description	Privilege
Regular member	Chat room members without administrative privileges.	Regular chat room members can modify their own chat room profiles.
chat room admin	Chat room admins are authorized by the chat room owner and have chat room management privileges.	The admins can manage regular members of the chat room. A maximum of 99 admins can be added.
chat room owner	The creator of the chat room. Chat room owners have the highest privileges.	The chat room owner can add chat room admins, disband the chat room, modify chat room information, and manage regular members of the chat room.

Common parameters

The following table lists common request and response parameters of the Chat RESTful APIs:

Request parameters

Parameter	Type	Description	Required
`host`	String	The domain name assigned by the Chat service to access RESTful APIs. For how to get the domain name, see Get the information of your project.	Yes
`app_id`	String	The unique identifier automatically assigned to each project by Agora	Yes
`username`	String	The unique login account of the user. The user ID must be 64 characters or less and cannot be empty. The following character sets are supported: 26 lowercase English letters (a-z) 10 numbers (0-9) "_", "-", "." Do not use any of the 26 uppercase English letters (A-Z). Ensure that each `username` under the same App ID is unique.	Yes
`chatroom_id`	String	The chat room ID. The unique chat room identifier assigned to each chat room by the Chat. You can get the chat room ID from the response body in Retrieve the basic information of all chat rooms.	Yes

Response parameters

Parameter	Type	Description
`action`	String	The request method.
`organization`	String	The unique identifier assigned to each company (organization) by the Chat service.
`application`	String	A unique internal ID assigned to each app by the Chat service. You can safely ignore this parameter.
`applicationName`	String	The unique identifier assigned to each app by the Chat service .
`uri`	String	The request URI.
`path`	String	The request path, which is part of the request URL. You can safely ignore this parameter.
`entities`	JSON	The response entity.
`entities.created`	Number	The Unix timestamp (ms) when the user is registered.
`entities.username`	String	The username. The unique account the user is logged in with.
`data`	JSON	The details of the response.
`timestamp`	Number	The Unix timestamp (ms) when the user is registered.
`duration`	Number	The time duration (ms) from sending the HTTP request to receiving the response.

Adding a chat room member

Adds the specified user to the chat room.

For each App Key, the call frequency limit of this method is 100 per second.

HTTP request

POST https://{host}/app-id/{app_id}/chatrooms/{chatroomid}/users/{username}

Path parameter

For the parameters and detailed descriptions, see Common parameters .

If the specified user does not exist in the app or is already a member of the chat room, the request fails and the error code 400 is returned.

Request header

Parameter	Type	Description	Required
`Content-Type`	String	`application/json`	Yes
`Accept`	String	`application/json`	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Field	Type	Description
`result`	Bool	The addition result: `true`: Success. `false`: Failure.
`action`	String	The operation that is performed. `add_member` means to add a member to the chat room.
`id`	String	The chat room ID. This is the unique identifier assigned to the chat room by the Chat service.
`user`	String	The array of usernames of the existing chat room members.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

# Replace  with the app token generated in your server.
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatrooms/XXXX/users/XXXX'

Response example

{
    "action": "post",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/app-id/XXXX/chatrooms/XXXX/users/XXXX",
    "entities": [],
    "data": {
        "result": true,
        "action": "add_member",
        "id": "XXXX",
        "user": "user1"
    },
    "timestamp": 1542554038353,
    "duration": 0,
    "organization": "XXXX",
    "applicationName": "XXXX"
}

Adding multiple chat room members

Adds multiple specified users to the chat room.

For each App Key, the call frequency limit of this method is 100 per second.

HTTP request

POST https://{host}/app-id/{app_id}/chatrooms/{chatroomid}/users

Path parameter

For the parameters and detailed descriptions, see Common parameters .

You can add at most 60 users each time.

Request header

Parameter	Type	Description	Required
`Content-Type`	String	`application/json`	Yes
`Accept`	String	`application/json`	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

Request body

The request body is a JSON object, which contains the following fields:

Field	Type	Description	Required
`usernames`	JSONArray	The array of usernames of chat room members that you want to add to the chat room.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Field	Type	Description
`newmembers`	JSONArray	The array of usernames of the existing chat room members.
`action`	String	The operation that is performed. `add_member` means to add a member to the chat room.
`id`	String	The chat room ID. This is the unique identifier assigned to the chat room by the Chat.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

# Replace  with the app token generated in your server.
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '{
   "usernames": [
     "user": "user2"
   ]
 }' 'http://XXXX/app-id/XXXX/chatrooms/XXXX/users'

Response example

{
    "action": "post",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/app-id/XXXX/chatrooms/XXXX/users",
    "entities": [],
    "data": {
        "newmembers": ["user1", "user2"],
        "action": "add_member",
        "id": "XXXX"
    },
    "timestamp": 1542554537237,
    "duration": 39,
    "organization": "XXXX",
    "applicationName": "XXXX"
}

Retrieving members with pagination

Retrieves members with pagination.

For each App Key, the call frequency limit of this method is 100 per second.

HTTP request

GET https://{host}/app-id/{app_id}/chatrooms/{chatroom_id}/users?pagenum={N}&pagesize={N}

Path parameter

For the parameters and detailed descriptions, see Common parameters .

Query parameters

Parameter	Type	Description	Required
`pagenum`	Int	The page number on which chat room members are retrieved. The default value is 1.	No
`pagesize`	Int	The number of chat room members displayed on each page. The default value is 1000. The value range is [0,1000]. If you pass in a value greater than `1000`, the server still returns 1000 chat room members.	No

Request header

Parameter	Type	Description	Required
`Accept`	String	`application/json`	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Field	Type	Description
`owner`	String	The username of the chat room owner, for example, `{"owner":"user1"}`.
`member`	String	The username of a chat room admin or regular chat room member, for example, `{"member":"user2"}`.
`count`	String	The number of chat room members retrieved at this call of this API.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

# Replace  with the app token generated in your server.
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatrooms/XXXX/users?pagenum=2&pagesize=2'

Response example

{
    "action": "get",
    "application": "527cd7e0-XXXX-XXXX-9f59-ef10ecd81ff0",
    "params": {
        "pagesize": ["2"],
        "pagenum": ["2"]
    },
    "uri": "http://XXXX/app-id/XXXX/chatrooms/XXXX/users",
    "entities": [],
    "data": [
        {
            "owner": "user1"
        },
        {
            "member": "user2"
        }
    ],
    "timestamp": 1489074511416,
    "duration": 0,
    "organization": "XXXX",
    "applicationName": "XXXX",
    "count": 2
}

Removing the specified member

Removes the specified user from the chat room.

For each App Key, the call frequency limit of this method is 100 per second.

HTTP request

DELETE https://{host}/app-id/{app_id}/chatrooms/{chatroomid}/users/{username}

Path parameter

For the parameters and detailed descriptions, see Common parameters .

Request header

Parameter	Type	Description	Required
`Accept`	String	`application/json`	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Field	Type	Description
`result`	Bool	The deletion result: `true`: Success. `false`: Failure.
`action`	String	The operation that is performed. `remove_member` means to delete a chat room member.
`user`	String	The username of the chat room member that is removed.
`id`	String	The chat room ID. This is the unique identifier assigned to the chat room by the Chat service.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Request example

# Replace  with the app token generated in your server.
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatrooms/XXXX/users/XXXX'

Response example

{
    "action": "delete",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/app-id/XXXX/chatrooms/XXXX/users/XXXX",
    "entities": [],
    "data": {
        "result": true,
        "action": "remove_member",
        "user": "user1"
        "id": "XXXX"
    },
    "timestamp": 1542555744726,
    "duration": 1,
    "organization": "XXXX",
    "applicationName": "XXXX"
}

Removing multiple chat room members

Removes multiple users from the chat room.

For each App Key, the call frequency limit of this method is 100 per second.

HTTP request

DELETE https://{host} /app-id/{app_id}/chatrooms/{chatroomid}/users/{usernames}

HTTP request

Path parameter

Parameter	Type	Description	Required
`usernames`	String	One or more usernames separated with the comma (,). In the URL, "," needs to be represented by "%2C". A maximum of 100 usernames can be passed in each time.	Yes

For other parameters and detailed descriptions, see Common parameters.

Request header

Parameter	Type	Description	Required
`Accept`	String	`application/json`	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds. The response body contains the following fields:

Field	Type	Description
`result`	Bool	The deletion result: `true`: Success. `false`: Failure.
`action`	String	The operation that is performed. `remove_member` means to remove a chat room member.
`reason`	String	The reason why the method fails.
`user`	String	The list of usernames of chat room members that are deleted.
`id`	String	The chat room ID. This is the unique identifier assigned to the chat room by the Chat service.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Request example

# Replace  with the app token generated in your server.
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatrooms/XXXX/users/user1%2Cuser2'

Response example

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

Adding a chat room admin

Adds a regular chat room member as the chat room admin.

For each App Key, the call frequency limit of this method is 100 per second.

HTTP request

POST https://{host}/app-id/{app_id}/chatrooms/{chatroom_id}/admin

Path parameter

For the parameters and detailed descriptions, see Common parameters .

Request header

Parameter	Type	Description	Required
`Accept`	String	`application/json`	Yes
`Content-Type`	String	`application/json`	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

Request body

The request body is a JSON object, which contains the following fields:

Field	Type	Description	Required
`newadmin`	String	The username to be added as the chat room admin.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Field	Type	Description
`result`	Bool	The addition result: `true`: Success. `false`: Failure.
`newadmin`	String	The username of the chat room administrator that is added.

For other fields and detailed descriptions, see Common parameters. If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '{
   "newadmin": "user1"
 }' 'http://XXXX/app-id/XXXX/chatrooms/XXXX/admin'

Response example

{
    "action": "post",
    "application": "22bcffa0-XXXX-XXXX-9df8-516f6df68c6d",
    "applicationName": "XXXX",
    "data": {
        "result": "success",
        "newadmin": "user1"
    },
    "duration": 0,
    "entities": [],
    "organization": "XXXX",
    "timestamp": 1642486989028,
    "uri": "http://XXXX/app-id/XXXX/chatrooms/XXXX/admin"
}

Retrieving admins

Retrieves all the admins of the specified chat room.

For each App Key, the call frequency limit of this method is 100 per second.

HTTP request

GET https://{host}/app-id/{app_id}/chatrooms/{chatroom_id}/admin

Path parameter

For the parameters and detailed descriptions, see Common parameters .

Request header

Parameter	Type	Description	Required
`Accept`	String	`application/json`	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

Field	Type	Description
`data`	JSONArray	The array of usernames of chat room administrators.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

# Replace  with the app token generated in your server.
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatrooms/XXXX/admin'

Response example

{
    "action": "get",
    "application": "527cd7e0-XXXX-XXXX-9f59-ef10ecd81ff0",
    "uri": "http://XXXX/app-id/XXXX/chatrooms/XXXX/admin",
    "entities": [],
    "data": ["XXXX"],
    "timestamp": 1489073361210,
    "duration": 0,
    "organization": "XXXX",
    "applicationName": "XXXX",
    "count": 1
}

Removing admins

Removes the administrative privileges of the chat room admin, and that admin becomes a regular chat room member.

For each App Key, the call frequency limit of this method is 100 per second.

HTTP request

DELETE https://{host}/app-id/{app_id}/chatrooms/{chatroom_id}/admin/{oldadmin}

Path parameter

Parameter	Type	Description	Required
`oldadmin`	String	The username of the chat room admin to be demoted as a regular chat room member.	Yes

For other parameters and detailed descriptions, see Common parameters.

Request header

Parameter	Type	Description	Required
`Accept`	String	`application/json`	Yes
`Authorization`	String	The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value.	Yes

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds and the response body contains the following fields:

Field	Type	Description
`result`	Boolean	The revocation result: `true`: Success. `false`: Failure.
`oldadmin`	String	The username of the chat room administrator whose administrative privileges are revoked.

For other fields and detailed descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

Example

Request example

# Replace  with the app token generated in your server.
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatrooms/XXXX/admin/XXXX'

Response example

{
    "action": "delete",
    "application": "527cd7e0-XXXX-XXXX-9f59-ef10ecd81ff0",
    "uri": "http://XXXX/app-id/XXXX/chatrooms/XXXX/admin/XXXX",
    "entities": [],
    "data": {
        "result": "success",
        "oldadmin": "XXXX"
    },
    "timestamp": 1489073432732,
    "duration": 1,
    "organization": "XXXX",
    "applicationName": "XXXX"
}

Status codes

For details, see HTTP Status Codes.

Contact Us

Contact Us