Chat API

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.

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

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.

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/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
 
Status 200 OK

{
  "data": {
    "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/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
 
Status 200 OK

{
  "data": {
    "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/routing_settings/agents

Gets the routing settings of all agents.

Pagination

This endpoint uses cursor-based pagination. See Pagination in List Agents.

Allowed for
  • Owner
  • Administrator
  • 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
Using curl
 
curl https://www.zopim.com/api/v2/routing_settings/agents \
  -v -u {email_address}:{password}
Example Response
 
Status 200 OK

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

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
 
Status 200 OK

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

Show 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
Parameters
Name Type In Required Description
agent_id integer Path true The ID of the agent
Using curl
 
curl https://www.zopim.com/api/v2/routing_settings/agents/{agent_id} \
  -v -u {email_address}:{password}
Example Response
 
Status 200 OK

{
  "data": {
    "routing": {
      "chat_limit": 3
    },
    "skills": [
      1,
      2,
      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)
Parameters
Name Type In Required Description
agent_id integer Path true The ID of the agent
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
 
Status 200 OK

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