Skip to main content
Conversational AI Engine: Create advanced voice apps by combining Agora's real-time audio with powerful conversational AI.

Manage chat group block list

A chat group blocklist refers to a list of users that can neither see nor receive group messages. Chat provides a complete set of blocklist management methods, including adding and removing chat group members from the chat group blocklist, and retrieving the blocklist.

This page shows how to manage a chat group blocklist by calling the Chat RESTful APIs. Before calling the following methods, ensure that you understand the call frequency limit described in Limitations.

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)
  • 10 numbers (0-9)
  • "_", "-", "."
info
  • Do not use any of the 26 uppercase English letters (A-Z).
  • Ensure that each username under the same app is unique.
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 URI. You can safely ignore this parameter.
entities JSONThe response entity.
dataJSONThe details of the response.
timestampNumberThe Unix timestamp (ms) of the HTTP response.
durationNumberThe duration (ms) from when the HTTP request is sent to the time the response is received.

Authorization​

Chat RESTful APIs require Bearer HTTP authentication. Every time an HTTP request is sent, the following Authorization field must be filled in the request header:


_1
Authorization: Bearer ${YourAppToken}

In order to improve the security of the project, Agora uses a token (dynamic key) to authenticate users before they log in to the chat system. Chat RESTful APIs only support authenticating users using app tokens. For details, see Authentication using App Token.

Retrieving the chat group blocklist​

Retrieves the blocklist of the specified chat group. Users added to the blocklist can neither see nor receive messages in the chat group.

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}/chatgroups/{group_id}/blocks/users?pageSize={N}&cursor={cursor}

Path parameter​

ParameterTypeDescriptionRequired
group_idStringThe group ID.Yes

For other parameters and detailed descriptions, see Common parameters.

Query parameter​

ParameterTypeDescriptionRequired
pageSizeNumberThe number of users on the blocklist to retrieve per page.Yes
cursorStringThe position from which to start getting data.Yes
If you pass in neither pageSize nor cursor, the server returns the top 500 users in the descending order of time when they are added to the blocklist. If you pass in only pageSize, but not cursor, the server returns a maximum of 50 users in the descending order of time when they are added to the blocklist.

Request header​

ParameterTypeDescriptionRequired
Content-TypeStringThe parameter type. Set it as application/json.Yes
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 data field in the response body contains the usernames in the group blocklist.

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

Example​

Request example​


_1
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/blocks/users?pageSize=2'

Response example​


_13
{
_13
"uri": " https://XXXX/XXXX/XXXX/chatgroups/66XXXX85/users/blocks/users",
_13
"timestamp": 1682064422108,
_13
"entities": [],
_13
"cursor": "MTA5OTAwMzMwNDUzNTA2ODY1NA==",
_13
"count": 2,
_13
"action": "get",
_13
"data": [
_13
"tst05",
_13
"tst04"
_13
],
_13
"duration": 52
_13
}

Adding a user to the chat group blocklist​

Adds the specified user to the chat group blocklist. Once added to the chat group blocklist, users can neither send nor receive messages in the chat group.

You cannot add the chat group owner to the group blocklist.

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}/chatgroups/{group_id}/blocks/users/{username}

Path parameter​

ParameterTypeDescriptionRequired
group_idStringThe group ID.Yes

For other parameters and detailed descriptions, see Common parameters.

Request header​

ParameterTypeDescriptionRequired
Content-TypeStringThe parameter type. Set it as application/json.Yes
AcceptStringThe parameter type. Set it as application/json.Yes
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 data field in the response body contains the following parameters.

ParameterTypeDescription
resultBooleanWhether the users are sucessfully added to the group blocklist.
  • true: Yes.
  • false: No.
groupidStringThe group ID.
actionStringThe request method.
userStringThe usernames added to the group blocklist.

For other fields and descriptions, see Common parameters.

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

Example​

Request example​


_1
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users/user1'

Response example​


_16
{
_16
"action": "post",
_16
"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
_16
"uri": "http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users/user1",
_16
"entities": [],
_16
"data": {
_16
"result": true,
_16
"action": "add_blocks",
_16
"user": "user1"
_16
"groupid": "66016455491585"
_16
},
_16
"timestamp": 1542539577124,
_16
"duration": 27,
_16
"organization": "XXXX",
_16
"applicationName": "XXXX"
_16
}

Adding multiple users to the chat group blocklist​

Adding multiple users to the group blocklist. Once added to the chat group blocklist, users can neither send nor receive messages in the chat group.

You can add a maximim of 60 users to the group blocklist each time. You cannot add the group owner to the group blocklist.

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}/chatgroups/{group_id}/blocks/users

Path parameter​

ParameterTypeDescriptionRequired
group_idStringThe group ID.Yes

For other parameters and detailed descriptions, see Common parameters.

Request header​

ParameterTypeDescriptionRequired
Content-TypeStringThe parameter type. Set it as application/json.Yes
AcceptStringThe parameter type. Set it as application/json.Yes
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​

ParameterTypeDescriptionRequired
usernamesArrayThe array of usernames to be added to the group blocklist.Yes

HTTP response​

Response body​

If the returned HTTP status code is 200, the request succeeds, and the data field in the response body contains the following parameters.

ParameterTypeDescription
resultBooleanWhether the users are sucessfully added to the group blocklist.
  • true: Yes.
  • false: No.
reasonStringThe reason why the users fail to be added to the group blocklist.
groupidStringThe group ID.
actionStringThe request method.
userStringThe usernames added to the group blocklist.

For other fields and descriptions, see Common parameters.

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

Example​

Request example​


_5
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
_5
"usernames": [
_5
"user3","user4"
_5
]
_5
}' 'http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users'

Response example​


_25
{
_25
"action": "post",
_25
"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
_25
"uri": "http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users",
_25
"entities": [],
_25
"data": [
_25
{
_25
"result": false,
_25
"action": "add_blocks",
_25
"reason": "user: user3 doesn't exist in group: 66016455491585",
_25
"user": "user3",
_25
"groupid": "66016455491585"
_25
},
_25
{
_25
"result": true,
_25
"action": "add_blocks",
_25
"user": "user4",
_25
"groupid": "66016455491585"
_25
}
_25
],
_25
"timestamp": 1542540095540,
_25
"duration": 16,
_25
"organization": "XXXX",
_25
"applicationName": "XXXX"
_25
}

Removing a user from the chat group blocklist​

Removes the specified user from the chat group blocklist. To add a user that is in the blocklist back to the chat group, you need to remove that user from the blocklist first.

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}/chatgroups/{group_id}/blocks/users/{username}

Path parameter​

ParameterTypeDescriptionRequired
group_idStringThe group ID.Yes

For other parameters and detailed descriptions, see Common parameters.

Request header​

ParameterTypeDescriptionRequired
AcceptStringThe parameter type. Set it as application/json.Yes
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 data field in the response body contains the following parameters.

ParameterTypeDescription
resultBooleanWhether the user is successfully removed from the group blocklist.
  • true: Yes.
  • false: No.
    • groupidStringThe group ID.
    actionStringThe request method.
    userStringThe usernames removed from the group blocklist.

    For other fields and descriptions, see Common parameters.

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

    Example​

    Request example​


    _1
    curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users/user1'

    Response example​


    _16
    {
    _16
    "action": "delete",
    _16
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    _16
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users/user1",
    _16
    "entities": [],
    _16
    "data": {
    _16
    "result": true,
    _16
    "action": "remove_blocks",
    _16
    "user": "user1"
    _16
    "groupid": "66016455491585"
    _16
    },
    _16
    "timestamp": 1542540470679,
    _16
    "duration": 45,
    _16
    "organization": "XXXX",
    _16
    "applicationName": "XXXX"
    _16
    }

    Removing multiple users from the chat group blocklist​

    Removes the specified users from the group blocklist. To add users that are in the blocklist back to the chat group, you need to remove these users from the blocklist first. You can remove up to 60 users from the blocklist each time.

    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}/chatgroups/{group_id}/blocks/users/{usernames}

    Path parameter​

    ParameterTypeDescriptionRequired
    group_idStringThe group ID.Yes
    usernamesStringThe usernames to be removed from the group blocklist, separated by the comma (,).Yes

    For other parameters and detailed descriptions, see Common parameters.

    Request header​

    ParameterTypeDescriptionRequired
    AcceptStringThe parameter type. Set it as application/json.Yes
    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 data field in the response body contains the following parameters.

    ParameterTypeDescription
    ParameterTypeDescription
    resultBooleanWhether the user is successfully removed from the group.
  • true: Yes.
  • false: No.
    • groupidStringThe group ID.
    actionStringThe request method.
    userStringThe usernames removed from the group blocklist.

    For other fields and descriptions, see Common parameters.

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

    Example​

    Request example​


    _1
    curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users/user1%2Cuser2'

    Response example​


    _24
    {
    _24
    "action": "delete",
    _24
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    _24
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/66016455491585/blocks/users/user1%2Cuser2",
    _24
    "entities": [],
    _24
    "data": [
    _24
    {
    _24
    "result": true,
    _24
    "action": "remove_blocks",
    _24
    "user": "user1"
    _24
    "groupid": "66016455491585"
    _24
    },
    _24
    {
    _24
    "result": true,
    _24
    "action": "remove_blocks",
    _24
    "user": "user2",
    _24
    "groupid": "66016455491585"
    _24
    }
    _24
    ],
    _24
    "timestamp": 1542541014655,
    _24
    "duration": 29,
    _24
    "organization": "XXXX",
    _24
    "applicationName": "XXXX"
    _24
    }

    Status codes​

    For details, see HTTP Status Code.