Creating a voice comment in a ticket

A voice comment is a unique kind of comment utilized by Zendesk to display key call-related information in the ticket (such as caller number, agent name, call duration, call transcription, etc.) and to provide controls for playing a call recording.

There are two types of voice comments:

• One used by the Tickets API

• The voice comment used exclusively by the Talk Partner Edition API. This provides a better user experience, but it requires you to create a call record first.

With the Talk Partner Edition voice comment:

• Information is organized into sections that can be expanded or collapsed as needed, ensuring efficient use of space within the ticket.
• Data is directly retrieved from the call record, eliminating the need to resend it.
• Numerous fields are available, making this voice comment suitable for a broader range of use cases.
• Agents can listen to and read transcripts simultaneously as they are presented side by side.
• Expanded transcripts are scrollable, saving space without compromising readability.
• The recording can be displayed separately from the rest of the data. In contrast, with the Tickets API, the recording must always be present or else a grey bar appears with the message "Recording not available".

Adding a voice comment to the ticket using the Talk Partner Edition API (recommended)

You can create the call record and the voice comment at the same time with a single API request. To do that, make a request to the create a call endpoint and include the comment section. The following example creates a call record associated with a ticket, and a voice comment and then displays the ticket to the agent indicated.

Example request body

{
  "call": {
    "app_id": 1352,
    "end_user_id": 7236,
    "ticket_id": 512
    "from_line": "[phone]",
    "to_line": "[phone]",
    "call_started_at": "2022-01-27T15:31:40+01",
    "call_ended_at": "2022-01-27T15:31:40-04:00",
    "direction": "inbound",
    "queue_time": 36,
    "ivr_destination_group_name": "Billing",
    "voicemail": false,
    "call_disposition": "Call again later",
    "recording_url": "https://somedomain.com/recording/123.mp3",
    "transcript": "My printer is on fire!",
  },
  "comment": {
    "title": "Call via MyCTI App",
    "call_fields": [
      "call_started_at",
      "call_ended_at",
      "recording_url",
      "transcript"
    ],
    "author_id": 7236,
    "display_to_agent": 7800
  }
}

If ticket_id is omitted, a new ticket is created and automatically associated with the call record before adding the voice comment. This is a way to create a ticket, a call record and a voice comment, and then display the ticket to the agent, all with a single API request.

When the ticket is created this way, it uses the comment title as its subject, which means that the ticket and the first comment will have the same title. If you want to set a different subject, add the field subject to the comment block. For example, the JSON block below creates a ticket with the subject “New Title”, creates a new call record associated with this ticket, adds a voice comment to the ticket, and displays it to the agent.

{
 "call": {
   "app_id": 135,
   "from_line": "[phone]",
   "to_line": "[phone]",
   "call_started_at": "2022-01-27T15:31:40+01",
   "direction": "inbound"
 },
 "comment": {
   "title": "Call via MyCTI App",
   "call_fields": [
      "from_line",
      "to_line"
   ],
   "author_id": 7236,
   "display_to_agent": 7800,
   "subject": "New Ticket"
 }
}

Alternatively, make a request to the Talk Partner Edition voice comment endpoint by passing the call_id of the call record you previously created and the fields from that call record that you want to display in the comment. The call record must have a ticket associated with it. See Creating a call record for details.

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

{
  "title": "Call recording",
  "call_fields": [
    "agent_id",
    "end_user_id",
    "answered_by",
    "from_line",
    "to_line",
    "call_started_at",
    "call_type",
    "end_user_location",
    "ivr_destination_group_name"
  ]
  "author_id": 7236,
  "display_to_agent": 7800,
}

Property	Description
agent_id	The id of the agent that answered (inbound) or placed (outbound) the call. If not present, the submitter of the request is used
end_user_id	The id of the end user who called (inbound) or answered (outbound) the call
answered_by	Instructs the voice comment to use either the agent's name for inbound calls (retrieved from agent_id) or the end user's name for outbound calls (retrieved from end_user_id) following the "Answered by" label. For an inbound call, both agent_id and answered_by must be provided, otherwise, no information is shown for the "Answered by" label. For an outbound call, both end_user_id and answered_by must be provided, otherwise, no information is shown.
author_id	The id of the comment author, represented by the avatar at the top of the comment. We recommend using the end user as the author for inbound calls and the agent for outbound. If author_id is omitted, the system uses end_user_id instead. If end_user_id is not present, the submitter of the request is used
display_to_agent	Screen-pops the ticket to an agent after adding the comment

Examples

A voice comment with just the title:

An expanded voice comment with title, call direction, call start time, end user's location, and wait time:

An expanded voice comment with title, call direction, call start time, end user's location, wait time, and recording URL:

An expanded voice comment with title, call direction, call start time, end user's location, wait time, recording URL, and transcript:

Note: The agent must have access to the recording URL to be able to listen to it.

Adding a voice comment in the ticket using the Tickets API

If your requirement is to add a basic voice comment to the ticket and you prefer not to use the Talk Partner Edition call object, you can use the Tickets API with the voice_comment type.

To add a voice comment to a ticket using the Tickets API:

1. Retrieve the id of an existing ticket. See Displaying a caller's ticket in Support.

2. Use the ticket id in a request to the Tickets API to add the voice recording or transcription:

   PUT /api/v2/tickets/{id}.json

   In the request body, specify a voice_comment object for the ticket. For example:

{
  "ticket": {
    "voice_comment": {
      "from": "[phone]",
      "to": "[phone]",
      "recording_url": "http://www.yourdomain.com/recordings.mp3",
      "started_at": "2013-06-24 15:31:44 +0000",
      "call_duration": 414,
      "answered_by_id": 6,
      "transcription_text": "The transcription of the call",
      "location": "Dublin, Ireland"
    }
  }
}

The following fields are required in the request: from, to, started_at, and call_duration.

Zendesk does not store the actual recording file only the link to the file. The audio file must be in MP3 or WAV format. The agent must have access to the URL of the recording in order to be able to listen to it.

See Update Ticket in the API docs.