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".
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_disposition": "Call again later",
"transcript": "My printer is on fire!",
"title": "Call via MyCTI App",
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.
"title": "Call via MyCTI App",
"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.
"title": "Call recording",
|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
|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
|display_to_agent||Screen-pops the ticket to an agent after adding the comment|
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.
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
To add a voice comment to a ticket using the Tickets API:
Retrieve the id of an existing ticket. See Displaying a caller's ticket in Support.
Use the ticket id in a request to the Tickets API to add the voice recording or transcription:
In the request body, specify a
voice_commentobject for the ticket. For example:
"started_at": "2013-06-24 15:31:44 +0000",
"transcription_text": "The transcription of the call",
"location": "Dublin, Ireland"
The following fields are required in the request:
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.