Incremental Exports

You can export a complete list of items from your Zendesk Chat instance, then periodically (incrementally) fetch items that have been created or updated since the previous fetch.

You can export the following items:

• Incremental chats
• Incremental agent timespans
• Incremental conversions
• Incremental department events

Items are returned based on the update timestamp. For example, if a chat is updated, any subsequent request will return the chat. Even if a chat is ended but later updated (such as by adding a tag), a subsequent request will still return the ended chat with the changes.

See the Core API Incremental Export documentation for general information on Zendesk incremental APIs, including detailed usage notes and examples.

Query string parameters

Name	Type	Mandatory	Comment
start_time	integer	no	A Unix epoch time in microseconds. See Start time. Defaults to 0
start_id	string	no	Defaults to empty string
limit	integer	no	The number of results to be returned. Default and max 1000
fields	string	no	Response properties required. See Resource Expansion

Start time

The incremental export endpoints (except agent_timeline) take a start_time parameter expressed as a Unix epoch time in seconds. For example, if you want to set the start time at January 1, 2019, at 7am GMT, the converter at http://www.epochconverter.com gives the time as an epoch timestamp of 1546326000.

GET /api/v2/chat/incremental/chats?start_time=1546326000

The agent timeline export takes a Unix epoch time in microseconds. Example: 1546326000000000. See Incremental Agent Timeline Export.

Note: The start_time value must be more than five minutes in the past otherwise the export request will be rejected.

Resource expansion

For endpoints that support resource expansion, the resource responses will only have a limited set of attributes by default, often just the ID.

{
  "chats": [
    {"id": "1712.4987.QeUipU4eZOoO3"},
    {"id": "1712.4987.QELAIbLLINHPV"},
    ...
  ]
}

Resource expansion allows you to specify which attributes of the resource should be returned, by passing the attribute names into the fields query string parameter.

?fields=chats(id,comment,rating)

• To selectively expand a nested attribute, use . to specify the attribute name:

  ?fields=chats(response_time.max)

• To fully expand the resource, pass a * as a wildcard:

  ?fields=chats(*)

Pagination and polling

For both pagination (during the initial export) and polling (periodic requests for new data), use the next_page URL.

The next_page URL contains start_time and start_id parameters that match the end_time and end_id of the previous response, but it is recommended that this URL be treated as an opaque string. Note that this is slightly different from the Incremental Export API in Zendesk Support, which uses only start_time and end_time.

Unlike other endpoints that return null as the value of next_page when reaching the last page of the result set, these endpoints return the URL that should be used for the next Polling fetch. You should use the count property to determine whether more items are available immediately.

These endpoints return up to limit items per page (1000 by default). If count is less than limit, more items are available, and the next_page URL may be requested immediately. Otherwise, no further items are available immediately, and the next_page URL should be requested after a polling interval.

Rate limits

The rate limits of Chat API apply.

Common response properties

The exported items are represented as JSON objects. The format depends on the exported resource, but all have the following additional common attributes:

JSON format

Incremental Export are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
count	integer	true	false	The number of results returned for the current request
end_id	string	true	false	The most recent item's ID present in this result set; this is used as the start_id in the next_page URL
end_time	number	true	false	The most recent time present in this result set in Unix epoch time; this is used as the start_time in the next_page URL
next_page	string	true	false	The URL that should be called to get the next set of results

Example

{
  "count": 4,
  "end_id": "1804.2.QqHwCNX18mZ7Y",
  "end_time": 1524710057,
  "next_page": "https://{subdomain}.zendesk.com/api/v2/chat/incremental/chats?fields=chats%28%2A%29&start_time=1524710057&start_id=1804.2.QqHwCNX18mZ7Y"
}

Incremental Agent Timeline Export

• GET /api/v2/chat/incremental/agent_timeline

Returns an agent_timeline object that consists of a chronologically ordered list of timespan objects generated since the given start time. A timespan is the state of an agent during a certain period. Currently, the state includes status and engagement_count. engagement_count correlates to the number of engagements. To understand the information captured in an engagement, see the engagements object properties.

agent_timeline

Name	Type	Read-only	Description
agent_id	integer	yes	The agent ID
start_time	date	yes	The date and time in microseconds when the timespan started
duration	number	yes	Duration of the timespan in seconds
status	string	yes	Status (non-offline) of the agent during the timespan: "online", "away", or "invisible"
engagement_count	integer	yes	Count of concurrent chats (engagements) that the agent was involved in

The start_time is used as described in Start time, except that it takes Unix epoch time in microseconds. To get the timestamp in microseconds (not to be confused with milliseconds), add 6 zeros to the epoch time, or 1546326000000000.

GET /api/v2/chat/incremental/agent_timeline?start_time=1546326000000000

The change to microseconds occurred on March 15, 2018.

Allowed for

• Owner
• 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_timeline" \
  -v -H "Authorization: Bearer {token}"

Go

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

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/incremental/agent_timeline?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_timeline")
		.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_timeline',
  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_timeline?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_timeline")
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_timeline": [
    {
      "agent_id": 1730415,
      "duration": 65.705271,
      "engagement_count": 0,
      "start_time": "2018-04-29T10:26:40.957650Z",
      "status": "away"
    },
    {
      "agent_id": 1730415,
      "duration": 0.29361,
      "engagement_count": 0,
      "start_time": "2018-04-29T10:27:46.662921Z",
      "status": "invisible"
    },
    {
      "agent_id": 1730415,
      "duration": 9957.130438,
      "engagement_count": 0,
      "start_time": "2018-04-29T10:27:46.956531Z",
      "status": "away"
    },
    {
      "agent_id": 980824,
      "duration": 10654.117251,
      "engagement_count": 0,
      "start_time": "2018-04-29T11:02:33.286461Z",
      "status": "online"
    }
  ],
  "count": 4,
  "end_time": 1525010407403712,
  "next_page": "https://{subdomain}.zendesk.com/api/v2/chat/incremental/agent_timeline?limit=7&start_time=1525010407403712"
}

Incremental Chat Export

• GET /api/v2/chat/incremental/chats

Returns a chats object listing the chats that were updated since the start time. Each chat has an engagements object that is only created when an agent joins a chat conversation. An engagement starts when the agent joins a chat conversation and ends when the agent leaves. See What is an engagement in Chat?

chats

Name	Type	Read-only	Description
<All Chat attributes>	-	-	All attributes documented in the Chat API
engagements	array	yes	Array of agent engagements . See engagements
update_timestamp	date	yes	The date and time when the chat was updated
skills_requested	array	yes	Array of skills requested
skills_fulfilled	boolean	yes	Whether the agent who served the chat had the skills
abandon_time	number	yes	Number of seconds the visitor waited for a response before leaving (for missed/dropped chats only)
dropped	boolean	yes	Whether the chat was dropped
proactive	boolean	yes	Whether the chat was proactively initiated by the agent
deleted	boolean	yes	Whether the chat was deleted

engagements

Name	Type	Read-only	Description
id	string	yes	The engagement ID
chat_id	string	yes	The chat ID
started_by	string	yes	Who started the engagements. Can be one of "visitor", "agent", or "transfer" (when being transferred to a different department)
agent_id	integer	yes	The agent ID
agent_full_name	string	yes	The agent's full name
department_id	integer	yes	The department ID of the engagement
assigned	boolean	yes	Whether the agent was assigned
accepted	boolean	yes	Whether the agent accepted the assignment and joined the chat
rating	string	yes	The customer satisfaction rating for the engagement
comment	string	yes	The customer comment on the engagement
skills_requested	array	yes	Array of skills requested
skills_fulfilled	boolean	yes	Whether the agent who served the chat had the skills
timestamp	date	yes	The date and time when the engagement starts
duration	number	yes	Duration of the engagement in seconds
response_time	object	yes	Statistics about the response times in the chat, avg, max and first
count	object	yes	Number of messages (each) by the visitor and the agent

Allowed for

• Owner
• Administrator

Resource Expansion

This endpoint supports resource expansion. See Resource expansion.

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/chats?fields=chats(*)" \
  -v -H "Authorization: Bearer {token}"

Go

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

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/incremental/chats?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/chats")
		.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/chats',
  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/chats?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/chats")
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

{
  "chats": [
    {
      "abandon_time": 29.43400001525879,
      "agent_ids": [
        "383486450414"
      ],
      "agent_names": [
        "David Foo"
      ],
      "comment": null,
      "conversions": [],
      "count": {
        "agent": 1,
        "total": 2,
        "visitor": 1
      },
      "deleted": false,
      "department_id": null,
      "department_name": null,
      "dropped": true,
      "duration": 12,
      "end_timestamp": "2020-12-22T04:54:59Z",
      "engagements": [
        {
          "accepted": false,
          "agent_full_name": "New Staff",
          "agent_id": "383486450414",
          "agent_name": "New Staff",
          "assigned": false,
          "comment": null,
          "count": {
            "agent": 1,
            "total": 2,
            "visitor": 1
          },
          "department_id": null,
          "duration": 43.4449999332428,
          "id": "2012.9339545.SJs7biGpcbveH.1",
          "rating": null,
          "response_time": {
            "avg": null,
            "first": null,
            "max": null
          },
          "skills_fulfilled": false,
          "skills_requested": [],
          "started_by": "agent",
          "timestamp": "2020-12-22T04:54:15Z"
        }
      ],
      "history": [
        {
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "department_id": null,
          "department_name": null,
          "index": 0,
          "name": "Visitor 25396546",
          "source": "chat.invite",
          "timestamp": "2020-12-22T04:54:15Z",
          "type": "chat.memberjoin"
        },
        {
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "index": 1,
          "name": "David Foo",
          "source": "chat.invite",
          "timestamp": "2020-12-22T04:54:15Z",
          "type": "chat.memberjoin"
        },
        {
          "agent_id": "383486450414",
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "index": 2,
          "msg": "deded",
          "name": "David Foo",
          "options": "",
          "sender_type": "Agent",
          "timestamp": "2020-12-22T04:54:18Z",
          "type": "chat.msg"
        },
        {
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "index": 3,
          "msg": "hello",
          "msg_id": "1608612869871",
          "name": "Visitor 25396546",
          "options": "",
          "sender_type": "Visitor",
          "timestamp": "2020-12-22T04:54:30Z",
          "type": "chat.msg"
        },
        {
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "index": 4,
          "name": "David Foo",
          "reason": "user_leave_chat",
          "timestamp": "2020-12-22T04:54:59Z",
          "type": "chat.memberleave"
        },
        {
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "index": 5,
          "name": "Visitor 25396546",
          "reason": "user_leave_chat",
          "timestamp": "2020-12-22T04:54:59Z",
          "type": "chat.memberleave"
        }
      ],
      "id": "2012.9339545.SJs7biGpcbveH",
      "missed": false,
      "proactive": true,
      "rating": null,
      "referrer_search_engine": "",
      "referrer_search_terms": "",
      "response_time": {
        "avg": null,
        "first": null,
        "max": null
      },
      "session": {
        "browser": "Chrome",
        "city": "Sydney",
        "country_code": "AU",
        "country_name": "Australia",
        "end_date": "2020-12-22T04:54:59Z",
        "id": "201222.9339545.7MmWjNbx50y3nMJBz",
        "ip": "13.55.49.175",
        "platform": "Mac OS",
        "region": "New South Wales",
        "start_date": "2020-12-22T04:50:58Z",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36"
      },
      "skills_fulfilled": false,
      "skills_requested": [],
      "started_by": "agent",
      "tags": [],
      "timestamp": "2020-12-22T04:54:16Z",
      "triggered": false,
      "triggered_response": null,
      "type": "chat",
      "unread": false,
      "update_timestamp": "2020-12-22T05:05:36Z",
      "visitor": {
        "email": "",
        "id": "9339545.11mjg3Gvk0uhEiK",
        "name": "Visitor 25396546",
        "notes": "",
        "phone": ""
      },
      "webpath": [
        {
          "from": "",
          "timestamp": "2020-12-22T04:50:58Z",
          "title": "Zendesk",
          "to": "https://subdomain.zendesk.com/hc/en-us"
        }
      ],
      "zendesk_ticket_id": 83
    },
    {
      "abandon_time": null,
      "agent_ids": [
        "383486450414"
      ],
      "agent_names": [
        "David Foo"
      ],
      "comment": null,
      "conversions": [],
      "count": {
        "agent": 1,
        "total": 1,
        "visitor": 0
      },
      "deleted": false,
      "department_id": null,
      "department_name": null,
      "dropped": false,
      "duration": 0,
      "end_timestamp": "2020-12-22T05:05:36Z",
      "engagements": [
        {
          "accepted": false,
          "agent_full_name": "New Staff",
          "agent_id": "383486450414",
          "agent_name": "New Staff",
          "assigned": false,
          "comment": null,
          "count": {
            "agent": 1,
            "total": 1,
            "visitor": 0
          },
          "department_id": null,
          "duration": 40.003000020980835,
          "id": "2012.9339545.SJsAIFAY09HB1.1",
          "rating": null,
          "response_time": {
            "avg": null,
            "first": null,
            "max": null
          },
          "skills_fulfilled": false,
          "skills_requested": [],
          "started_by": "agent",
          "timestamp": "2020-12-22T05:04:55Z"
        }
      ],
      "history": [
        {
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "department_id": null,
          "department_name": null,
          "index": 0,
          "name": "Visitor 25396546",
          "source": "chat.invite",
          "timestamp": "2020-12-22T05:04:55Z",
          "type": "chat.memberjoin"
        },
        {
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "index": 1,
          "name": "David Foo",
          "source": "chat.invite",
          "timestamp": "2020-12-22T05:04:55Z",
          "type": "chat.memberjoin"
        },
        {
          "agent_id": "383486450414",
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "index": 2,
          "msg": "hello again",
          "name": "David Foo",
          "options": "",
          "sender_type": "Agent",
          "timestamp": "2020-12-22T05:04:59Z",
          "type": "chat.msg"
        },
        {
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "index": 3,
          "name": "David Foo",
          "new_tags": [
            "one"
          ],
          "tags": [],
          "timestamp": "2020-12-22T05:05:02Z",
          "type": "chat.tag"
        },
        {
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "index": 4,
          "name": "David Foo",
          "new_tags": [
            "goodbye_survey",
            "one"
          ],
          "tags": [
            "one"
          ],
          "timestamp": "2020-12-22T05:05:04Z",
          "type": "chat.tag"
        },
        {
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "index": 5,
          "name": "David Foo",
          "reason": "user_leave_chat",
          "timestamp": "2020-12-22T05:05:35Z",
          "type": "chat.memberleave"
        },
        {
          "channel": "#supportchat:9339545-11mjg3Gvk0uhEiK",
          "index": 6,
          "name": "Visitor 25396546",
          "reason": "user_leave_chat",
          "timestamp": "2020-12-22T05:05:36Z",
          "type": "chat.memberleave"
        }
      ],
      "id": "2012.9339545.SJsAIFAY09HB1",
      "missed": false,
      "proactive": true,
      "rating": null,
      "referrer_search_engine": "",
      "referrer_search_terms": "",
      "response_time": {
        "avg": null,
        "first": null,
        "max": null
      },
      "session": {
        "browser": "Chrome",
        "city": "Sydney",
        "country_code": "AU",
        "country_name": "Australia",
        "end_date": "2020-12-22T05:05:36Z",
        "id": "201222.9339535.7MmWjNbx50y3nMJBz",
        "ip": "13.55.49.175",
        "platform": "Mac OS",
        "region": "New South Wales",
        "start_date": "2020-12-22T04:50:58Z",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36"
      },
      "skills_fulfilled": false,
      "skills_requested": [],
      "started_by": "agent",
      "tags": [
        "one",
        "goodbye_survey"
      ],
      "timestamp": "2020-12-22T05:04:56Z",
      "triggered": false,
      "triggered_response": null,
      "type": "chat",
      "unread": false,
      "update_timestamp": "2020-12-22T05:42:05Z",
      "visitor": {
        "email": "",
        "id": "9339545.11mjg3Gvk0uhEiK",
        "name": "Joel",
        "notes": "",
        "phone": ""
      },
      "webpath": [
        {
          "from": "",
          "timestamp": "2020-12-22T04:50:58Z",
          "title": "Zendesk",
          "to": "https://subdomain.zendesk.com/hc/en-us"
        }
      ],
      "zendesk_ticket_id": 84
    }
  ],
  "count": 2,
  "end_id": "2012.9339545.SJsAIFAY09HB1",
  "end_time": 1608613496,
  "next_page": "https://{subdomain}.zendesk.com/api/v2/chat/incremental/chats?fields=chats%28%2A%29&start_time=1608613496&start_id=2012.9339545.SJsAIFAY09HB1"
}

Incremental Conversions Export

• GET /api/v2/chat/incremental/conversions

Returns a conversions object that lists the conversions that have occurred or been updated since the start time.

Conversions attributes

Name	Type	Read-only	Description
id	string	yes	Conversion's ID
timestamp	date	yes	The date and time when the conversion happened
goal_id	integer	yes	Conversion's goal ID
goal_name	string	yes	Conversion's goal name
attribution	object	yes	Conversion's attribution. See attribution

attribution

Name	Type	Read-only	Description
agent_id	integer	yes	Involved agent ID
department_id	integer	yes	Invovled department ID
chat_id	string	yes	Associated chat ID
chat_timestamp	date	yes	Associated chat's start date and time

Allowed for

• Owner
• Administrator

Resource Expansion

This endpoint supports resource expansion. See Resource expansion.

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/conversions?fields=conversions(*)" \
  -v -H "Authorization: Bearer {token}"

Go

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

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/incremental/conversions?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/conversions")
		.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/conversions',
  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/conversions?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/conversions")
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

{
  "conversions": [
    {
      "attribution": {
        "agent_id": 361271293212,
        "chat_id": "1805.2234024.QrLZCCXVnzGJH",
        "chat_timestamp": "2018-05-07T07:57:37Z",
        "department_id": null
      },
      "goal_id": 1863,
      "goal_name": "add to cart",
      "id": "1805.2234024.v.1863.7BjLCgLGCJp4W90JapicWu",
      "timestamp": "2018-05-07T07:57:39Z"
    },
    {
      "attribution": {
        "agent_id": 361271293212,
        "chat_id": "1805.2234024.QrLoIcRHWMeul",
        "chat_timestamp": "2018-05-07T08:57:36Z",
        "department_id": null
      },
      "goal_id": 1863,
      "goal_name": "add to cart",
      "id": "1805.2234024.v.1863.6DPoXaF5JozixQ5RVoK9K3",
      "timestamp": "2018-05-07T08:57:39Z"
    },
    {
      "attribution": {
        "agent_id": null,
        "chat_id": null,
        "chat_timestamp": null,
        "department_id": null
      },
      "goal_id": 1865,
      "goal_name": "place order",
      "id": "1805.2234024.v.1865.4rUmpcFFfUBCkBqDru9j6V",
      "timestamp": "2018-05-07T10:57:38Z"
    }
  ],
  "count": 3,
  "end_id": "1805.2234024.v.1865.4rUmpcFFfUBCkBqDru9j6V",
  "end_time": 1525690658,
  "next_page": "https://{subdomain}.zendesk.com/api/v2/chat/incremental/conversions?fields=conversions%28%2A%29&start_time=1525690658&start_id=1805.2234024.v.1865.4rUmpcFFfUBCkBqDru9j6V"
}

Incremental Department Events Export

• GET /api/v2/chat/incremental/department_events

Returns a department_events object that contains a chronologically ordered list of event objects that reflect changes of departments' attributes since the given start time. Currently, the available attribute is queue_sizes.

department_events

Name	Type	Read-only	Description
id	string	yes	The event's ID
department_id	integer or null	yes	The nullable department ID
timestamp	date	yes	The date and time in seconds when the event happened
field_name	string	yes	Field name that defines an event's attribute. Possible value: "queue_sizes"
value	object	yes	Current value of the field specified by "field_name" attribute.
previous_value	object	yes	Previous value of the field specified by "field_name" attribute. This attribute may not present in response in case of being null or not applicable.

Allowed for

• Owner
• 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/department_events" \
  -v -H "Authorization: Bearer {token}"

Go

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

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/incremental/department_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/department_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/department_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/department_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/department_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

{
  "count": 2,
  "department_events": [
    {
      "department_id": 123,
      "field_name": "queue_sizes",
      "id": "R3J4l7Q.department:123.JNny6n",
      "timestamp": "2017-12-02T00:00:00.312082Z",
      "value": {
        "assigned": 2,
        "incoming": 2
      }
    },
    {
      "department_id": 456,
      "field_name": "queue_sizes",
      "id": "R3J4l7Q.department:456.ccf4LG",
      "timestamp": "2017-12-02T00:01:00.657078Z",
      "value": {
        "assigned": 2,
        "incoming": 3
      }
    }
  ],
  "end_id": "R3J4l7Q.department:456.ccf4LG",
  "end_time": 1536041904,
  "next_page": "https://{subdomain}.zendesk.com/api/v2/chat/incremental/department_events?start_time=1512172860.657078&start_id=R3J4l7Q.department:456.ccf4LG"
}