Incremental Exports

You can use the Incremental Exports API to export a complete list of information on inbound and outbound calls from your Zendesk Talk instance, then periodically (incrementally) fetch items that have been created or updated since the previous fetch.

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

JSON Format

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
count integer yes no The number of results returned for the current request

Request Parameters

The incremental export endpoints take a required start_time parameter expressed as a Unix epoch time. Example:

GET /api/v2/channels/voice/stats/incremental/calls.json?start_time=1547635159

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 parameter that matches the end_time of the previous response, but it is recommended that this URL be treated as an opaque string. This is similar to the Incremental Export API in Zendesk Support, which also uses 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 export. You should use the count property to determine whether more items are available immediately.

Rate limits

You can make up to 10 requests per minute to these endpoints.

The rate limiting mechanism behaves identically to the one described in Rate Limits in the Support API introduction. We recommend using the Retry-After header value as described in Catching errors caused by rate limiting.

If you find yourself bumping into the rate limit when testing the API, see Incremental Sample Export below to test the API without getting throttled continuously.

Incremental Calls Export

GET /api/v2/channels/voice/stats/incremental/calls.json?start_time={unix_time}

Allowed For
  • Admins
  • Agents with Can manage channels permission
Request Parameters
  • start_time: The time of the oldest Talk call you're interested in. The call can be inbound or outbound. Returns Talk calls modified on or since this time.
Using curl
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/stats/incremental/calls.json?start_time=1547635159
  -v -u {email_address}:{password}
Fields

The exported items are represented as JSON objects.

Name Type Comment
id integer Call id
created_at date When the call object was created
updated_at date When the call object was last updated
direction string Inbound or outbound. The agent or customer who initialized the call
duration integer Call duration in seconds
completion_status string Status of the call. Possible values: "completed", "abandoned_in_queue", "abandoned_in_ivr", "abandoned_in_voicemail", "abandoned_on_hold", "pending_voicemail"
ticket_id integer  The id of the ticket related to the call
voicemail boolean  Customer's id in the call
agent_id integer  The id of the first agent who picked up the call
phone_number string  Talk phone associated with the call. Example: "+1311123456789"
phone_number_id integer  Talk phone number id
wait_time integer  How long in seconds the customer was in the call before an agent answered
hold_time integer Sum of how long in seconds the customer was placed on hold by an agent(s)
talk_time integer Sum of how long in seconds the customer was in conference with an agent(s). If a call is not accepted by an agent this will be 0
time_to_answer integer How long in seconds the customer waited for an agent to answer after hearing the Available agents greeting
wrap_up_time integer Sum of how long in seconds the agent(s) spent in wrap up
consultation_time integer Sum of how long in seconds agents consulted with each other while the customer was on hold
exceeded_queue_wait_time boolean The customer exceeded the maximum queue wait time and did not speak with an agent
outside_business_hours boolean The call was received outside business hours
customer_requested_voicemail boolean The customer requested to be directed to voicemail instead of waiting for an agent to answer
minutes_billed integer Minutes billed
call_charge string Total charge for the call. String representation of a decimal number with six decimal places. Example: "1.230000". null if no charge was received from Twilio
ivr_time_spent integer How long in seconds the customer spent in IVR. null if IVR is disabled
ivr_hops integer How many menu options the customer went through in IVR before talking to an agent. null if IVR is disabled
ivr_destination_group_name string Name of the group that received the call through IVR routing. null if IVR is disabled
ivr_routed_to string Phone number where call was routed to by IVR. Example: "+1311123456789". null if IVR is disabled
ivr_action string Menu action that was used by the caller in the IVR menu selection. Possible values: "null (if IVR is not used)", "voicemail", "group", "external", "textback ","invalid_keypress".
default_group boolean The call was answered by an agent who is a member of the call's default group, if group routing is used
callback boolean True if the call was initiated by a callback request from the customer
callback_source string The source of the callback request. Possible values: "null (if callback is false)", "queue", "web widget"
overflowed boolean True if the call overflowed
overflowed_to boolean The phone number that the call overflowed to. null if overflowed is false
Example Response
   Status: 200 OK

   {
        "calls": [
      {
        "id": 10217,
        "created_at": "2019-01-16T10:36:56Z",
        "updated_at": "2019-01-16T10:39:19Z",
        "agent_id": 10011,
        "call_charge": "0.025",
        "consultation_time": 0,
        "completion_status": "completed",
        "customer_id": 10032,
        "customer_requested_voicemail": false,
        "direction": "inbound",
        "duration": 76,
        "exceeded_queue_wait_time": false,
        "hold_time": 0,
        "minutes_billed": 2,
        "outside_business_hours": false,
        "phone_number_id": 10062,
        "phone_number": "+13308828232",
        "ticket_id": 5,
        "time_to_answer": 60,
        "voicemail": false,
        "wait_time": 35,
        "wrap_up_time": 0,
        "ivr_time_spent": null,
        "ivr_hops": null,
        "ivr_destination_group_name": null,
        "talk_time": 15,
        "ivr_routed_to": null,
        "callback": false,
        "callback_source": null,
        "default_group": false,
        "ivr_action": null,
        "overflowed": false,
        "overflowed_to": null
      }
    ],
    "next_page": "https://subdomain.zendesk.com/api/v2/channels/voice/stats/incremental/calls.json?start_time=1547635159",
    "count": 1,
    "end_time": 1547635159
   }

Incremental Call Legs Export

GET /api/v2/channels/voice/stats/incremental/legs.json?start_time={unix_time}

A call leg is a logical connection between two voice gateways or between a gateway and an IP telephony device.

Allowed For
  • Admins
  • Agents with Can manage channels permission
Request Parameters
  • start_time: The time of the oldest call leg you are interested in. Returns call legs modified on or since this time.
Using curl
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/stats/incremental/legs.json?start_time=1547635159
  -v -u {email_address}:{password}
Fields

Legs are a subsection of calls and return information specific to each agent that interacted with the call, or any action the system took on the call.

Name Type Comment
id integer Leg id
call_id integer Call id that the leg belongs to
type string The type of the leg. Possible values: "customer", "agent", "external","supervisor"
created_at date When the leg object was created
updated_at date When the leg object was last updated
agent_id integer Id of the agent associated with this part of the call. When agent_id is positive, then user_id must be 0 and the type is “agent_leg”
user_id integer Id of the customer or user associated with this part of the call. When user_id is positive then agent_id must be 0 and the type is “customer_leg”
duration integer How long in seconds the leg existed
hold_time integer How long in seconds the leg was on hold
talk_time integer How long in seconds the agent was in conference with the customer for this leg
wrap_up_time integer How long in seconds the leg was in wrap up. It can be null on customer leg
consultation_time integer How long the agent consulted with another agent while the customer was on hold. null if there was no consultation
available_via string Ways the agent is available for incoming calls. Possible values: "browser", "phone". It can be null on customer leg
forwarded_to string Phone number the call was forwarded to. Example: "+1311123456789". It can be null on customer leg
consultation_from integer The id of the agent who initialized a consultation. This value must be 0 on the first agent's leg. null if there was no consultation
consultation_to integer The id of the agent who received and accepted the consultation request. null if there was no transfer
transferred_from integer The id of the agent who initialized the transfer. This value must be 0 on the first agent's leg. null if there was no transfer
transferred_to integer The id of the agent who received and accepted the transfer request
conference_time    integer     Time that agent spent in 3rd party conference (if call has multiple conferences we will sum the conference time)
conference_from   integer     ID of agent who initiated the 3rd party conference
conference_to     integer     ID of user or agent that joined the 3rd party conference
minutes_billed integer Minutes billed
completion_status string Completion status of the leg. Possible values: "agent_declined", "agent_missed", "agent_transfer_declined", "customer_hang_up", "completed"
call_charge string Call charge on the leg. String representation of a decimal number with six decimal places. Example: "1.230000"
Example Response
   Status: 200 OK

   {
     "legs": [
      {
        "id": 10402,
        "created_at": "2019-01-16T10:36:56Z",
        "updated_at": "2019-01-16T10:39:19Z",
        "agent_id": 0,
        "user_id": 10032,
        "duration": 76,
        "hold_time": 0,
        "wrap_up_time": null,
        "available_via": null,
        "forwarded_to": null,
        "consultation_from": null,
        "transferred_from": null,
        "transferred_to": null,
        "conference_from": null,
        "conference_to": null,
        "conference_time": null,
        "minutes_billed": 2,
        "call_charge": "0.019",
        "completion_status": "completed",
        "consultation_time": null,
        "talk_time": 15,
        "consultation_to": null,
        "call_id": 10217,
        "type": "customer"
      },
      {
        "id": 10407,
        "created_at": "2019-01-16T10:37:30Z",
        "updated_at": "2019-01-16T10:39:19Z",
        "agent_id": 10011,
        "user_id": 0,
        "duration": 109,
        "hold_time": 0,
        "wrap_up_time": 0,
        "available_via": "browser",
        "forwarded_to": null,
        "consultation_from": null,
        "transferred_from": null,
        "transferred_to": null,
        "conference_from": null,
        "conference_to": null,
        "conference_time": null,
        "minutes_billed": 2,
        "call_charge": "0.003",
        "completion_status": "completed",
        "consultation_time": null,
        "talk_time": 14,
        "consultation_to": null,
        "call_id": 10217,
        "type": "agent"
      }
    ],
    "next_page": "https://subdomain.zendesk.com/api/v2/channels/voice/stats/incremental/legs.json?start_time=1547635159",
    "count": 2,
    "end_time": 1547635159
   }