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:

Name	Type	Read-only	Mandatory	Description
agent_id	integer	false	false	Zendesk 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_id	integer	true	true	The app's unique identifier
brand_id	integer	false	false	Zendesk id of the brand associated with the call
call_disposition	string	false	false	Outcome of the call, such as 'no longer in business', 'do not call again', 'problem solved', 'escalated' and so forth
call_ended_at	string	false	false	Date and time when the call ended (for example, the agent ends the phone call) in ISO 8601 format
call_recording_consent	string	false	false	Call recording consent value configured by the account for the phone number. Allowed values are 'always', 'opt_in', 'opt_out' or 'never'
call_recording_consent_action	string	false	false	Call recording consent option selected by the caller. For example, 'caller_opted_in', 'caller_opted_out'
call_started_at	string	false	true	Date and time the call is connected (when the greeting starts playing) in ISO 8601 format
call_type	string	false	false	The type of the call, regarding its origin, for example, "phone" or "digital"
callback_number	string	false	false	The number entered in the IVR by the user when requesting a callback. Usually, an alternative phone number for the caller
callback_source	string	false	false	The source of the callback request. Allowed values are 'queue' or 'web widget'
completion_status	string	false	false	Status 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_time	integer	false	false	Sum of how long in seconds agents consulted with each other while the customer was on hold
created_at	string	false	false	System generated time when the call object was created in ISO 8601 format
customer_requested_voicemail	boolean	false	false	The customer requested to be directed to voicemail instead of waiting for an agent to answer
direction	string	false	true	Call direction. Allowed values are 'inbound', 'outbound', 'internal' or 'callback'
dnis	string	false	false	Number dialed by the caller
duration	integer	false	false	Call duration in seconds
end_user_id	integer	false	false	Zendesk id of the caller (end user)
end_user_location	string	false	false	An approximation of the geographic area for the phone number, usually based on the prefix of the number or IP of the caller
exceeded_queue_time	boolean	false	false	If true, the caller exceeded the maximum queue wait time and did not speak with an agent
external_id	string	false	false	An id representing the call in an external system
from_line	string	false	true	The phone number of the person who initated the call
from_line_nickname	string	false	false	For outbound calls, the nickname of the line that made the call. For inbound calls it should be empty or null
hold_time	integer	false	false	How long in seconds the customer was on hold
id	integer	true	false	Automatically assigned upon creation
ivr_action	string	false	false	Menu 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_name	string	false	false	Name 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_hops	integer	false	false	How many menu options the customer went through in IVR before talking to an agent
ivr_routed_to	string	false	false	Phone number where the call was routed to by IVR. null if IVR was disabled
ivr_time_spent	integer	false	false	How long in seconds the customer spent in IVR before entering the queue
not_recording_time	integer	false	false	How long in seconds spend not recording on the call
organization_id	integer	false	false	Zendesk id of the organization associated with the call
outside_business_hours	boolean	false	false	If true, the call was received outside business hours
overflowed	boolean	false	false	if true, the call overflowed to a different number
overflowed_to	string	false	false	The number that the call overflowed to, null if overflowed is false
phone_name	string	false	false	Unique caller id name registered in a CNAM database. Used by VoIP services. For landline providers, this is the same as the phone number
queue_name	string	false	false	The name of the queue from where the caller came
queue_time	integer	false	false	How long in seconds of how long the customer spent in queue before the agent picks up the call
recording_control_interactions	integer	false	false	The number of times agents have paused or resumed a recording on the call
recording_time	integer	false	false	How long in seconds spent recording on the call
recording_url	string	false	false	URL 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_time	integer	false	false	Duration 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_id	integer	false	false	Zendesk id of the ticket associated with the call
time_to_answer	integer	false	false	How long in seconds the customer waited for the agent after greeting
to_line	string	false	true	Phone number of the person who received the call
to_line_nickname	string	false	false	For inbound calls, the nickname of the line that received the call. For outbound calls, it should be empty or null
transcript	string	false	false	Transcript of the message in plain text. Line breaks ('\n') are allowed
updated_at	string	false	false	System generated time when the call was last updated in ISO 8601 format
voicemail	boolean	false	false	If true, a voicemail was created
wait_time	integer	false	false	How long in seconds the customer waited for the agent after hearing the greeting
wrap_up_time	integer	false	false	Sum of how long in seconds the agent(s) spent in wrap up

Valid call 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": "[phone]",
  "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": "[phone]",
  "from_line_nickname": "Sales",
  "hold_time": 120,
  "id": 1,
  "ivr_action": "voicemail",
  "ivr_destination_group_name": "Billing",
  "ivr_hops": 3,
  "ivr_routed_to": "[phone]",
  "ivr_time_spent": 21,
  "not_recording_time": 210,
  "outside_business_hours": false,
  "overflowed": false,
  "overflowed_to": "[phone]",
  "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": "[phone]",
  "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.

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": "[phone]",
    "from_line_nickname": "Sales",
    "to_line": "[phone]",
    "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}:{password} \
-d '{"call": { "from_line": "[phone]", "to_line": "[phone]", "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}:{password} \
-d '{"call": { "from_line": "[phone]", "to_line": "[phone]", "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": "[phone]",
    "from_line_nickname": "Sales",
    "id": 1,
    "organization_id": 367,
    "ticket_id": 37987922,
    "to_line": "[phone]",
    "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

Name	Type	In	Required	Description
call_id	integer	Path	true	id of the Talk Partner Edition call

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/calls/{call_id}.json \
-v -u {email_address}:{password} \
-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": "[phone]",
    "from_line_nickname": "Sales",
    "id": 1,
    "organization_id": 367,
    "ticket_id": 37987922,
    "to_line": "[phone]",
    "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

Name	Type	In	Required	Description
call_id	integer	Path	true	id 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": "[phone]",
    "from_line_nickname": "Sales",
    "recording_url": "http://external.site.com/recordings/abcdef",
    "to_line": "[phone]",
    "to_line_nickname": "Technical Support"
  }
}

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/calls/{call_id}.json \
-v -u {email_address}:{password} \
-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": "[phone]",
    "from_line_nickname": "Sales",
    "id": 1,
    "organization_id": 367,
    "ticket_id": 37987922,
    "to_line": "[phone]",
    "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. A list of valid fields can be found in the See Valid call fields schema.

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.

Parameters

Name	Type	In	Required	Description
call_id	integer	Path	true	id 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}:{password} \
-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": "[phone]",
    "to_line": "[phone]"
  },
  "id": 7040574985853,
  "public": true,
  "type": "TpeVoiceComment"
}