Chat API

Agents

You can use the API to get or set agent information.

If you created your Zendesk Chat account in Zendesk Support, access to the Chat Accounts and Agents APIs is restricted to GET requests. You can still use the other Chat APIs normally.

JSON Format

Agents are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
create_date string true false The date of creation of the agent
departments array true false The departments for the agent
display_name string false false The name to be displayed for the agent
email string false false The email address of the agent
enabled integer false false Describes whether the agent is enabled
enabled_departments array true false The enabled departments for the agent
first_name string false false The agent's first name
id integer true false The ID of the agent
last_name string false false The agent's last name
role_id integer false false The role ID of the agent
roles object true false Special role privileges. See below for values (deprecated)
skills array true false The skills for the agent

The roles attribute has the following values:

Value Users
owner owner of the account
administrator agent with administrator privileges

Note: The following field is required during creation:

Name Type Read-only Description
password string yes This is the password for the agent. This is only required during creation.
Example
 
{
  "create_date": "2014-09-30T08:25:09Z",
  "departments": [],
  "display_name": "Johnny",
  "email": "[email protected]",
  "enabled": 1,
  "enabled_departments": [],
  "first_name": "John",
  "id": 5,
  "last_name": "Doe",
  "role_id": 3,
  "roles": {
    "administrator": false,
    "owner": false
  }
}

List Agents
  • GET /api/v2/agents

Lists all the agents for your account.

Pagination

This endpoint uses cursor-based pagination. The records are ordered sequentially by record id. The endpoint takes max_id and since_id query parameters, which act as separate cursors that track the record ids in the recordset. The max_id cursor moves backward through the recordset, with the record ids getting smaller. The since_id cursor moves forward, with the record ids getting larger.

  • Use the max_id parameter to paginate backward through the recordset. Example: "Get the previous 200 records, ending with and including the max_id record."

    "https://www.zopim.com/api/v2/agents?max_id=10&limit=200"

  • Use the since_id parameter to paginate forward through the recordset. Example: "Get the next 200 records, starting with and including the since_id record."

    "https://www.zopim.com/api/v2/agents?since_id=10&limit=200"

The next page can be retrieved by computing the next since_id by adding 1 to the ID of the last record in the current set, and specifying that as the since_id in the next request. Similarly, the previous page can be retrieved by making a request that species a max_id that is 1 less than the first element of the current record set.

Additionally, the next page and the previous page paths will be available as headers in the response.

If any of the pagination parameters (since_id, max_id, limit) are present, the default number of results is 10, but you can change it with the limit parameter. If none of the pagination parameters are present, the entire record set is returned.

Zendesk Chat recommends using pagination wherever possible. Non-paginated queries will be deprecated in subsequent releases of the API.

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/agents?since_id=5&limit=2" \
  -v -u {email_address}:{password}
Example Response
 
Status 200 OK

[
  {
    "create_date": "2014-09-30T08:25:09Z",
    "departments": [],
    "display_name": "Johnny",
    "email": "[email protected]",
    "enabled": 1,
    "first_name": "John",
    "id": 5,
    "last_name": "Doe",
    "role_id": 3,
    "roles": {
      "administrator": false,
      "owner": false
    }
  }
]

Create Agent
  • POST /api/v2/agents

Creates an agent in an account. Note: An additional field, password, needs to be provided during creation.

Allowed for
  • Owner
  • Administrator
Using curl
 
curl https://www.zopim.com/api/v2/agents \
  -d '{
      "email": "[email protected]",
      "password": "secretpassword",
      "first_name": "John",
      "last_name": "Smith",
      "display_name": "Smith",
      "enabled": 1
    }' \
-v -u {email_address}:{password} \
-X POST -H "Content-Type: application/json"
Example Response
 
Status 201 Created

{
  "display_name": "Smith",
  "email": "[email protected]",
  "enabled": 1,
  "first_name": "John",
  "last_name": "Smith"
}

Show Agent by Email
  • GET /api/v2/agents/email/{email}

Fetches an agent using the agent's email address.

Allowed for
  • Owner
  • Administrator
Parameters
Name Type In Required Description
email string Path true The email of the agent
Using curl
 
curl "https://www.zopim.com/api/v2/agents/email/{email_id}" \
  -v -u {email_address}:{password}
Example Response
 
Status 200 OK

{
  "create_date": "2014-09-30T08:25:09Z",
  "departments": [],
  "display_name": "Johnny",
  "email": "[email protected]",
  "enabled": 1,
  "enabled_departments": [],
  "first_name": "John",
  "id": 5,
  "last_name": "Doe",
  "role_id": 3,
  "roles": {
    "administrator": false,
    "owner": false
  }
}

Show Requesting Agent
  • GET /api/v2/agents/me

Fetches your data.

Allowed for
  • Owner
  • Administrator
  • Agent
Using curl
 
curl https://www.zopim.com/api/v2/agents/me \
  -v -u {email_address}:{password}
Example Response
 
Status 200 OK

{
  "create_date": "2014-09-30T08:25:09Z",
  "departments": [],
  "display_name": "Johnny",
  "email": "[email protected]",
  "enabled": 1,
  "enabled_departments": [],
  "first_name": "John",
  "id": 5,
  "last_name": "Doe",
  "role_id": 3,
  "roles": {
    "administrator": false,
    "owner": false
  }
}

Update Requesting Agent
  • PUT /api/v2/agents/me

Updates your data.

Allowed for
  • Owner
  • Administrator
Using curl
 
curl https://www.zopim.com/api/v2/agents/me \
  -d '{"first_name" : "Jonathan"}' \
  -v -u {email_address}:{password} \
  -X PUT -H "Content-Type: application/json"
Example Response
 
Status 200 OK

{
  "display_name": "Smith",
  "email": "[email protected]",
  "enabled": 1,
  "first_name": "John",
  "last_name": "Smith"
}

Show Agent by ID
  • GET /api/v2/agents/{agent_id}

Fetches an agent by his or her ID.

Allowed for
  • Owner
  • Administrator
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/agents/{agent_id} \
  -v -u {email_address}:{password}
Example Response
 
Status 200 OK

{
  "create_date": "2014-09-30T08:25:09Z",
  "departments": [],
  "display_name": "Johnny",
  "email": "[email protected]",
  "enabled": 1,
  "enabled_departments": [],
  "first_name": "John",
  "id": 5,
  "last_name": "Doe",
  "role_id": 3,
  "roles": {
    "administrator": false,
    "owner": false
  }
}

Update Agent
  • PUT /api/v2/agents/{agent_id}

Updates details of an agent.

Allowed for
  • Owner
  • Administrator
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/agents/{agent_id} \
  -d '{"first_name": "John", "last_name": "Smith", "role_id": 2}' \
  -v -u {email_address}:{password} \
  -X PUT -H "Content-Type: application/json"
Example Response
 
Status 200 OK

{
  "display_name": "Smith",
  "email": "[email protected]",
  "enabled": 1,
  "first_name": "John",
  "last_name": "Smith"
}

Delete Agent
  • DELETE /api/v2/agents/{agent_id}

Deletes an agent from an account.

Allowed for
  • Owner
  • Administrator
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/agents/{agent_id} \
  -v -u {email_address}:{password} -X DELETE
Example Response
 
Status 204 No Content