Creating a call record in Zendesk

The Talk Partner Edition API includes a standard call object which enables your telephony system to save, read, and update a set of call-related data in Zendesk. All data stored in the call object can be easily viewed on the Talk Partner Edition voice comment in a structured and consistent manner. In addition to transferring the task of displaying call data in the ticket to Zendesk, utilizing the standard call object offers the significant benefit of enabling customers to access this information through other means, like through Explore (the integration with Explore will come soon for third-party call data).

Creating a call record

Use the create a call endpoint to create a call record in the standard call object:

POST /api/v2/calls

The endpoint requires the following mandatory fields:

{
  "app_id": 735264019863524,
  "from_line": "[phone]",
  "to_line": "[phone]",
  "call_started_at": "2022-01-27T15:31:40+01",
  "direction": "inbound"
}

See call fields for a complete list of the call object fields.

The app_id is the identifier assigned to your app when using the Zendesk Apps Framework (ZAF). It's not necessary to upload your app to the Zendesk Marketplace to receive an app_id.

Creating a call record doesn’t generate any output on the ticket. If you want to show the call record on the ticket post-creation, you must use the Talk Partner Edition voice comment.

Not all calls need to be associated with tickets. For example, abandoned calls. Therefore, the ticket_id is not a required field when creating the call record.

Creating a call record, a ticket, and a voice comment with a single API request

In most cases, your system will generate a ticket, establish a call record linked to the ticket, and present it to an agent using a Talk Partner Edition voice comment. To avoid the need for multiple API requests, you can make a single request to the Create Call Object endpoint. You should omit ticket_id and include a comment section. You can set the agent for whom the ticket should be displayed, the subject of the ticket, and the author of the voice comment all after the call object is created. Example:

{
  "call": {
    "app_id": 735264019863524,
    "from_line": "[phone]",
    "to_line": "[phone]",
    "call_started_at": "2022-01-27T15:31:40+01",
    "direction": "inbound"
  },
  "comment": {
    "title": "Call to Agent X",
    "call_fields": ["from_line", "to_line", "call_started_at", "direction"],
    "display_to_agent": 385843365538,
    "author_id": 14710682415889,
    "subject": "Test Ticket"
  }
}

Retrieving a call record

To retrieve a call record, make a request to the following retrieve single call endpoint:

GET /api/v2/calls/{call_id}

Updating a call record

To update a call record, make a request to the Talk Partner Edition update call:

PATCH /api/v2/calls/{call_id}

For example, at the end of a call your system could make a request to update the call record with the time that the call ended, its duration, talk time, and more.

{
  "call_ended_at": "2022-01-27T15:31:40-04:00",
  "duration": 345,
  "talk_time": 360,
  "hold_time": 120,
  "completion_status": "completed",
  "call_disposition": "Call again later",
  "recording_url": "https://somedomain.com/recording/help.mp3",
  "transcript": "Help! I need somebody (Help) ..."
}

See call fields for a complete list of the call object fields.

Updating a call record doesn’t generate any output on the ticket. If after updating a call record you want to display it in the ticket, you must use the Talk Partner Edition voice comment.