Incremental Exports

These APIs are intended for exporting a complete list of items from your Zendesk Chat instance, then periodically (incrementally) fetching items that have been created or updated since the previous fetch.

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

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:

Name Type Read-only Mandatory Comment
next_page string yes no The URL that should be called to get the next set of results
end_time integer yes no 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
end_id string yes no The most recent item's ID present in this result set; this is used as the start_id in the next_page URL
count integer yes no The number of results returned for the current request

Request 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 strign 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/incremental/chats?start_time=1546326000

/agent_timeline follows the same usage of 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/incremental/agent_timeline?start_time=1546326000000000

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.

Incremental Chat Export

GET /api/v2/incremental/chats

Returns the chats that were updated since the start time.

chats attributes
Name Type Read-only Description
<All Chat attributes> - - All attributes documented in the Chat API
engagements array yes Array of agent 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 attributes
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 transfered 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
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 the usage notes above.

Using cURL
curl "https://www.zopim.com/api/v2/incremental/chats?fields=chats(*)" \
  -v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "chats": [
    {
      "comment": null,
      "rating": null,
      "update_timestamp": "2018-04-24T07:04:07Z",
      "triggered_response": null,
      "visitor": {
        "id": "2.m5hI3lMCpFMHQF",
        "phone": "",
        "notes": "",
        "email": "",
        "name": "Visitor 23675913"
      },
      "skills_requested": [
        "english"
      ],
      "dropped": false,
      "engagements": [
        {
          "comment": null,
          "agent_full_name": "Agent 1",
          "rating": null,
          "timestamp": "2018-04-24T06:53:28Z",
          "skills_fulfilled": false,
          "skills_requested": [],
          "count": {
            "visitor": 0,
            "total": 0,
            "agent": 0
          },
          "started_by": null,
          "assigned": true,
          "agent_id": 980824,
          "duration": 0,
          "accepted": false,
          "id": "1804.2.Qq7ILHyiRUU2W.1",
          "response_time": {
            "max": null,
            "avg": null,
            "first": null
          },
          "department_id": null
        },
        {
          "comment": null,
          "agent_full_name": "Agent 1",
          "rating": null,
          "timestamp": "2018-04-24T06:53:53Z",
          "skills_fulfilled": false,
          "skills_requested": [
            "english"
          ],
          "count": {
            "visitor": 1,
            "total": 2,
            "agent": 1
          },
          "started_by": "visitor",
          "assigned": true,
          "agent_id": 980824,
          "duration": 5.2809998989105225,
          "accepted": true,
          "id": "1804.2.Qq7ILHyiRUU2W.2",
          "response_time": {
            "max": 28,
            "avg": 28.16700005531311,
            "first": 28
          },
          "department_id": null
        }
      ],
      ...
    },
    ...
  ],
  "count": 4,
  "next_page": "https://www.zopim.com/api/v2/incremental/chats?fields=chats%28%2A%29&start_time=1524710057&start_id=1804.2.QqHwCNX18mZ7Y",
  "end_time": 1524710057,
  "end_id": "1804.2.QqHwCNX18mZ7Y"
}

Incremental Agent Timeline Export

GET /api/v2/incremental/agent_timeline

Returns an agent_timeline 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.

agent_timeline attributes
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
Allowed for
  • Owner
  • Administrator
Resource Expansion

Not applicable.

Using cURL
curl "https://www.zopim.com/api/v2/incremental/agent_timeline" \
  -v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "agent_timeline": [
    {
      "status": "away",
      "engagement_count": 0,
      "start_time": "2018-04-29T10:26:40.957650Z",
      "agent_id": 1730415,
      "duration": 65.705271
    },
    {
      "status": "invisible",
      "engagement_count": 0,
      "start_time": "2018-04-29T10:27:46.662921Z",
      "agent_id": 1730415,
      "duration": 0.29361
    },
    {
      "status": "away",
      "engagement_count": 0,
      "start_time": "2018-04-29T10:27:46.956531Z",
      "agent_id": 1730415,
      "duration": 9957.130438
    },
    {
      "status": "online",
      "engagement_count": 0,
      "start_time": "2018-04-29T11:02:33.286461Z",
      "agent_id": 980824,
      "duration": 10654.117251
    }
  ],
  "count": 4,
  "next_page": "https://www.zopim.com/api/v2/incremental/agent_timeline?limit=7&start_time=1525010407403712",
  "end_time": 1525010407403712
}

Incremental Conversions Export

GET /api/v2/incremental/conversions

Return conversions that have occurred, or been updated, since the start time.

conversion 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
attribution attributes
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 the usage notes above.

Using cURL
curl "https://www.zopim.com/api/v2/incremental/conversions?fields=conversions(*)" \
  -v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

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

Incremental Department Events Export

GET /api/v2/incremental/department_events

Returns 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_event attributes
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.

Using cURL
curl "https://www.zopim.com/api/v2/incremental/department_events" \
  -v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

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