Skip to main content

Update expiration time

This method updates the expiration time of a specified banning rule.

Prototype

  • Method: PUT
  • Endpoint: https://api.agora.io/dev/v1/kicking-rule

Request parameters

Request header

The Content-Type field in all HTTP request headers is application/json. All requests and responses are in JSON format. All request URLs and request bodies are case-sensitive.

The Agora Channel Management RESTful APIs only support HTTPS. Before sending HTTP requests, you must generate a Base64-encoded credential with the Customer ID and Customer Secret provided by Agora, and pass the credential to the Authorization field in the HTTP request header. See RESTful authentication for details.

Request body

Pass in the following parameters in the request body:

ParameterTypeRequired/OptionalDescription
appidStringRequiredThe 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.
  • idNumberRequiredThe ID of the rule that you want to update.
    timeNumberRequiredThe time duration (in minutes) to ban the user. The value range is [1,1440].

    Note

  • If the set value is between 0 and 1, Agora automatically sets the value to 1.
  • If the set value is greater than 1440, Agora automatically sets the value to 1440.
  • If the set value is 0, the banning rule does not take effect. The server sets all users that conform to the rule offline, and users can log in again to rejoin the channel.
  • Use either time or time_in_seconds. If you set both parameters, the time_in_seconds parameter takes effect; if you set neither of these parameters, the Agora server automatically sets the banning time duration to 60 minutes, that is, 3600 seconds.
  • time_in_secondsNumberRequiredThe time duration (in seconds) to ban the user. The value range is [10,86430].

    Note

  • If the set value is between 0 and 10, Agora automatically sets the value to 10.
  • If the set value is greater than 86430, Agora automatically sets the value to 86430.
  • If the set value is 0, the banning rule does not take effect. The server sets all users that conform to the rule offline, and users can log in again to rejoin the channel.
  • Use either time or time_in_seconds. If you set both parameters, the time_in_seconds parameter takes effect; if you set neither of these parameters, the Agora server automatically sets the banning time duration to 60 minutes, that is, 3600 seconds.
  • Request examples

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

    JSON
    {  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",  "id": 1953,  "time": 60}
    Shell
    • curl
      curl --request PUT \               --url http://api.sd-rtn.com/dev/v1/kicking-rule \               --header 'Accept: application/json' \               --header 'Authorization: ' \               --header 'Content-Type: application/json' \               --data '{               "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",               "id": 1953,               "time": 60             }'
    • HTTPie
      echo '{  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",  "id": 1953,  "time": 60}' |  \  http PUT http://api.sd-rtn.com/dev/v1/kicking-rule \  Accept:application/json \  Authorization:'' \  Content-Type:application/json
    • wget
      wget --quiet \  --method PUT \  --header 'Authorization: ' \  --header 'Content-Type: application/json' \  --header 'Accept: application/json' \  --body-data '{  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",  "id": 1953,  "time": 60}' \  --output-document \  - http://api.sd-rtn.com/dev/v1/kicking-rule
    Javascript
    • Fetch
      const url = 'http://api.sd-rtn.com/dev/v1/kicking-rule';const options = {  method: 'PUT',  headers: {    Authorization: '',    'Content-Type': 'application/json',    Accept: 'application/json'  },  body: '{"appid":"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2","id":1953,"time":60}'};try {  const response = await fetch(url, options);  const data = await response.json();  console.log(data);} catch (error) {  console.error(error);}
    • XMLHTTPRequest
      const data = JSON.stringify({  appid: '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',  id: 1953,  time: 60});const xhr = new XMLHttpRequest();xhr.withCredentials = true;xhr.addEventListener('readystatechange', function () {  if (this.readyState === this.DONE) {    console.log(this.responseText);  }});xhr.open('PUT', 'http://api.sd-rtn.com/dev/v1/kicking-rule');xhr.setRequestHeader('Authorization', '');xhr.setRequestHeader('Content-Type', 'application/json');xhr.setRequestHeader('Accept', 'application/json');xhr.send(data);
    • jQuery
      const settings = {  async: true,  crossDomain: true,  url: 'http://api.sd-rtn.com/dev/v1/kicking-rule',  method: 'PUT',  headers: {    Authorization: '',    'Content-Type': 'application/json',    Accept: 'application/json'  },  processData: false,  data: '{  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",  "id": 1953,  "time": 60}'};$.ajax(settings).done(function (response) {  console.log(response);});
    • Axios
      import axios from 'axios';const options = {  method: 'PUT',  url: 'http://api.sd-rtn.com/dev/v1/kicking-rule',  headers: {    Authorization: '',    'Content-Type': 'application/json',    Accept: 'application/json'  },  data: {appid: '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2', id: 1953, time: 60}};try {  const { data } = await axios.request(options);  console.log(data);} catch (error) {  console.error(error);}
    Node
    • Native
      const http = require('http');const options = {  method: 'PUT',  hostname: 'api.sd-rtn.com',  port: null,  path: '/dev/v1/kicking-rule',  headers: {    Authorization: '',    'Content-Type': 'application/json',    Accept: 'application/json'  }};const req = http.request(options, function (res) {  const chunks = [];  res.on('data', function (chunk) {    chunks.push(chunk);  });  res.on('end', function () {    const body = Buffer.concat(chunks);    console.log(body.toString());  });});req.write(JSON.stringify({appid: '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2', id: 1953, time: 60}));req.end();
    • Request
      const request = require('request');const options = {  method: 'PUT',  url: 'http://api.sd-rtn.com/dev/v1/kicking-rule',  headers: {    Authorization: '',    'Content-Type': 'application/json',    Accept: 'application/json'  },  body: {appid: '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2', id: 1953, time: 60},  json: true};request(options, function (error, response, body) {  if (error) throw new Error(error);  console.log(body);});
    • Unirest
      const unirest = require('unirest');const req = unirest('PUT', 'http://api.sd-rtn.com/dev/v1/kicking-rule');req.headers({  Authorization: '',  'Content-Type': 'application/json',  Accept: 'application/json'});req.type('json');req.send({  appid: '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',  id: 1953,  time: 60});req.end(function (res) {  if (res.error) throw new Error(res.error);  console.log(res.body);});
    • Fetch
      const fetch = require('node-fetch');const url = 'http://api.sd-rtn.com/dev/v1/kicking-rule';const options = {  method: 'PUT',  headers: {    Authorization: '',    'Content-Type': 'application/json',    Accept: 'application/json'  },  body: '{"appid":"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2","id":1953,"time":60}'};try {  const response = await fetch(url, options);  const data = await response.json();  console.log(data);} catch (error) {  console.error(error);}
    • Axios
      const axios = require('axios').default;const options = {  method: 'PUT',  url: 'http://api.sd-rtn.com/dev/v1/kicking-rule',  headers: {    Authorization: '',    'Content-Type': 'application/json',    Accept: 'application/json'  },  data: {appid: '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2', id: 1953, time: 60}};try {  const { data } = await axios.request(options);  console.log(data);} catch (error) {  console.error(error);}
    Python
    • Python 3
      import http.clientconn = http.client.HTTPConnection("api.sd-rtn.com")payload = "{  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",  "id": 1953,  "time": 60}"headers = {    'Authorization': "",    'Content-Type': "application/json",    'Accept': "application/json"}conn.request("PUT", "/dev/v1/kicking-rule", payload, headers)res = conn.getresponse()data = res.read()print(data.decode("utf-8"))
    • Requests
      import requestsurl = "http://api.sd-rtn.com/dev/v1/kicking-rule"payload = {    "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",    "id": 1953,    "time": 60}headers = {    "Authorization": "",    "Content-Type": "application/json",    "Accept": "application/json"}response = requests.put(url, json=payload, headers=headers)print(response.json())
    Go
    package main    import (    	  "fmt"    	  "strings"    	  "net/http"    	  "io"    )    func main() {    	  url := "http://api.sd-rtn.com/dev/v1/kicking-rule"    	  payload := strings.NewReader("{\n  \"appid\": \"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2\",\n  \"id\": 1953,\n  \"time\": 60\n}")    	  req, _ := http.NewRequest("PUT", url, payload)    	  req.Header.Add("Authorization", "")    	  req.Header.Add("Content-Type", "application/json")    	  req.Header.Add("Accept", "application/json")    	  res, _ := http.DefaultClient.Do(req)    	  defer res.Body.Close()    	  body, _ := io.ReadAll(res.Body)    	  fmt.Println(res)    	  fmt.Println(string(body))    }
    C
    CURL *hnd = curl_easy_init();curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "PUT");curl_easy_setopt(hnd, CURLOPT_URL, "http://api.sd-rtn.com/dev/v1/kicking-rule");struct curl_slist *headers = NULL;headers = curl_slist_append(headers, "Authorization: ");headers = curl_slist_append(headers, "Content-Type: application/json");headers = curl_slist_append(headers, "Accept: application/json");curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\n  \"appid\": \"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2\",\n  \"id\": 1953,\n  \"time\": 60\n}");CURLcode ret = curl_easy_perform(hnd);
    Objective-C
    #import <Foundation/Foundation.h>NSDictionary *headers = @{ @"Authorization": @"",                           @"Content-Type": @"application/json",                           @"Accept": @"application/json" };NSDictionary *parameters = @{ @"appid": @"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",                              @"id": @1953,                              @"time": @60 };NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"http://api.sd-rtn.com/dev/v1/kicking-rule"]                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy                                                   timeoutInterval:10.0];[request setHTTPMethod:@"PUT"];[request setAllHTTPHeaderFields:headers];[request setHTTPBody:postData];NSURLSession *session = [NSURLSession sharedSession];NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {                                                if (error) {                                                    NSLog(@"%@", error);                                                } else {                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;                                                    NSLog(@"%@", httpResponse);                                                }                                            }];[dataTask resume];
    OCaml
    open Cohttp_lwt_unixopen Cohttpopen Lwtlet uri = Uri.of_string "http://api.sd-rtn.com/dev/v1/kicking-rule" inlet headers = Header.add_list (Header.init ()) [  ("Authorization", "");  ("Content-Type", "application/json");  ("Accept", "application/json");] inlet body = Cohttp_lwt_body.of_string "{\n  \"appid\": \"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2\",\n  \"id\": 1953,\n  \"time\": 60\n}" inClient.call ~headers ~body `PUT uri>>= fun (res, body_stream) ->  (* Do stuff with the result *)
    C#
    • HTTPClient
      using System.Net.Http.Headers;var client = new HttpClient();var request = new HttpRequestMessage{    Method = HttpMethod.Put,    RequestUri = new Uri("http://api.sd-rtn.com/dev/v1/kicking-rule"),    Headers =    {        { "Authorization", "" },        { "Accept", "application/json" },    },    Content = new StringContent("{\n  \"appid\": \"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2\",\n  \"id\": 1953,\n  \"time\": 60\n}")    {        Headers =        {            ContentType = new MediaTypeHeaderValue("application/json")        }    }};using (var response = await client.SendAsync(request)){    response.EnsureSuccessStatusCode();    var body = await response.Content.ReadAsStringAsync();    Console.WriteLine(body);}
    • RestSharp
      var client = new RestClient("http://api.sd-rtn.com/dev/v1/kicking-rule");var request = new RestRequest(Method.PUT);request.AddHeader("Authorization", "");request.AddHeader("Content-Type", "application/json");request.AddHeader("Accept", "application/json");request.AddParameter("application/json", "{\n  \"appid\": \"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2\",\n  \"id\": 1953,\n  \"time\": 60\n}", ParameterType.RequestBody);IRestResponse response = client.Execute(request);
    Java
    • AsyncHttp
      AsyncHttpClient client = new DefaultAsyncHttpClient();client.prepare("PUT", "http://api.sd-rtn.com/dev/v1/kicking-rule")  .setHeader("Authorization", "")  .setHeader("Content-Type", "application/json")  .setHeader("Accept", "application/json")  .setBody("{  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",  "id": 1953,  "time": 60}")  .execute()  .toCompletableFuture()  .thenAccept(System.out::println)  .join();client.close();
    • NetHttp
      HttpRequest request = HttpRequest.newBuilder()    .uri(URI.create("http://api.sd-rtn.com/dev/v1/kicking-rule"))    .header("Authorization", "")    .header("Content-Type", "application/json")    .header("Accept", "application/json")    .method("PUT", HttpRequest.BodyPublishers.ofString("{\n  \"appid\": \"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2\",  \"id\": 1953,\n  "time": 60\n}"))    .build();HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());System.out.println(response.body());
    • OkHttp
      OkHttpClient client = new OkHttpClient();MediaType mediaType = MediaType.parse("application/json");RequestBody body = RequestBody.create(mediaType, "{\n  \"appid\": \"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2\",\n  \"id\": 1953,\n  \"time\": 60\n}");Request request = new Request.Builder()  .url("http://api.sd-rtn.com/dev/v1/kicking-rule")  .put(body)  .addHeader("Authorization", "")  .addHeader("Content-Type", "application/json")  .addHeader("Accept", "application/json")  .build();Response response = client.newCall(request).execute();
    • Unirest
      HttpResponse<String> response = Unirest.put("http://api.sd-rtn.com/dev/v1/kicking-rule")  .header("Authorization", "")  .header("Content-Type", "application/json")  .header("Accept", "application/json")  .body("{\n  \"appid\": \"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2\",\n  \"id\": 1953,\n  \"time\": 60\n}")  .asString();
    Http 1.1
    PUT /dev/v1/kicking-rule HTTP/1.1Authorization:Content-Type: application/jsonAccept: application/jsonHost: api.sd-rtn.comContent-Length: 77{  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",  "id": 1953,  "time": 60}
    Clojure
    (require '[clj-http.client :as client])(client/put "http://api.sd-rtn.com/dev/v1/kicking-rule" {:headers {:Authorization ""}                                                         :content-type :json                                                         :form-params {:appid "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2"                                                                       :id 1953                                                                       :time 60}                                                         :accept :json})
    Kotlin
    val client = OkHttpClient()val mediaType = MediaType.parse("application/json")val body = RequestBody.create(mediaType, "{\n  \"appid\": \"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2\",\n  \"id\": 1953,\n  \"time\": 60\n}")val request = Request.Builder()  .url("http://api.sd-rtn.com/dev/v1/kicking-rule")  .put(body)  .addHeader("Authorization", "")  .addHeader("Content-Type", "application/json")  .addHeader("Accept", "application/json")  .build()val response = client.newCall(request).execute()
    PHP
    • cURL
      <?php$curl = curl_init();curl_setopt_array($curl, [  CURLOPT_URL => "http://api.sd-rtn.com/dev/v1/kicking-rule",  CURLOPT_RETURNTRANSFER => true,  CURLOPT_ENCODING => "",  CURLOPT_MAXREDIRS => 10,  CURLOPT_TIMEOUT => 30,  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,  CURLOPT_CUSTOMREQUEST => "PUT",  CURLOPT_POSTFIELDS => json_encode([    'appid' => '4855xxxxxxxxxxxxxxxxxxxxxxxxeae2',    'id' => 1953,    'time' => 60  ]),  CURLOPT_HTTPHEADER => [    "Accept: application/json",    "Authorization: ",    "Content-Type: application/json"  ],]);$response = curl_exec($curl);$err = curl_error($curl);curl_close($curl);if ($err) {  echo "cURL Error #:" . $err;} else {  echo $response;}
    • Guzzle
      <?php$client = new GuzzleHttp\Client();$response = $client->request('PUT', 'http://api.sd-rtn.com/dev/v1/kicking-rule', [  'body' => '{  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",  "id": 1953,  "time": 60  }',  'headers' => [    'Accept' => 'application/json',    'Authorization' => '',    'Content-Type' => 'application/json',  ],]);echo $response->getBody();
    PowerShell
    • WebRequest
      $headers=@{}$headers.Add("Authorization", "")$headers.Add("Content-Type", "application/json")$headers.Add("Accept", "application/json")$response = Invoke-WebRequest -Uri 'http://api.sd-rtn.com/dev/v1/kicking-rule' -Method PUT -Headers $headers -ContentType 'application/json' -Body '{  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",  "id": 1953,  "time": 60}'
    • RestMethod
      $headers=@{}$headers.Add("Authorization", "")$headers.Add("Content-Type", "application/json")$headers.Add("Accept", "application/json")$response = Invoke-RestMethod -Uri 'http://api.sd-rtn.com/dev/v1/kicking-rule' -Method PUT -Headers $headers -ContentType 'application/json' -Body '{  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",  "id": 1953,  "time": 60}'
    R
    library(httr)url <- "http://api.sd-rtn.com/dev/v1/kicking-rule"payload <- "{\n  \"appid\": \"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2\",\n  \"id\": 1953,\n  \"time\": 60\n}"encode <- "json"response <- VERB("PUT", url, body = payload, add_headers('Authorization' = ''), content_type("application/json"), accept("application/json"), encode = encode)content(response, "text")
    Ruby
    require 'uri'require 'net/http'url = URI("http://api.sd-rtn.com/dev/v1/kicking-rule")http = Net::HTTP.new(url.host, url.port)request = Net::HTTP::Put.new(url)request["Authorization"] = ''request["Content-Type"] = 'application/json'request["Accept"] = 'application/json'request.body = "{\n  \"appid\": \"4855xxxxxxxxxxxxxxxxxxxxxxxxeae2\",\n  \"id\": 1953,\n  \"time\": 60\n}"response = http.request(request)puts response.read_body
    Swift
    import Foundationlet headers = [  "Authorization": "",  "Content-Type": "application/json",  "Accept": "application/json"]let parameters = [  "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",  "id": 1953,  "time": 60] as [String : Any]let postData = JSONSerialization.data(withJSONObject: parameters, options: [])let request = NSMutableURLRequest(url: NSURL(string: "http://api.sd-rtn.com/dev/v1/kicking-rule")! as URL,                                        cachePolicy: .useProtocolCachePolicy,                                    timeoutInterval: 10.0)request.httpMethod = "PUT"request.allHTTPHeaderFields = headersrequest.httpBody = postData as Datalet session = URLSession.sharedlet dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in  if (error != nil) {    print(error as Any)  } else {    let httpResponse = response as? HTTPURLResponse    print(httpResponse)  }})dataTask.resume()

    Response parameters

    For details about possible response status codes, see Response status codes.

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

    If the status code is 200, the request succeeds, and the response body includes the following parameters:

    ParameterTypeDescription
    statusStringThe status of this request. success means the request succeeds.
    resultObjectThe result of the update:
  • id: String. The rule ID.
  • ts: String. The UTC time when the rule expires.
  • Response example

    The following is a response example for a successful request:

    {  "status": "success",  "result": {    "id": 1953,    "ts": "2018-01-09T08:45:54.545Z"  }}
    vundefined