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": "+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.

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}:{password} \-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}:{password} \-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

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": "+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

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": "+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}:{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": "+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. 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": "+183808333456",    "to_line": "+149488484873"  },  "id": 7040574985853,  "public": true,  "type": "TpeVoiceComment"}