DocumentationAPI Reference

Calls

Talk Partner Edition includes a Standard Call Object with endpoints to save, read, and update a set of call-related data in Zendesk. All data stored in the standard call object can be presented in a structured and consistent way in the ticket with the new Talk Partner Edition Voice Comment.

JSON format

Calls are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
agent_idintegerfalsefalseZendesk id of the agent who answered the call. Zendesk displays this information in the ticket as the name of the agent in the system
app_idintegertruetrueThe app's unique identifier
brand_idintegerfalsefalseZendesk id of the brand associated with the call
call_dispositionstringfalsefalseOutcome of the call, such as 'no longer in business', 'do not call again', 'problem solved', 'escalated' and so forth
call_ended_atstringfalsefalseDate and time when the call ended (for example, the agent ends the phone call) in ISO 8601 format
call_recording_consentstringfalsefalseCall recording consent value configured by the account for the phone number. Allowed values are 'always', 'opt_in', 'opt_out' or 'never'
call_recording_consent_actionstringfalsefalseCall recording consent option selected by the caller. For example, 'caller_opted_in', 'caller_opted_out'
call_started_atstringfalsetrueDate and time the call is connected (when the greeting starts playing) in ISO 8601 format
call_typestringfalsefalseThe type of the call, regarding its origin, for example, "phone" or "digital"
callback_numberstringfalsefalseThe number entered in the IVR by the user when requesting a callback. Usually, an alternative phone number for the caller
callback_sourcestringfalsefalseThe source of the callback request. Allowed values are 'queue' or 'web widget'
completion_statusstringfalsefalseStatus of the call. It should be empty for calls in progress. Allowed values are 'completed', 'abandoned_in_queue', 'abandoned_in_ivr', 'abandoned_in_voicemail', 'abandoned_on_hold', 'pending_voicemail', 'missed', 'declined', 'dropped', 'dropped_by_caller' or 'dropped_by_agent'
consultation_timeintegerfalsefalseSum of how long in seconds agents consulted with each other while the customer was on hold
created_atstringfalsefalseSystem generated time when the call object was created in ISO 8601 format
customer_requested_voicemailbooleanfalsefalseThe customer requested to be directed to voicemail instead of waiting for an agent to answer
directionstringfalsetrueCall direction. Allowed values are 'inbound', 'outbound', 'internal' or 'callback'
dnisstringfalsefalseNumber dialed by the caller
durationintegerfalsefalseCall duration in seconds
end_user_idintegerfalsefalseZendesk id of the caller (end user)
end_user_locationstringfalsefalseAn approximation of the geographic area for the phone number, usually based on the prefix of the number or IP of the caller
exceeded_queue_timebooleanfalsefalseIf true, the caller exceeded the maximum queue wait time and did not speak with an agent
external_idstringfalsefalseAn id representing the call in an external system
from_linestringfalsetrueThe phone number of the person who initated the call
from_line_nicknamestringfalsefalseFor outbound calls, the nickname of the line that made the call. For inbound calls it should be empty or null
hold_timeintegerfalsefalseHow long in seconds the customer was on hold
idintegertruefalseAutomatically assigned upon creation
ivr_actionstringfalsefalseMenu action used by the caller in the IVR menu selection. Possible values are null (if IVR was not used), "menu", "voicemail", "group", "phone_number", "textback", "invalid", and so forth
ivr_destination_group_namestringfalsefalseName of the group that received the call through IVR routing. Partners that don't use groups the same way as Zendesk can use this field as the last option selected by the caller in the IVR menu
ivr_hopsintegerfalsefalseHow many menu options the customer went through in IVR before talking to an agent
ivr_routed_tostringfalsefalsePhone number where the call was routed to by IVR. null if IVR was disabled
ivr_time_spentintegerfalsefalseHow long in seconds the customer spent in IVR before entering the queue
not_recording_timeintegerfalsefalseHow long in seconds spend not recording on the call
organization_idintegerfalsefalseZendesk id of the organization associated with the call
outside_business_hoursbooleanfalsefalseIf true, the call was received outside business hours
overflowedbooleanfalsefalseif true, the call overflowed to a different number
overflowed_tostringfalsefalseThe number that the call overflowed to, null if overflowed is false
phone_namestringfalsefalseUnique caller id name registered in a CNAM database. Used by VoIP services. For landline providers, this is the same as the phone number
queue_namestringfalsefalseThe name of the queue from where the caller came
queue_timeintegerfalsefalseHow long in seconds of how long the customer spent in queue before the agent picks up the call
recording_control_interactionsintegerfalsefalseThe number of times agents have paused or resumed a recording on the call
recording_timeintegerfalsefalseHow long in seconds spent recording on the call
recording_urlstringfalsefalseURL of the recording. This is displayed in the voice comment both as an audio player (if the audio is reachable) and the actual URL
talk_timeintegerfalsefalseDuration of the call in seconds the customer was in conference with an agent(s). Hold time and conference time are not included in the talk time
ticket_idintegerfalsefalseZendesk id of the ticket associated with the call
time_to_answerintegerfalsefalseHow long in seconds the customer waited for the agent after greeting
to_linestringfalsetruePhone number of the person who received the call
to_line_nicknamestringfalsefalseFor inbound calls, the nickname of the line that received the call. For outbound calls, it should be empty or null
transcriptstringfalsefalseTranscript of the message in plain text. Line breaks ('\n') are allowed
updated_atstringfalsefalseSystem generated time when the call was last updated in ISO 8601 format
voicemailbooleanfalsefalseIf true, a voicemail was created
wait_timeintegerfalsefalseHow long in seconds the customer waited for the agent after hearing the greeting
wrap_up_timeintegerfalsefalseSum of how long in seconds the agent(s) spent in wrap up

Valid comment fields

All valid call fields that can be added to the voice comment. Any values not in this list will be ignored.

  • agent_id
  • call_disposition
  • call_ended_at
  • call_recording_consent_action
  • call_type
  • callback_number
  • completion_status
  • consultation_time
  • dnis
  • duration
  • end_user_location
  • exceeded_queue_time
  • hold_time
  • ivr_destination_group_name
  • ivr_time_spent
  • location
  • outside_business_hours
  • overflowed_to
  • phone_name
  • queue_name
  • queue_time
  • recording_url
  • talk_time
  • time_to_answer
  • transcript
  • wait_time
  • external_id

Example

{  "agent_id": 88902883,  "app_id": 735264019863524,  "brand_id": 9157783614,  "call_disposition": "Call again later",  "call_ended_at": "2022-01-27T15:31:40-04:00",  "call_recording_consent": "opt_in",  "call_recording_consent_action": "caller_opted_out",  "call_started_at": "2022-01-27T15:31:40+01",  "call_type": "PSTN",  "callback_number": "+1 (661) 748-0123",  "callback_source": "queue",  "completion_status": "completed",  "consultation_time": 67,  "customer_requested_voicemail": false,  "direction": "inbound",  "dnis": "0800-12345",  "duration": 345,  "end_user_id": 7827,  "end_user_location": "Dublin",  "exceeded_queue_time": true,  "external_id": "1245HN567",  "from_line": "+183808333456",  "from_line_nickname": "Sales",  "hold_time": 120,  "id": 1,  "ivr_action": "voicemail",  "ivr_destination_group_name": "Billing",  "ivr_hops": 3,  "ivr_routed_to": "+1311123456789",  "ivr_time_spent": 21,  "not_recording_time": 210,  "outside_business_hours": false,  "overflowed": false,  "overflowed_to": "+1 (661) 748-0123",  "phone_name": "1300 SELL",  "queue_name": "priority_one",  "queue_time": 36,  "recording_control_interactions": 3,  "recording_time": 210,  "recording_url": "https://somedomain.com/recording/123.mp3",  "talk_time": 360,  "ticket_id": 37987922,  "time_to_answer": 24,  "to_line": "+149488484873",  "to_line_nickname": "Technical Support",  "transcript": "There is an issue with my printer. Can you help? ...",  "voicemail": false,  "wait_time": 20,  "wrap_up_time": 210}

Create a Call Object

  • POST /api/v2/calls

Creates a standard call object record.

Optionally, creates a ticket and comment by also passing a VoiceComment object. See Valid comment fields.

When creating a ticket with a comment, the subject field sets the ticket's subject. If subject is not provided, title is used.

Note:

  • This field does not update the ticket's subject if a ticket already exists.
  • Do not include ticket_id in the call object. Including ticket_id, even if it is null, results in an error.

Example body

{  "call": {    "app_id": 735264019863524,    "call_ended_at": "2022-01-27T15:32:40+01",    "call_started_at": "2022-01-27T15:31:40+01",    "direction": "inbound",    "from_line": "+183808333456",    "from_line_nickname": "Sales",    "to_line": "+149488484873",    "to_line_nickname": "Technical Support"  },  "comment": {    "call_fields": [      "from_line",      "to_line",      "call_started_at"    ],    "title": "This is the ticket comment"  }}

Code Samples

curl - call object 
curl https://{subdomain}.zendesk.com/api/v2/calls.json \-v -u {email_address}/token:{api_token} \-d '{"call": { "from_line": "+183808333456", "to_line": "+149488484873", "call_started_at":  "2022-01-27T15:31:40+01", "direction":  "inbound", "app_id": 735264019863524 }}' \-X POST -H 'Content-Type: application/json'
curl - call object and comment in one 
curl https://{subdomain}.zendesk.com/api/v2/calls.json \-v -u {email_address}/token:{api_token} \-d '{"call": { "from_line": "+183808333456", "to_line": "+149488484873", "call_started_at":  "2022-01-27T15:31:40+01", "direction":  "inbound", "app_id": 735264019863524 }, "comment": { "title": "testing comment and call in 1", "call_fields": ["from_line", "to_line", "call_started_at", "direction", "duration"]}}' \-X POST -H 'Content-Type: application/json'

Example response(s)

201 Created 
// Status 201 Created
{  "call": {    "agent_id": 88902883,    "app_id": 735264019863524,    "brand_id": 9157783614,    "call_ended_at": "2022-01-27T15:32:40+01",    "call_started_at": "2022-01-27T15:31:40+01",    "direction": "inbound",    "end_user_id": 7827,    "from_line": "+183808333456",    "from_line_nickname": "Sales",    "id": 1,    "organization_id": 367,    "ticket_id": 37987922,    "to_line": "+149488484873",    "to_line_nickname": "Technical Support"  }}

Retrieve a Single Call by id

  • GET /api/v2/calls/{call_id}

Returns a call object according to the unique id provided.

Parameters

NameTypeInRequiredDescription
call_idintegerPathtrueid of the Talk Partner Edition call

Code Samples

curl 
curl https://{subdomain}.zendesk.com/api/v2/calls/{call_id}.json \-v -u {email_address}/token:{api_token} \-X GET

Example response(s)

200 OK 
// Status 200 OK
{  "call": {    "agent_id": 88902883,    "app_id": 735264019863524,    "brand_id": 9157783614,    "call_ended_at": "2022-01-27T15:32:40+01",    "call_started_at": "2022-01-27T15:31:40+01",    "direction": "inbound",    "end_user_id": 7827,    "from_line": "+183808333456",    "from_line_nickname": "Sales",    "id": 1,    "organization_id": 367,    "ticket_id": 37987922,    "to_line": "+149488484873",    "to_line_nickname": "Technical Support"  }}

Update a Call

  • PATCH /api/v2/calls/{call_id}

Updates a voice comment on the ticket linked to the call object.

Parameters

NameTypeInRequiredDescription
call_idintegerPathtrueid of the Talk Partner Edition call

Example body

{  "call": {    "app_id": 735264019863524,    "call_ended_at": "2022-01-27T15:32:40+01",    "call_started_at": "2022-01-27T15:31:40+01",    "direction": "inbound",    "duration": 120,    "from_line": "+183808333456",    "from_line_nickname": "Sales",    "recording_url": "http://external.site.com/recordings/abcdef",    "to_line": "+149488484873",    "to_line_nickname": "Technical Support"  }}

Code Samples

curl 
curl https://{subdomain}.zendesk.com/api/v2/calls/{call_id}.json \-v -u {email_address}/token:{api_token} \-d '{"call": { "call_ended_at": "2022-04-16T09:15:37Z" }}' \-X PATCH -H 'Content-Type: application/json'

Example response(s)

200 OK 
// Status 200 OK
{  "call": {    "agent_id": 88902883,    "app_id": 735264019863524,    "brand_id": 9157783614,    "call_ended_at": "2022-01-27T15:32:40+01",    "call_started_at": "2022-01-27T15:31:40+01",    "direction": "inbound",    "end_user_id": 7827,    "from_line": "+183808333456",    "from_line_nickname": "Sales",    "id": 1,    "organization_id": 367,    "ticket_id": 37987922,    "to_line": "+149488484873",    "to_line_nickname": "Technical Support"  }}

Creates a Voice Comment on a Ticket

  • POST /api/v2/calls/{call_id}/comments

title is required.

call_fields displays selected fields based on your preferences. If call_fields is not provided, only the required fields are displayed. For a list of valid comment fields, see Valid comment fields.

author_id is the author of the comment. If no author_id is provided, then end_user_id is used. If end_user_id is not set, it defaults to the integration user that called the API.

display_to_agent screen pops the ticket to the agent's browser when the voice comment is added. Leaving this field blank adds the comment, but the ticket must be manually opened. The agent id is validated before the call or ticket is created. A "422 - Unprocessable entity" error is returned if the agent id is invalid.

Parameters

NameTypeInRequiredDescription
call_idintegerPathtrueid of the Talk Partner Edition call

Example body

{  "call_fields": [    "from_line",    "to_line",    "call_started_at",    "call_ended_at",    "direction"  ],  "title": "this is the title"}

Code Samples

curl 
curl https://{subdomain}.zendesk.com/api/v2/calls/{call_id}/comments.json \-v -u {email_address}/token:{api_token} \-d '{"title": "this is the title", "call_fields": {["from_line", "to_line", "call_started_at", "call_ended_at", "direction"]}}' \-X POST -H 'Content-Type: application/json'

Example response(s)

201 Created 
// Status 201 Created
{  "data": {    "app_id": 735264019863524,    "call_ended_at": "2022-01-27T15:32:40+01",    "call_started_at": "2022-01-27T15:31:40+01",    "direction": "inbound",    "from_line": "+183808333456",    "to_line": "+149488484873"  },  "id": 7040574985853,  "public": true,  "type": "TpeVoiceComment"}