Routing Settings

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

The table below describes nested key names using dot notation, but you must use a nested JSON object in your request payload. See examples for reference.

Field Name	Type	Read-only	Description
routing_mode	string	no	Routing mode of the account. Possible values: `broadcast`, `assigned` or `hybrid`
chat_limit.enabled	boolean	no	Enable chat limit
chat_limit.limit	integer	no	Number of concurrent chats each agent can take at once. Possible values: Integers from 0 to 20
chat_limit.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`
chat_limit.allow_agent_override	boolean	no	Allow each agent to set their own chat limit under Personal settings
skill_routing.enabled	boolean	no	Enable skill routing
skill_routing.max_wait_time	integer	no	Maximum time (in seconds) to wait for an agent with exact matching skills before assigning chat to the most available agent. Only applicable if `routing_mode` is not `broadcast` and `skill_routing.enabled` is `true`. Possible values: Integers from 5 to 300
reassignment.enabled	boolean	no	Enable reassignment
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.enabled	boolean	no	Enable automatic idle
auto_idle.reassignments_before_idle	integer	no	Number of chats reassigned before the agent's status is changed. Possible values: Integers from 1 to 20
auto_idle.new_status	string	no	Status when being idle. Possible values: `away` or `invisible`

Example payload:

{
  "routing_mode": "broadcast",
  "chat_limit": {
    "limit": 3,
    "enabled": false,
    "allow_agent_override": false,
    "limit_type": "account"
  },
  "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.

The table below describes nested field names using dot notation, but you must use a nested JSON object in your request payload. See examples for reference.

Field Name	Type	Read-only	Description
skills	array/object	no	Skill IDs assigned to the agent. See skills property
routing.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]
}

Get Account Routing Settings

GET /api/v2/routing_settings/account

Gets the routing settings of the account.

Allowed for

Owner
Administrator
Agent

Using cURL

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

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "routing_mode": "broadcast",
    "chat_limit": {
      "limit": 3,
      "enabled": false,
      "allow_agent_override": false,
      "limit_type": "account"
    },
    "auto_idle": {
      "enabled": true,
      "reassignments_before_idle": 3,
      "new_status": "away"
    },
    "skill_routing": {
      "enabled": true,
      "max_wait_time": 30
    },
    "reassignment": {
      "enabled": false,
      "timeout": 30
    }
  }
}

Update Account Routing Settings

PATCH /api/v2/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.

Allowed for

Owner
Administrator

Using cURL

curl https://www.zopim.com/api/v2/routing_settings/account \
  -d '{
    "routing_mode": "broadcast",
    "chat_limit": {
      "enabled": true
    },
    "reassignment": {
      "enabled": true,
      "timeout": 60
    }
  }' \
  -v -u {email_address}:{password} \
  -X PATCH -H "Content-Type: application/json"

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "routing_mode": "broadcast",
    "chat_limit": {
      "limit": 3,
      "enabled": true,
      "allow_agent_override": false,
      "limit_type": "account"
    },
    "auto_idle": {
      "enabled": true,
      "reassignments_before_idle": 3,
      "new_status": "away"
    },
    "skill_routing": {
      "enabled": true,
      "max_wait_time": 30
    },
    "reassignment": {
      "enabled": true,
      "timeout": 60
    }
  }
}

Get Agent Routing Settings

GET /api/v2/routing_settings/agents/{agent_id}
GET /api/v2/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

Owner
Administrator
Agent

Using cURL

curl https://www.zopim.com/api/v2/routing_settings/agents/{agent_id} \
  -v -u {email_address}:{password}

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "skills": [1, 2, 3],
    "routing": {
      "chat_limit": 3
    }
  }
}

Update Agent Routing Settings

PATCH /api/v2/routing_settings/agents/{agent_id}
PATCH /api/v2/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

Owner
Administrator
Agent (using /me)

Using cURL

curl https://www.zopim.com/api/v2/routing_settings/agents/{agent_id} \
  -d '{
    "skills": [5, 6],
    "routing": {
      "chat_limit": 5
    }
  }' \
  -v -u {email_address}:{password} \
  -X PATCH -H "Content-Type: application/json"

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "skills": [5, 6],
    "routing": {
      "chat_limit": 5
    }
  }
}

Get Multiple Agents' Routing Settings

GET /api/v2/routing_settings/agents
GET /api/v2/routing_settings/agents?since_id=100&limit=100
GET /api/v2/routing_settings/agents?max_id=150

Gets the routing settings of all agents.

Pagination

This endpoint uses cursor-based pagination. The paging mechanism is similar to the GET /api/v2/agents API. See Get All Agents for reference.

Allowed for

Owner
Administrator
Agent

Using cURL

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

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "19174": {
      "skills": [1, 2, 3],
      "routing": {
        "chat_limit": 3
      }
    },
    "19175": {
      "skills": [5, 6],
      "routing": {
        "chat_limit": 5
      }
    }
  }
}

Batch Update Routing Settings for Multiple Agents

PATCH /api/v2/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

Owner
Administrator

Using cURL

curl https://www.zopim.com/api/v2/routing_settings/agents \
  -d '{
    "19174": {
      skills: [8, 9]
    },
    "19175": {
      "routing": {
        "chat_limit": 7
      }
    }
  }' \
  -v -u {email_address}:{password} \
  -X PATCH -H "Content-Type: application/json"

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "19174": {
      "skills": [8, 9],
      "routing": {
        "chat_limit": 3
      }
    },
    "19175": {
      "skills": [5, 6],
      "routing": {
        "chat_limit": 7
      }
    }
  }
}