Bans

You can use the API to get, set, or delete a ban.

JSON format

Bans are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
created_at	string	true	false	The timestamp of creation of the ban. This can be null for older bans.
id	integer	true	false	The ID of the ban
ip_address	string	true	false	The IP address of the banned visitor
reason	string	true	false	The reason for the ban
type	string	true	false	The type of the ban
visitor_id	string	true	false	The ID of the banned visitor
visitor_name	string	true	false	The display name of the banned visitor

Example

{  "created_at": "2020-03-14T15:09:26Z",  "id": 1,  "ip_address": "87.230.12.41",  "reason": "Spammer",  "type": "I",  "visitor_id": "",  "visitor_name": ""}

List Bans

GET /api/v2/chat/bans

Lists the bans for the account. Returns up to 1000 results per page. This endpoint uses cursor-based pagination. See Pagination in List Agents.

Allowed for

Administrator

Parameters

Name	Type	In	Required	Description
limit	integer	Query	false	Number of records that will be returned by the endpoint. Default to 10.
max_id	integer	Query	false	Use the max_id parameter to paginate backward through the recordset
since_id	integer	Query	false	Use the since_id parameter to paginate forward through the recordset

Code Samples

curl

curl "https://{subdomain}.zendesk.com/api/v2/chat/bans?since_id=5&limit=2" \  -v -H "Authorization: Bearer {token}"

import (	"fmt"	"io"	"net/http")
func main() {	url := "https://subdomain.zendesk.com/api/v2/chat/bans?limit=20&max_id=20&since_id=10"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}

Java

import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://subdomain.zendesk.com/api/v2/chat/bans")		.newBuilder()		.addQueryParameter("limit", "20")		.addQueryParameter("max_id", "20")		.addQueryParameter("since_id", "10");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var config = {  method: 'GET',  url: 'https://subdomain.zendesk.com/api/v2/chat/bans',  headers: {	'Content-Type': 'application/json',  },  params: {    'limit': '20',    'max_id': '20',    'since_id': '10',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});

Python

import requests
url = "https://subdomain.zendesk.com/api/v2/chat/bans?limit=20&max_id=20&since_id=10"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)

Ruby

require "net/http"uri = URI("https://subdomain.zendesk.com/api/v2/chat/bans")uri.query = URI.encode_www_form("limit": "20", "max_id": "20", "since_id": "10")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK

// Status 200 OK
{  "ip_address": [    {      "created_at": "2020-03-14T15:09:26Z",      "id": 8,      "ip_address": "242.211.134.60",      "reason": "Spammer"    }  ],  "visitor": [    {      "created_at": "2020-03-14T15:09:26Z",      "id": 5,      "reason": "Spammer",      "visitor_id": "2",      "visitor_name": "John"    }  ]}

List Banned IP Addresses

GET /api/v2/chat/bans/ip

Returns a list of banned visitor IP addresses for your account.

Allowed for

Administrator

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/chat/bans/ip \  -v -H "Authorization: Bearer {token}"

import (	"fmt"	"io"	"net/http")
func main() {	url := "https://subdomain.zendesk.com/api/v2/chat/bans/ip"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}

Java

import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://subdomain.zendesk.com/api/v2/chat/bans/ip")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var config = {  method: 'GET',  url: 'https://subdomain.zendesk.com/api/v2/chat/bans/ip',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});

Python

import requests
url = "https://subdomain.zendesk.com/api/v2/chat/bans/ip"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)

Ruby

require "net/http"uri = URI("https://subdomain.zendesk.com/api/v2/chat/bans/ip")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK

// Status 200 OK
[  "155.69.127.97",  "155.69.127.98"]

Show Ban

GET /api/v2/chat/bans/{ban_id}

Fetches a ban by its ID.

Allowed for

Administrator

Parameters

Name	Type	In	Required	Description
ban_id	integer	Path	true	The ID of the ban

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/chat/bans/(ban_id) \  -v -H "Authorization: Bearer {token}"

import (	"fmt"	"io"	"net/http")
func main() {	url := "https://subdomain.zendesk.com/api/v2/chat/bans/1"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}

Java

import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://subdomain.zendesk.com/api/v2/chat/bans/1")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var config = {  method: 'GET',  url: 'https://subdomain.zendesk.com/api/v2/chat/bans/1',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});

Python

import requests
url = "https://subdomain.zendesk.com/api/v2/chat/bans/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)

Ruby

require "net/http"uri = URI("https://subdomain.zendesk.com/api/v2/chat/bans/1")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK

// Status 200 OK
{  "created_at": "2020-03-14T15:09:26Z",  "id": 1,  "ip_address": "87.230.12.41",  "reason": "Spammer",  "type": "I",  "visitor_id": "",  "visitor_name": ""}

Create Ban

POST /api/v2/chat/bans

Creates a ban either by visitor ID or by IP address.

Allowed for

Administrator

Code Samples

curl

# To ban a visitorcurl https://{subdomain}.zendesk.com/api/v2/chat/bans \  -d '{        "visitor_id": "12345",        "reason": "Spammer"      }' \  -v -H "Authorization: Bearer {token}" \  -H "Content-Type: application/json" -X POST
# Or, to ban an IPcurl https://{subdomain}.zendesk.com/api/v2/chat/bans \  -d '{        "ip_address": "192.123.123.5",        "reason": "Spammer"      }' \  -v -H "Authorization: Bearer {token}" \  -H "Content-Type: application/json" -X POST

import (	"fmt"	"io"	"net/http")
func main() {	url := "https://subdomain.zendesk.com/api/v2/chat/bans"	method := "POST"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}

Java

import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://subdomain.zendesk.com/api/v2/chat/bans")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var config = {  method: 'POST',  url: 'https://subdomain.zendesk.com/api/v2/chat/bans',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});

Python

import requests
url = "https://subdomain.zendesk.com/api/v2/chat/bans"headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	headers=headers)
print(response.text)

Ruby

require "net/http"uri = URI("https://subdomain.zendesk.com/api/v2/chat/bans")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

201 Created

// Status 201 Created
{  "created_at": "2020-03-14T15:09:26Z",  "id": 1,  "ip_address": "",  "reason": "Spammer",  "type": "V",  "visitor_id": "12345",  "visitor_name": "Agent Smith"}

Delete Ban

DELETE /api/v2/chat/bans/{ban_id}

Deletes a ban.

Allowed for

Administrator

Parameters

Name	Type	In	Required	Description
ban_id	integer	Path	true	The ID of the ban

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/chat/bans/{ban_id} \  -v -H "Authorization: Bearer {token}" -X DELETE

import (	"fmt"	"io"	"net/http")
func main() {	url := "https://subdomain.zendesk.com/api/v2/chat/bans/1"	method := "DELETE"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}

Java

import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://subdomain.zendesk.com/api/v2/chat/bans/1")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("DELETE", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var config = {  method: 'DELETE',  url: 'https://subdomain.zendesk.com/api/v2/chat/bans/1',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});

Python

import requests
url = "https://subdomain.zendesk.com/api/v2/chat/bans/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"DELETE",	url,	headers=headers)
print(response.text)

Ruby

require "net/http"uri = URI("https://subdomain.zendesk.com/api/v2/chat/bans/1")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

204 No Content

// Status 204 No Content
null

Chat API

Real Time Chat API

Chat Conversations API

Bans

JSON format

Example

List Bans

Allowed for

Parameters

Code Samples

Example response(s)

List Banned IP Addresses

Allowed for

Code Samples

Example response(s)

Show Ban

Allowed for

Parameters

Code Samples

Example response(s)

Create Ban

Allowed for

Code Samples

Example response(s)

Delete Ban

Allowed for

Parameters

Code Samples

Example response(s)