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 publicly 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.

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 Talk Partner Edition (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.

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.

Troubleshooting

If the recording fails to play in the browser, upload the file as an attachment to the ticket using the token returned from uploading a call recording.

Example body:

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