Skip to main content

Global mute

With increasingly strict rules and regulations on app compliance, content supervision has become a crucial part of the app lifecycle. To meet this need, Chat provides the global-mute feature, which enables you to mute any user ID in one-to-one chats, group chats, or chat rooms, preventing these users from sending messages to other chat users, chat groups, or chat rooms. When global-mute expires, the chat server automatically unmutes the user ID, and this user resumes the privilege of sending messages.

This feature can be widely applied in apps that power real-time engagements. For example, if a user frequently sends illegitimate advertisements to multiple chat rooms, you can use global-mute to prevent this user from sending chat room messages for 15 days; if a user makes improper statements concerning politics, global-mute can permanently prevent this user from sending any messages in one-to-one chats, chat groups, or chat rooms.

Before calling the following methods, make sure you understand the call frequency limit of the Chat RESTful APIs as 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 the Chat 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 the Chat 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.
  • Do not set this parameter as a UUID, email address, phone number, or other sensitive information.
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.
dataJSONThe response details.
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.

Globally mute a specified user

This method mutes a specified user in one-to-one chats, chat groups, or chat rooms. After a successful method call, this user can no longer send messages in one-to-one chats, chat groups, or chat rooms, depending on your settings in the request parameter.

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

HTTP request


_1
POST https://{host}/{orgName}/{appName}/mutes

Path parameter

For parameters and the detailed descriptions, see Commom parameters.

Request parameter

ParameterTypeRequiredDescription
usernameStringYesThe user ID that you want to globally mute.
chatNumberNoThe amount of time to mute this user ID in one-to-one chats, in seconds. The maximum value is 2,147,483,647.
  • > 0: The amount of time to mute the user in one-to-one chats.
  • 0: Unmutes the user in one-to-one chats.
  • -1: Permanently mutes the user in one-to-one chats.
  • If you set this parameter as any other negative values, the setting does not take effect.
groupchatNumberNoThe amount of time to mute this user in group chats, in seconds. The maximum value is 2,147,483,647.
  • > 0: The amount of time to mute the user in group chats.
  • 0: Unmutes the user in group chats.
  • -1: Permanently mutes the user in group chats.
  • If you set this parameter as any other negative values, the setting does not take effect.
chatroomNumberNoThe amount of time to mute this user in chat rooms, in seconds. The maximum value is 2,147,483,647.
  • > 0: The amount of time to mute the user in chat rooms.
  • 0: Unmutes the user in chat rooms.
  • -1: Permanently mutes the user in chat rooms.
  • If you set this parameter as any other negative values, the setting does not take effect.

Request header

ParameterTypeDescription
Content-TypeStringThe content type. Set is as application/json.
AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.

HTTP response

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

ParameterTypeDescription
resultStringThe result of this method call. ok means that global-mute is successfully enabled.

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


_9
curl -L -X POST 'https://XXXX/XXXX/XXXX/mutes' \
_9
-H 'Authorization: Bearer {YourAppToken}' \
_9
-H 'Content-Type: application/json' \
_9
--data-raw '{
_9
"username": "XXXX",
_9
"chat": 100,
_9
"groupchat": 100,
_9
"chatroom": 100
_9
}'

Reponse example


_13
{
_13
"path": "/mutes",
_13
"uri": "https://XXXX/XXXX/XXXX/mutes",
_13
"timestamp": 1631609754727,
_13
"organization": "XXXX",
_13
"application": "XXXX",
_13
"action": "post",
_13
"data": {
_13
"result": "ok"
_13
},
_13
"duration": 74,
_13
"applicationName": "XXXX"
_13
}

Query the detailed information of global-mute

This method queries the detailed information of the global-mute settings of the specified user in one-to-one chats, group chats, or chatrooms.

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

HTTP request


_1
GET https://{host}/{orgName}/{appName}/mutes/{username}

Path parameter

ParameterTypeRequiredDescription
usernameStringYesThe user ID whose global-mute settings you want to query.

For other parameters and the detailed descriptions, see Commom parameters.

Request header

ParameterTypeDescription
Content-TypeStringThe content type. Set is as application/json.
AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.

HTTP response

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

ParameterTypeDescription
useridStringThe user ID whose global-mute settings you want to query.
chatNumberThe remaining time that this user is muted in one-to-one chats, in seconds. The maximum value is 2,147,483,647.
  • > 0: The remaining time that this user is muted in one-to-one chats.
  • 0: This user is unmuted in one-to-one chats.
  • -1: This user is permanently muted in one-to-one chats.
groupchatNumberThe remaining time that this user is muted in group chats, in seconds. The maximum value is 2,147,483,647.
  • > 0: The remaining time that this user is muted in group chats.
  • 0: This user is unmuted in group chats.
  • -1: This user is permanently muted in group chats.
chatroomNumberThe remaining time that this user is muted in group rooms, in seconds. The maximum value is 2,147,483,647.
  • > 0: The remaining time that this user is muted in chat rooms.
  • 0: This user is unmuted in chat rooms.
  • -1: This user is permanently muted in chat rooms.
unixtimeNumberThe Unix timestamp of the current operation.

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 -L -X GET 'https://XXXX/XXXX/XXXX/mutes/{username}' \
_3
-H 'Authorization: Bearer {YourAppToken}' \
_3
-H 'Content-Type: application/json'

Response example


_17
{
_17
"path": "/mutes",
_17
"uri": "https://XXXX/XXXX/XXXX/mutes",
_17
"timestamp": 1631609831800,
_17
"organization": "XXXX",
_17
"application": "XXXX",
_17
"action": "get",
_17
"data": {
_17
"userid": "XXXX",
_17
"chat": 96,
_17
"groupchat": 96,
_17
"chatroom": 96,
_17
"unixtime": 1631609831
_17
},
_17
"duration": 13,
_17
"applicationName": "XXXX"
_17
}

Retrieve all globally muted users

This method retrieves all the users that have been globally muted in the app, and returns the remaining time that each user is muted for each type of chat.

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

HTTP request


_1
GET https://{host}/{orgName}/{appName}/mutes

Path parameter

For parameters and the detailed descriptions, see Commom parameters.

Request header

ParameterTypeDescription
Content-TypeStringThe content type. Set is as application/json.
AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.

Request body

ParameterTypeRequiredDescription
pageNumNumberYesThe number of page for querying the globally muted users in the app.
pageSizeNumberYesThe number of data entries on each page.

HTTP response

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

ParameterTypeDescription
usernameStringThe user ID whose global-mute settings you want to query.
chatNumberThe remaining time that this user is muted in one-to-one chats, in seconds. The maximum value is 2,147,483,647.
  • > 0: The remaining time that this user is muted in one-to-one chats.
  • 0: This user is unmuted in one-to-one chats.
  • -1: This user is permanently muted in one-to-one chats.
groupchatNumberThe remaining time that this user is muted in group chats, in seconds. The maximum value is 2,147,483,647.
  • > 0: The remaining that this user in chat groups.
  • 0: This user is unmuted in chat groups.
  • -1: This user is permanently muted in chat groups.
chatroomNumberThe remaining time that this user is muted in group rooms, in seconds. The maximum value is 2,147,483,647.
  • > 0: The remaining duration for muting this user in chat rooms.
  • 0: This user is unmuted in chat rooms.
  • -1: This user is permanently muted in chat rooms.
unixtimeNumberThe Unix timestamp of the current operation.

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 -L -X GET 'https://XXXX/XXXX/XXXX/mutes?pageNum=1&pageSize=10' \
_3
-H 'Authorization: Bearer {YourAppToken}' \
_3
-H 'Content-Type: application/json'

Response example


_43
{
_43
"path": "/mutes",
_43
"uri": "https://XXXX/XXXX/XXXX/mutes",
_43
"timestamp": 1631609858771,
_43
"organization": "XXXX",
_43
"application": "XXXX",
_43
"action": "get",
_43
"data": {
_43
"data": [
_43
{
_43
"username": "XXXX",
_43
"chatroom": 0
_43
},
_43
{
_43
"username": "XXXX",
_43
"groupchat": 69
_43
},
_43
{
_43
"username": "XXXX",
_43
"chat": 69
_43
},
_43
{
_43
"username": "XXXX",
_43
"chatroom": 69
_43
},
_43
{
_43
"username": "XXXX",
_43
"chatroom": 0
_43
},
_43
{
_43
"username": "XXXX",
_43
"groupchat": 0
_43
},
_43
{
_43
"username": "XXXX",
_43
"chat": 0
_43
}
_43
],
_43
"unixtime": 1631609858
_43
},
_43
"duration": 17,
_43
"applicationName": "XXXX"
_43
}

Status codes

For details, see HTTP Status Codes.