Create rule

POST

https://api.agora.io/dev/v1/kicking-rule

Use this endpoint to create a rule for banning specified user privileges.

The request URL and request body is case-sensitive. All requests must use HTTPS.

• Content-Type: application/json
• The request header must contain the Authorization field. For details, see RESTful authentication.

APPLICATION/JSON

BODYrequired

stringrequired
The App ID of the project. You can get it through one of the following methods:
• Copy from the Agora Console
• Call the Get all projects API, and read the value of the vendor_key field in the response body.
stringnullable

The channel name.

numbernullable

The user ID. Do not set it to 0.

stringnullable

The IP address of the user. Do not set it to 0.

numbernullable

Range: [1, 1440]

The time duration (in minutes) to ban the user. Values outside the range [1,1440] are clamped to the nearest bound. Setting this to 0 disables the rule: users are set offline but can rejoin immediately.

numbernullable

Range: [10, 86430]

The time duration (in seconds) to ban the user. Values outside the range [10,86430] are clamped to the nearest bound. Setting this to 0 disables the rule: users are set offline but can rejoin immediately.

info

Use either time or time_in_seconds, not both. If both are set, time_in_seconds takes effect. If neither is set, the default ban duration is 60 minutes (3600 seconds).

arrayrequired

The user privileges you want to block. Possible values:

• join_channel: Bans a user from joining a channel or kicks a user out of a channel.
• publish_audio: Bans a user from publishing audio.
• publish_video: Bans a user from publishing video.

To ban a user from both publishing audio and video, specify both publish_audio and publish_video.

The effect of the banning rule depends on the combination of cname, uid, and ip you set. See Banning rule behavior for details.

When privileges is set to join_channel, a kicked user receives a connection state change callback on their platform. See Client callbacks for join_channel bans for details.

A 200 status code indicates success. The response body contains the following parameters:

OK

string

The status of this request. success means the request succeeds.

number

The rule ID. Save the rule ID to update or delete this rule later.

If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure. Refer to Response status codes for details.

The banning rule behavior depends on which combination of cname, uid, and ip fields you set.

When privileges is join_channel:

ip	cname	uid	Rule
✔	✘	✘	All users with this ip cannot join any channel in the app. Using ip as a filter field may incorrectly block users who should not be blocked, for example, in a use-case where multiple users share an IP address.
✘	✔	✘	No one can join the channel specified by the cname field. Using cname as a filter field directly blocks the named channel.
✘	✘	✔	The user with the uid cannot join any channel in the app.
✘	✔	✔	The user with the uid cannot join the channel specified by the cname field.

When privileges is publish_audio or publish_video:

ip	cname	uid	Rule
✔	✘	✘	The users with this ip cannot publish audio or video in any channel of the app.
✘	✔	✘	No one can publish audio or video in the channel specified by the cname field.
✘	✘	✔	The user with the uid cannot publish audio or video in any channel of the app.
✘	✔	✔	The user with the uid cannot publish audio or video in the channel specified by the cname field.

A user who is kicked out of a channel when privileges is set to join_channel receives one of the following callbacks based on their platform:

• Android: The onConnectionStateChanged callback reports CONNECTION_CHANGED_BANNED_BY_SERVER(3).
• iOS/macOS: The connectionChangedToState callback reports AgoraConnectionChangedBannedByServer(3).
• Web (3.x): The Client.on("client-banned") callback.
• Web (4.x): The Client.on("connection-state-change") callback.
• Windows: The onConnectionStateChanged callback reports CONNECTION_CHANGED_BANNED_BY_SERVER(3).
• Electron: The AgoraRtcEngine.on("connectionStateChanged") callback reports 3.
• Unity: The OnConnectionStateChangedHandler callback reports CONNECTION_CHANGED_BANNED_BY_SERVER(3).
• React Native: The ConnectionStateChanged callback reports BannedByServer(3).
• Flutter: The ConnectionStateChanged callback reports BannedByServer(3).
• Cocos Creator: The onConnectionStateChanged callback reports CONNECTION_CHANGED_BANNED_BY_SERVER(3).
• Applets: on(event: "client-banned").

To maximize the success rate of create, update, and delete operations, query requests are assigned a lower priority. Under poor network conditions, the success rate and accuracy of GET requests may degrade and some request records may be missing from the results.

When you call POST to create a rule where time is not set to 0, use the following best practices to update or delete it later:

• Save the rule ID returned in the POST request on your server, and rely on this ID for subsequent update and delete operations.
• To ensure that you can still obtain the rule ID under poor network conditions, set the timeout for the POST request to 20 seconds or higher. Make sure that the timeout is set to no less than 5 seconds.
• In case the POST request times out or returns a 504 error, use the response of the GET method to obtain the rule ID. If the rule exists, it indicates that the POST request was successful, and you can save the rule ID on your server.

Authorization

This endpoint requires Basic authentication.

Request example

Test this request in Postman or use one of the following code examples:

• Curl
• Node.js
• Python

_15

curl --request POST \

_15

--url https://api.sd-rtn.com/dev/v1/kicking-rule \

_15

--header 'Accept: application/json' \

_15

--header 'Authorization: Basic <your_base64_encoded_credentials>' \

_15

--header 'Content-Type: application/json' \

_15

--data '{

_15

"appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",

_15

"cname": "channel1",

_15

"uid": 589517928,

_15

"ip": "",

_15

"time": 60,

_15

"privileges": [

_15

"join_channel"

_15

]

_15

}'

Response example

_4

{

_4

"status": "success",

_4

"id": 1953

_4

}