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 attributes.
Name | Type | Read-only | Description |
---|---|---|---|
id | integer | yes | The ID of the agent |
first_name | string | no | The agent's first name |
last_name | string | no | The agent's last name |
display_name | string | no | The name to be displayed for the agent |
create_date | timestamp | yes | The date of creation of the agent |
integer | no | The email ID of the agent | |
roles | object | yes | Special role privileges. See below for values (deprecated) |
role_id | integer | no | The role ID of the agent |
enabled | integer | no | Describes whether the agent is enabled |
departments | array | yes | The departments for the agent |
skills | array | yes | 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. |
Get All Agents
GET /api/v2/agents
GET /api/v2/agents?since_id=100&limit=100
GET /api/v2/agents?max_id=150
This lists all the agents for your account.
Pagination
This endpoint uses cursor-based pagination. The records are ordered sequentially by record id. The max_id
and since_id
parameters 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 themax_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 thesince_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
Using cURL
curl "https://www.zopim.com/api/v2/agents?since_id=5&limit=2" \
-v -u {email_address}:{password}
Note: In this example, you must enclose the URL in quotes because of the pagination parameters.
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
X-Next-Page: /api/v2/agents?since_id=9&limit=2
X-Previous-Page: /api/v2/agents?max_id=4&limit=2
[
{
"id" : 5,
"first_name" : "John",
"last_name" : "Doe",
"display_name" : "Johnny",
"create_date" : "2014-09-30T08:25:09Z",
"email" : "[email protected]",
"roles" : {
"owner": false,
"administrator": false
},
"role_id": 3,
"enabled" : 1,
"departments" : []
},
{
"id" : 8,
"first_name" : "Kevin",
"last_name" : "Doe",
...
}
]
Get Agent by ID
GET /api/v2/agents/{agent_id}
Fetches an agent by his or her ID.
Allowed for
- Owner
- Administrator
Using cURL
curl https://www.zopim.com/api/v2/agents/{agent_id} \
-v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id":2,
"first_name":"Kevin",
"last_name":"Doe",
...
}
Get Agent by Email ID
GET /api/v2/agents/email/{email_id}
Fetches an agent using the agent's email ID.
Allowed for
- Owner
- Administrator
Using cURL
curl https://www.zopim.com/api/v2/agents/email/{email_id} \
-v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id":2,
"first_name":"Kevin",
"last_name":"Doe",
"email":"[email protected]",
...
}
Create Agent
POST /api/v2/agents
Allows the account owner/administrator to add more agents to the 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
HTTP/1.1 201 Created
Content-Type: application/json
{
"id":3,
"first_name":"John",
"last_name":"Smith",
...
}
Update Agent
PUT /api/v2/agents/{agent_id}
Allows an account owner/administrator to update details of an agent.
Allowed for
- Owner
- Administrator
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"id":2,
"first_name":"John",
"last_name":"Smith",
"role_id": 2,
...
}
Delete Agent
DELETE /api/v2/agents/{agent_id}
Allows an account owner/administrator to delete an agent.
Allowed for
- Owner
- Administrator
Using cURL
curl https://www.zopim.com/api/v2/agents/{agent_id} \
-v -u {email_address}:{password} -X DELETE
Response
Status: 204 No Content
Get Requesting Agent
GET /api/v2/agents/me
Fetches information about your agent.
Allowed for
- Owner
- Administrator
- Agent
Using cURL
curl https://www.zopim.com/api/v2/agents/me \
-v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id":2,
"first_name":"Kevin",
"last_name":"Doe",
...
}
Update Requesting Agent
PUT /api/v2/agents/me
Allows an account owner/administrator to update his or her 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
HTTP/1.1 200 OK
Content-Type: application/json
{
"id":1,
"first_name":"Jonathan",
"last_name":"Doe",
...
}