Integrating with Voice QA

Your telephony system can use the ticket Attachments API to store call recordings, ensuring full compatibility with Voice QA.

Since call recordings are stored locally without authentication barriers, Voice QA can access them, transcribe the conversations, and conduct quality assessments.

Note: The Attachment API has a file size limit of 50MB, which is approximately 50 minutes of conversation.

Use the following steps to store call recordings using the attachments API:

• Upload a call recording to Zendesk
• Create a ticket and associate a call object
• Add the voice comment

What you need

Your Zendesk account must have the Voice QA add-on and transcriptions enabled.

Note: Unlike Talk, Talk Partner Edition (TPE) does not offer an option to enable transcription and summarization for QA. To have your account added for transcription, you must notify the Zendesk QA team directly (Voice QA is handled within Zendesk QA) by submitting a ticket to Zendesk customer support. This requirement applies to all accounts.

Uploading a call recording

To upload a call recording to Zendesk, send a POST request to Upload Files.

Example:

POST /api/v2/uploads.json?filename=conversation.mp3

The response includes a token and a content_url indicating where the file is stored.

Example response:

{
  "upload": {
    "token": "0umwYlYebbXyHzVdVhDMi8mB0",
    "expires_at": "2025-02-15T15:08:39Z",
    "attachments": [
      {
        "url": "https://z3nabcd.zendesk.com/api/v2/attachments/32617476483729.json",
        "id": 32617476483729,
        "file_name": "conversation.mp3",
        "content_url": "https://z3nabcd.zendesk.com/attachments/token/jeYIaZaOZtTsvWJ09Zy82WSZA/?name=conversation.mp3",
        "content_type": "audio/mpeg",
        "size": 22987927
      }
    ]
  }
}

Creating the ticket and associating a call object

Once the file is uploaded, use Create a Call Object to create a ticket and associate a call object using content_url as the recording_url.

Example request:

curl https://{subdomain}.zendesk.com/api/v2/calls.json \
  -v -u {email_address}:{password} \
  -d '{
    "app_id": 735264019863524,
    "from_line": "[phone]",
    "to_line": "[phone]",
    "call_started_at": "2025-01-27T15:31:40+01",
    "direction": "inbound",
    "recording_url": "https://z3nabcd.zendesk.com/attachments/token/jeYIaZaOZtTsvWJ09Zy82WSZA/?name=conversation.mp3"
  }' \
  -X POST -H 'Content-Type: application/json'

Adding a voice comment

A TPE voice comment is a unique kind of comment used by Zendesk to display key call-related information in the ticket and to provide controls for playing a call recording. For more information, see Creating a voice comment in a ticket and Create a Voice Comment.

Although the voice comment retrieves its underlying data from the Call Object (eliminating the need to resend field values), each field you want surfaced must still be explicitly named in the call_fields array of the request below.

Important: Populating recording_url on the Call Object alone is not enough for Voice QA to pick up the recording. The field must also be explicitly included in the call_fields array below. The fields listed in call_fields determine what is displayed in the voice comment. If recording_url is omitted, the recording won't appear in the voice comment, won't be playable there, and Voice QA will not be able to find or assess it.

Example request:

curl https://{subdomain}.zendesk.com/api/v2/calls/{call_id}/comments.json \
  -v -u {email_address}:{password} \
  -d '{
    "title": "Call recording",
    "call_fields": [
      "from_line",
      "to_line",
      "call_started_at",
      "recording_url"
    ],
    "author_id": 7236,
    "display_to_agent": 7800
  }' \
  -X POST -H 'Content-Type: application/json'

Alternatively, you can create the ticket, the call object, and the voice comment in a single API request. The difference is in how the voice comment is listed in the ticket. For more information, see Creating a voice comment in a ticket.

Uploading and reusing call recording attachments

The call recording attachment must be uploaded to the ticket at least once to make the recording playable. Once the token has been used during this upload, the recording can be accessed in other tickets without needing to be uploaded again.

Example body:

{
  "ticket": {
    "comment": {
      "body": "Audio file",
      "uploads": ["0umwYlYebbXyHzVdVhDMi8mB0"]
    }
  }
}

Verifying your integration

After completing the steps above, your ticket should contain a voice comment with the call recording embedded in it. To confirm your integration is set up correctly:

1. Open the ticket containing the call.
2. Locate the voice comment.
3. Click the recording control and confirm the recording plays.

If the recording plays directly from the voice comment, your integration is correctly configured and the call is eligible for Voice QA to transcribe and assess.

Troubleshooting tip: If a call recording appears as a standard ticket attachment and plays correctly there, but there is no playable recording in the voice comment itself (or it never shows up in Voice QA), check whether recording_url was included in call_fields on the associated TpeVoiceComment. A populated Call Object without this field present in the voice comment's call_fields is a common cause of "missing from QA" issues.