Roles

You can use the API to create, get, or set role information.

Note: To assign an agent to a role, please see Agents.

JSON format

Roles are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
description	string	true	false	The description of the role. Note: The description cannot be changed for the Owner, Admin, and Agent roles. You can change it for custom roles
enabled	boolean	true	false	Describes whether the role is enabled. Note: Owner, Admin, and Agent roles cannot be disabled. You can disable custom roles
id	integer	true	false	The ID of the role
members_count	integer	true	false	The number of members on this role
name	string	true	false	The name of the role. Note: The name cannot be changed for the Owner, Admin, and Agent roles. You can change it for custom roles
permissions	object	true	false	The permissions for the role (described below). Note: The permissions cannot be changed for Owner and Admin roles. You can change them for Agent and custom roles. See Permissions

Permissions

The permissions property is an object containing permission settings for a role.

Name	Type	Possible values	Description
visitors_seen	string	"account", "department", "own"	Permission to see visitors on your site
proactive_chatting	string	"listen-join", "listen", "own"	Permission to listen to chat and/or proactively join a chat
edit_visitor_information	boolean	true, false	Can edit user name, email, and phone via the chat panel or history
edit_visitor_notes	boolean	true, false	Can edit notes via the chat panel or history
view_past_chats	string	"account", "department", "own", "none"	Permission to view past chats
edit_chat_tags	boolean	true, false	Can add or remove chat tags for past chats in history
manage_bans	string	"account", "none"	Can temporarily ban visitors via browser cookies while in a chat or manage more permanent bans by IP
access_analytics	string	"account", "none"	Can access Analytics and Email Reports (under Personal Settings)
view_monitor	string	"account", "none"	Can view real-time metrics on Monitor across the whole account
edit_department_agents	string	"account", "none"	Can add or edit agents in departments
set_agent_chat_limit	string	"account", "none"	Can set chat limits for agents if agent limits are enabled
manage_shortcuts	string	"account", "none"	Can add, edit, or delete shortcuts that can be used by anyone while chatting with visitors

Permission string values

• "listen" - Listen to any chat visible to the agent
• "listen-join" - Listen to any chat and proactively join a chat with any visitor visible to the agent
• "own" - Not able to listen to any chat or proactive chat with any visitor on the Visitor List
• "account" - Permission for the whole account
• "department" - Permission limited to the user's department
• "own" - Permission limited to the user's own information
• "none" - No permission

Example

{
  "description": "The person who set up the account. In addition to agent and administrator\nprivileges, this role can adjust the account's plan, change billing information,\nand cancel the account. Permissions for Owner role cannot be modified.\n",
  "enabled": true,
  "id": 1,
  "members_count": 1,
  "name": "Owner",
  "permissions": {
    "access_analytics": "account",
    "edit_chat_tags": true,
    "edit_department_agents": "account",
    "edit_visitor_information": true,
    "edit_visitor_notes": true,
    "manage_bans": "account",
    "manage_shortcuts": "account",
    "proactive_chatting": "listen-join",
    "set_agent_chat_limit": "account",
    "view_monitor": "account",
    "view_past_chats": "account",
    "visitors_seen": "account"
  }
}

List Roles

• GET /api/v2/chat/roles

Lists all the roles for your account.

Allowed for

• Administrator

Code Samples

curl

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

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/roles"
	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/roles")
		.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/roles',
  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/roles"
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/roles")
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

[
  {
    "description": "The person who set up the account. In addition to agent and administrator privileges, this role can adjust the account's plan, change billing information, and cancel the account. Permissions for Owner role cannot be modified.",
    "enabled": true,
    "id": 1,
    "members_count": 1,
    "name": "Owner",
    "permissions": {
      "access_analytics": "account",
      "edit_chat_tags": true,
      "edit_department_agents": "account",
      "edit_visitor_information": true,
      "edit_visitor_notes": true,
      "manage_bans": "account",
      "manage_shortcuts": "account",
      "proactive_chatting": "listen-join",
      "set_agent_chat_limit": "account",
      "view_monitor": "account",
      "view_past_chats": "account",
      "visitors_seen": "account"
    }
  },
  {
    "description": "Team Lead",
    "enabled": true,
    "id": 8,
    "members_count": 10,
    "name": "Team Lead",
    "permissions": {
      "access_analytics": "account",
      "edit_chat_tags": true,
      "edit_department_agents": "account",
      "edit_visitor_information": true,
      "edit_visitor_notes": true,
      "manage_bans": "account",
      "manage_shortcuts": "account",
      "proactive_chatting": "own",
      "set_agent_chat_limit": "account",
      "view_monitor": "account",
      "view_past_chats": "own",
      "visitors_seen": "own"
    }
  }
]

Show Role

• GET /api/v2/chat/roles/{role_id}

Allowed for

• Administrator

Parameters

Name	Type	In	Required	Description
role_id	integer	Path	true	The ID of the role

Code Samples

curl

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

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/roles/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/roles/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/roles/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/roles/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/roles/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

{
  "description": "The person who set up the account. In addition to agent and administrator privileges, this role can adjust the account's plan, change billing information, and cancel the account. Permissions for Owner role cannot be modified.",
  "enabled": true,
  "id": 1,
  "members_count": 1,
  "name": "Owner",
  "permissions": {
    "access_analytics": "account",
    "edit_chat_tags": true,
    "edit_department_agents": "account",
    "edit_visitor_information": true,
    "edit_visitor_notes": true,
    "manage_bans": "account",
    "manage_shortcuts": "account",
    "proactive_chatting": "listen-join",
    "set_agent_chat_limit": "account",
    "view_monitor": "account",
    "view_past_chats": "account",
    "visitors_seen": "account"
  }
}

Create Role

• POST /api/v2/chat/roles

Allowed for

• Administrator

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/chat/roles \
  -d '{
        "name": "Team Lead"
      }' \
  -v -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" -X POST

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/roles"
	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/roles")
		.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/roles',
  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/roles"
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/roles")
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

{
  "description": "",
  "enabled": true,
  "id": 10000,
  "members_count": 0,
  "name": "Team Lead",
  "permissions": {
    "access_analytics": "none",
    "edit_chat_tags": false,
    "edit_department_agents": "none",
    "edit_visitor_information": true,
    "edit_visitor_notes": true,
    "manage_bans": "account",
    "manage_shortcuts": "account",
    "proactive_chatting": "listen-join",
    "set_agent_chat_limit": "none",
    "view_monitor": "account",
    "view_past_chats": "account",
    "visitors_seen": "account"
  }
}

Update Role

• PUT /api/v2/chat/roles/{role_id}

Allowed for

• Administrator

Parameters

Name	Type	In	Required	Description
role_id	integer	Path	true	The ID of the role

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/chat/roles/{role_id} \
  -d '{
        "enabled": true,
        "description": "Updated description",
        "permissions": {
          "edit_visitor_information": false
        }
      }' \
  -v -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" -X PUT

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/roles/1"
	method := "PUT"
	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/roles/1")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PUT", body)
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'PUT',
  url: 'https://subdomain.zendesk.com/api/v2/chat/roles/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/roles/1"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"PUT",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://subdomain.zendesk.com/api/v2/chat/roles/1")
request = Net::HTTP::Put.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

{
  "description": "Updated description",
  "enabled": true,
  "id": 1,
  "members_count": 1,
  "name": "Owner",
  "permissions": {
    "access_analytics": "account",
    "edit_chat_tags": true,
    "edit_department_agents": "account",
    "edit_visitor_information": false,
    "edit_visitor_notes": true,
    "manage_bans": "account",
    "manage_shortcuts": "account",
    "proactive_chatting": "listen-join",
    "set_agent_chat_limit": "account",
    "view_monitor": "account",
    "view_past_chats": "account",
    "visitors_seen": "account"
  }
}

Delete Role

• DELETE /api/v2/chat/roles/{role_id}

Allowed for

• Administrator

Parameters

Name	Type	In	Required	Description
role_id	integer	Path	true	The ID of the role

Code Samples

curl

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

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/roles/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/roles/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/roles/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/roles/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/roles/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