Routing Settings
You can use this API to get or modify chat routing settings. For more information, see Setting up chat routing in the Chat Help Center.
JSON Format
Account Routing Setting Payload
Account-level routing settings are represented as a nested JSON object.
Field Name | Type | Read-only | Description |
---|---|---|---|
routing_mode | string | no | Routing mode of the account. Possible values: "broadcast", "assigned" or "hybrid" |
chat_limit | object | no | See Chat limit property |
skill_routing | object | no | See Skill routing property |
reassignment | object | no | See Reassignment property |
auto_idle | object | no | See Auto idle property |
auto_accept | object | no | See Auto accept property |
Chat limit property
Field Name | Type | Read-only | Description |
---|---|---|---|
enabled | boolean | no | Enable chat limit |
limit | integer | no | Number of concurrent chats each agent can take at once. Possible values: Integers from 0 to 20 |
limit_type | string | no | The scope to which the chat limit is applied to. When set to "agent", each agent will have their own individual chat limit. Possible values: "account" or "agent" |
allow_agent_override | boolean | no | Allow each agent to set their own chat limit under Personal settings |
Skill routing property
Field Name | Type | Read-only | Description |
---|---|---|---|
enabled | boolean | no | Enable skill routing |
max_wait_time | integer | no | Maximum time in seconds to wait before assigning the chat to an agent with matching skills. Only applicable if routing_mode is not "broadcast" and skill_routing.enabled is true. Possible values: Integers from 5 to 300 |
Reassignment property
Field Name | Type | Read-only | Description |
---|---|---|---|
enabled | boolean | no | Enable reassignment |
timeout | integer | no | Time (in seconds) with no response before a chat is assigned to another agent. Possible values: Integers from 10 to 120 |
Auto idle property
Field Name | Type | Read-only | Description |
---|---|---|---|
enabled | boolean | no | Enable automatic idle |
reassignments_before_idle | integer | no | Number of chats reassigned before the agent's status is changed. Possible values: Integers from 1 to 20 |
new_status | string | no | Status when being idle. Possible values: "away" or "invisible" |
Auto accept property
Field Name | Type | Read-only | Description |
---|---|---|---|
enabled | boolean | no | Enable auto accept. This property is applicable only if the account has Agent Workspace enabled |
Example payload:
{
"routing_mode": "broadcast",
"chat_limit": {
"limit": 3,
"enabled": false,
"allow_agent_override": false,
"limit_type": "account"
},
"auto_accept": {
"enabled": false
},
"auto_idle": {
"enabled": true,
"reassignments_before_idle": 3,
"new_status": "away"
},
"skill_routing": {
"enabled": true,
"max_wait_time": 30
},
"reassignment": {
"enabled": false,
"timeout": 30
}
}
Agent Routing Setting Payload
Agent-level routing settings are represented as a nested JSON object.
Field Name | Type | Read-only | Description |
---|---|---|---|
skills | array/object | no | Skill IDs assigned to the agent. See skills property |
routing | object | no | See Routing property |
Routing property
Field Name | Type | Read-only | Description |
---|---|---|---|
chat_limit | integer | no | Agent's chat limit if account's chat_limit.limit_type is "agent" or chat_limit.allow_agent_override is true. Possible values: Integers from 0 to 20 |
Example payload:
{
"skills": [1, 2, 3],
"routing": {
"chat_limit": 3
}
}
skills property
With agent routing settings, you can update agents' skills incrementally so you have more flexibility when adding or removing skills.
The API always returns skills
as an array of skill IDs as integers. Example:
{
"skills": [1, 2, 3],
"routing": {
"chat_limit": 3
}
}
To replace all existing skills of an agent with a new set of skill ids,
provide a skills
array of skill IDs in the request payload.
For example, the payload below will remove all existing skills and set skill IDs to be 1, 2 and 3.
{
"skills": [1, 2, 3]
}
To add to or remove skills from an agent's existing skills, you can provide
skills
as an object. Use skill IDs as keys (see the
Skills API
for instructions on how to fetch skill IDs). Provide true as the value if you
want to add the skill ID to the existing skills or null if you want to
remove the skill ID.
The following example adds one skill and removes another.
Existing skills:
{
"skills": [1, 2, 3]
}
The following payload adds the skill with ID 5
and removes the skill with ID 3
from the existing skills:
{
"skills": {
"5": true,
"3": null
}
}
Updated skills:
{
"skills": [1, 2, 5]
}
Show Account Routing Settings
GET /api/v2/chat/routing_settings/account
Gets the routing settings of the account.
Allowed for
- Agent
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/chat/routing_settings/account \
-v -H "Authorization: Bearer {token}"
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://subdomain.zendesk.com/api/v2/chat/routing_settings/account"
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/routing_settings/account")
.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/routing_settings/account',
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/routing_settings/account"
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/routing_settings/account")
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
{
"data": {
"auto_accept": {
"enabled": false
},
"auto_idle": {
"enabled": true,
"new_status": "away",
"reassignments_before_idle": 3
},
"chat_limit": {
"allow_agent_override": false,
"enabled": false,
"limit": 3,
"limit_type": "account"
},
"reassignment": {
"enabled": false,
"timeout": 30
},
"routing_mode": "broadcast",
"skill_routing": {
"enabled": true,
"max_wait_time": 30
}
}
}
Update Account Routing Settings
PATCH /api/v2/chat/routing_settings/account
Updates the routing settings of the account. You may include only the fields you want to modify. Absent fields will not be changed.
Auto accept can't be enabled in broadcast routing mode, when reassignment is enabled, or auto idle is enabled.
Allowed for
- Administrator
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/chat/routing_settings/account \
-d '{
"routing_mode": "broadcast",
"chat_limit": {
"enabled": true
},
"reassignment": {
"enabled": true,
"timeout": 60
}
}' \
-v -H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" -X PATCH
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://subdomain.zendesk.com/api/v2/chat/routing_settings/account"
method := "PATCH"
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/routing_settings/account")
.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
""");
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("PATCH", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'PATCH',
url: 'https://subdomain.zendesk.com/api/v2/chat/routing_settings/account',
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/routing_settings/account"
headers = {
"Content-Type": "application/json",
}
response = requests.request(
"PATCH",
url,
headers=headers
)
print(response.text)
Ruby
require "net/http"
uri = URI("https://subdomain.zendesk.com/api/v2/chat/routing_settings/account")
request = Net::HTTP::Patch.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
{
"data": {
"auto_accept": {
"enabled": false
},
"auto_idle": {
"enabled": true,
"new_status": "away",
"reassignments_before_idle": 3
},
"chat_limit": {
"allow_agent_override": false,
"enabled": true,
"limit": 3,
"limit_type": "account"
},
"reassignment": {
"enabled": true,
"timeout": 60
},
"routing_mode": "broadcast",
"skill_routing": {
"enabled": true,
"max_wait_time": 30
}
}
}
List Agents' Routing Settings
GET /api/v2/chat/routing_settings/agents
Gets the routing settings of all agents.
Pagination
This endpoint uses cursor-based pagination. See Pagination in List Agents.
Allowed for
- Agent
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/routing_settings/agents \
-v -H "Authorization: Bearer {token}"
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://subdomain.zendesk.com/api/v2/chat/routing_settings/agents?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/routing_settings/agents")
.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/routing_settings/agents',
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/routing_settings/agents?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/routing_settings/agents")
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
{
"data": {
"19174": {
"routing": {
"chat_limit": 3
},
"skills": [
1,
2,
3
]
},
"19175": {
"routing": {
"chat_limit": 5
},
"skills": [
5,
6
]
}
}
}
Show Agent Routing Settings
GET /api/v2/chat/routing_settings/agents/{agent_id}
GET /api/v2/chat/routing_settings/agents/me
Gets the routing settings of an agent. An authenticated agent can get their own
settings by replacing {agent_id}
with me
.
Allowed for
- Agent
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
agent_id | integer | Path | true | The ID of the agent |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/chat/routing_settings/agents/{agent_id} \
-v -H "Authorization: Bearer {token}"
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://subdomain.zendesk.com/api/v2/chat/routing_settings/agents/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/routing_settings/agents/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/routing_settings/agents/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/routing_settings/agents/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/routing_settings/agents/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
{
"data": {
"routing": {
"chat_limit": 3
},
"skills": [
1,
2,
3
]
}
}
Update Agent Routing Settings
PATCH /api/v2/chat/routing_settings/agents/{agent_id}
PATCH /api/v2/chat/routing_settings/agents/me
Updates the routing settings of an agent. An authenticated agent can update
their own settings by replacing {agent_id}
with me
.
Allowed for
- Administrator
- Agent (using
/me
)
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
agent_id | integer | Path | true | The ID of the agent |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/chat/routing_settings/agents/{agent_id} \
-d '{
"skills": [5, 6],
"routing": {
"chat_limit": 5
}
}' \
-v -H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" -X PATCH
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://subdomain.zendesk.com/api/v2/chat/routing_settings/agents/1"
method := "PATCH"
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/routing_settings/agents/1")
.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
""");
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("PATCH", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'PATCH',
url: 'https://subdomain.zendesk.com/api/v2/chat/routing_settings/agents/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/routing_settings/agents/1"
headers = {
"Content-Type": "application/json",
}
response = requests.request(
"PATCH",
url,
headers=headers
)
print(response.text)
Ruby
require "net/http"
uri = URI("https://subdomain.zendesk.com/api/v2/chat/routing_settings/agents/1")
request = Net::HTTP::Patch.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
{
"data": {
"routing": {
"chat_limit": 5
},
"skills": [
5,
6
]
}
}
Batch Update Routing Settings for Multiple Agents
PATCH /api/v2/chat/routing_settings/agents
Batch updates the routing settings for multiple agents.
The payload must be an object with agent IDs as keys and the agent settings updates as values. You may include only the fields you want to modify in the settings update. Absent fields will not be changed.
Rate Limit
This API has a different rate limit. When batch updating agents, every 5 agents in the request body count as 1 request for the purpose of rate limiting. Please adjust the number of agents in one request to avoid getting rate limited.
Example:
Number of agents in one batch | Request count |
---|---|
2 agents | 1 |
5 agents | 1 |
6 agents | 2 |
51 agents | 11 |
Allowed for
- Administrator
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/chat/routing_settings/agents \
-d '{
"19174": {
skills: [8, 9]
},
"19175": {
"routing": {
"chat_limit": 7
}
}
}' \
-v -H "Authorization: Bearer {token}" \
-X PATCH -H "Content-Type: application/json"
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://subdomain.zendesk.com/api/v2/chat/routing_settings/agents"
method := "PATCH"
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/routing_settings/agents")
.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
""");
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("PATCH", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'PATCH',
url: 'https://subdomain.zendesk.com/api/v2/chat/routing_settings/agents',
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/routing_settings/agents"
headers = {
"Content-Type": "application/json",
}
response = requests.request(
"PATCH",
url,
headers=headers
)
print(response.text)
Ruby
require "net/http"
uri = URI("https://subdomain.zendesk.com/api/v2/chat/routing_settings/agents")
request = Net::HTTP::Patch.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
{
"data": {
"19174": {
"routing": {
"chat_limit": 3
},
"skills": [
8,
9
]
},
"19175": {
"routing": {
"chat_limit": 7
},
"skills": [
5,
6
]
}
}
}