If you are participating in the Zendesk messaging beta, some Chat APIs are not supported. See How Zendesk messaging impacts Chat APIs for more information.

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/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

  • Owner
  • 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

Using curl

curl "https://www.zopim.com/api/v2/bans?since_id=5&limit=2" \  -v -u {email_address}:{password}

Example Response

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"    }  ]}

Create Ban

  • POST /api/v2/bans

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

Allowed for

  • Owner
  • Administrator

Using curl

# To ban a visitorcurl https://www.zopim.com/api/v2/bans \  -d '{        "visitor_id": "12345",        "reason": "Spammer"      }' \  -v -u {email_address}:{password} \  -X POST -H "Content-Type: application/json"
# Or, to ban an IPcurl https://www.zopim.com/api/v2/bans \  -d '{        "ip_address": "192.123.123.5",        "reason": "Spammer"      }' \  -v -u {email_address}:{password} \  -X POST -H "Content-Type: application/json"

Example Response

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"}

List Banned IP Addresses

  • GET /api/v2/bans/ip

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

Allowed for

  • Owner
  • Administrator

Using curl

curl https://www.zopim.com/api/v2/bans/ip \  -v -u {email_address}:{password}

Example Response

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

Show Ban

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

Fetches a ban by its ID.

Allowed for

  • Owner
  • Administrator

Parameters

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

Using curl

curl https://www.zopim.com/api/v2/bans/(ban_id) \  -v -u {email_address}:{password}

Example Response

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": ""}

Delete Ban

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

Deletes a ban.

Allowed for

  • Owner
  • Administrator

Parameters

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

Using curl

curl https://www.zopim.com/api/v2/bans/{ban_id} \  -v -u {email_address}:{password} -X DELETE

Example Response

Status 204 No Content