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, Agora 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 Agora Chat RESTful APIs:

Request parameters

Response parameters

Authorization

Agora 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:

Authorization: Bearer ${YourAppToken}

In order to improve project security, Agora uses a token (dynamic key) to authenticate users before they log in to the chat system. Agora 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

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

Path parameter

For parameters and the detailed descriptions, see Commom parameters.

Request parameter

Request header

HTTP response

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

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 -L -X POST 'https://XXXX/XXXX/XXXX/mutes' \
-H 'Authorization: Bearer {YourAppToken}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "username": "XXXX",
    "chat": 100,
    "groupchat": 100,
    "chatroom": 100
}'

Reponse example

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

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

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

Path parameter

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

Request header

HTTP response

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

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

Response example

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

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

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

Path parameter

For parameters and the detailed descriptions, see Commom parameters.

Request header

Request body

HTTP response

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

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

Response example

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

Status codes

For details, see HTTP Status Codes.