Skip to main content

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

RoleDescriptionPrivilege
Regular memberChat room members without administrative privileges.Regular chat room members can modify their own chat room profiles.
Chat room adminChat 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 ownerThe 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

ParameterTypeDescriptionRequired
hostStringThe 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
org_nameStringThe unique identifier assigned to each company (organization) by the Chat service. For how to get the org name, see Get the information of your project.Yes
app_nameStringThe unique identifier assigned to each app by the Chat service. For how to get the app name, see Get the information of your project.Yes
usernameStringThe 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)
  • 26 uppercase English letters (A-Z)
  • 10 numbers (0-9)
  • "_", "-", "."
  • The username is case insensitive, so Aa and aa are the same username.
  • Ensure that each username under the same app is unique.
Yes
chatroom_idStringThe 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

ParameterTypeDescription
actionStringThe request method.
organizationStringThe unique identifier assigned to each company (organization) by the Chat service. This is the same as org_name.
applicationStringA unique internal ID assigned to each app by the Chat service. You can safely ignore this parameter.
applicationNameStringThe unique identifier assigned to each app by the Chat service . This is the same as app_name.
uriStringThe request URI.
pathStringThe request path, which is part of the request URL. You can safely ignore this parameter.
entities JSONThe response entity.
entities.createdNumberThe Unix timestamp (ms) when the user is registered.
entities.usernameStringThe username. The unique account the user is logged in with.
dataJSONThe details of the response.
timestampNumberThe Unix timestamp (ms) when the user is registered.
durationNumberThe 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


_1
POST https://{host}/{org_name}/{app_name}/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

ParameterTypeDescriptionRequired
Content-TypeStringapplication/jsonYes
AcceptStringapplication/jsonYes
AuthorizationStringThe 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:

FieldTypeDescription
resultBoolThe addition result:
  • true: Success
  • false: Failure
  • actionStringThe operation that is performed. add_member means to add a member to the chat room.
    idStringThe chat room ID. This is the unique identifier assigned to the chat room by the Chat service.
    userStringThe 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


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

    Response example


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

    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


    _1
    POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroomid}/users

    Path parameter

    For the parameters and detailed descriptions, see Common parameters .

    You can add at most 60 users at one request.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringapplication/jsonYes
    AcceptStringapplication/jsonYes
    AuthorizationStringThe 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:

    FieldTypeDescriptionRequired
    usernamesJSONArrayThe 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:

    FieldTypeDescription
    newmembersJSONArrayThe array of usernames of the exsiting chat room members.
    actionStringThe operation that is performed. add_member means to add a member to the chat room.
    idStringThe 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


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

    Response example


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

    Retrieving chat room members with pagination

    Retrieves chat room members with pagination.

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

    HTTP request


    _1
    GET https://{host} /{org_name}/{app_name}/chatrooms/super_admin?pagenum={N}&pagesize={N}

    Path parameter

    For the parameters and detailed descriptions, see Common parameters .

    Query parameters

    ParameterTypeDescriptionRequired
    pagenumIntThe number of page on which chat room members are retrieved. The default value is 1.No
    pagesizeIntThe number of chat room members displayed on each page. The default value is 1000. The value range is [0,1000].No

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    AuthorizationStringThe 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:

    FieldTypeDescription
    memberStringThe username of a chat room member.

    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


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

    Response example


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

    Removing the specified chat room 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


    _1
    DELETE https://{host}/{org_name}/{app_name}/chatrooms/{chatroomid}/users/{username}

    Path parameter

    For the parameters and detailed descriptions, see Common parameters .

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    AuthorizationStringThe 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:

    FieldTypeDescription
    resultBoolThe deletion result:
  • true: Success
  • false: Failure
  • actionStringThe operation that is performed. remove_member means to delete a chat room member.
    userStringThe username of the chat room member that is removed.
    idStringThe 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


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

    Response example


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

    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


    _1
    DELETE https://{host} /{org_name}/{app_name}/chatrooms/{chatroomid}/users/{usernames}

    HTTP request

    Path parameter

    ParameterTypeDescriptionRequired
    usernamesStringOne 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 at one time.Yes

    For other parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    AuthorizationStringThe 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:

    FieldTypeDescription
    resultBoolThe deletion result:
  • true: Success
  • false: Failure
  • actionStringThe operation that is performed. remove_member means to remove a chat room member.
    reasonStringThe reason why the method fails.
    userStringThe list of usernames of chat room members that are deleted.
    idStringThe 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


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

    Response example


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

    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


    _1
    POST https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin

    Path parameter

    For the parameters and detailed descriptions, see Common parameters .

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    Content-TypeStringapplication/jsonYes
    AuthorizationStringThe 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:

    FieldTypeDescriptionRequired
    newadminStringThe 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:

    FieldTypeDescription
    resultBoolThe addition result:
  • true: Success
  • false: Failure
  • newadminStringThe 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


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

    Response example


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

    Retrieving chat room 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


    _1
    GET https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin

    Path parameter

    For the parameters and detailed descriptions, see Common parameters .

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    AuthorizationStringThe 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:

    FieldTypeDescription
    dataJSONArrayThe 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


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

    Response example


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

    Removing chat room 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


    _1
    DELETE https://{host}/{org_name}/{app_name}/chatrooms/{chatroom_id}/admin/{oldadmin}

    Path parameter

    ParameterTypeDescriptionRequired
    oldadminStringThe 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

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    AuthorizationStringThe 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:

    FieldTypeDescription
    resultBooleanThe revocation result:
  • true: Success
  • false: Failure
  • oldadminStringThe 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


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

    Response example


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

    Status codes

    For details, see HTTP Status Codes.