Agent Events

The Agent Events API provides access to agent-related updates across your Zendesk Chat account.

This API is currently in limited availability.

JSON format

Incremental Agent Events are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
account_id	integer	true	false	The agent’s account id
agent_id	integer	true	false	The agent’s unique identifier
field_name	string	true	false	The agent attribute that changed on this event. Possible values are "status" or "engagements".
id	string	true	false	The event's unique identifier
previous_value		true	false	The value of the attribute before the change. For a status change, possible values are "offline", "online", "away" or "invisible". For an engagements change, the value is the number of concurrent chats (engagements) that the agent was involved in.
timestamp	string	true	false	The date and time in seconds when the event happened
value		true	false	The value of the attribute after the change. It can be either a string or an integer. Possible values are the same as previous_value.

Example

{
  "account_id": 2,
  "agent_id": 980824,
  "field_name": "status",
  "id": "R6vTSXc.agent:980824.WEuQDQ",
  "previous_value": "online",
  "timestamp": "2018-10-19T12:33:50.140101Z",
  "value": "away"
}

Incremental Agent Events Export

• GET /api/v2/chat/incremental/agent_events

Returns an agent_events object that consists of a chronologically ordered list of any agent-related update generated since the given start time. An event captures:

• Either any agent status change,
• Or a change in the number of any agent’s engagements.

Common Response Properties

See the Incremental Exports documentation.

Allowed for

• Administrator

Resource Expansion

Not applicable.

Parameters

Name	Type	In	Required	Description
fields	string	Query	false	Response properties required. See Resource expansion
limit	integer	Query	false	The number of results to be returned. Default and max 1000
start_id	string	Query	false	Defaults to empty string
start_time	integer	Query	false	A Unix epoch time in microseconds. See Start time. Defaults to 0

Code Samples

curl

curl "https://{subdomain}.zendesk.com/api/v2/chat/incremental/agent_events" \
  -v -H "Authorization: Bearer {token}"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/incremental/agent_events?fields=&limit=&start_id=&start_time="
	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/incremental/agent_events")
		.newBuilder()
		.addQueryParameter("fields", "")
		.addQueryParameter("limit", "")
		.addQueryParameter("start_id", "")
		.addQueryParameter("start_time", "");

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/incremental/agent_events',
  headers: {
	'Content-Type': 'application/json',
  },
  params: {
    'fields': '',
    'limit': '',
    'start_id': '',
    'start_time': '',
  },
};

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/incremental/agent_events?fields=&limit=&start_id=&start_time="
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/incremental/agent_events")
uri.query = URI.encode_www_form("fields": "", "limit": "", "start_id": "", "start_time": "")
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

{
  "agent_events": [
    {
      "account_id": 2,
      "agent_id": 980824,
      "field_name": "status",
      "id": "R6vTSXc.agent:980824.WEuQDQ",
      "previous_value": "online",
      "timestamp": "2018-10-19T12:33:50.140101Z",
      "value": "away"
    },
    {
      "account_id": 2,
      "agent_id": 980824,
      "field_name": "engagements",
      "id": "R6vTXhl.agent:980824.y7Q4aI",
      "previous_value": 0,
      "timestamp": "2018-10-19T12:34:09.989524Z",
      "value": 1
    },
    {
      "account_id": 2,
      "agent_id": 980824,
      "field_name": "engagements",
      "id": "R6vTZ0i.agent:980824.wpOTDT",
      "previous_value": 1,
      "timestamp": "2018-10-19T12:34:15.008359Z",
      "value": 0
    }
  ],
  "count": 3,
  "end_id": "R7AfRxf.agent:980824.72oQk1",
  "end_time": 1540176932.8872,
  "next_page": "https://{subdomain}.zendesk.com/api/v2/chat/incremental/agent_events?start_time=1540176932.887200&start_id=R7AfRxf.agent%3A980824.72oQk1"
}