Data API - Audio File Names

The Audio Files API lets an external system list the audio configured on a CCaaS tenant: queue and hold music, IVR announcements, and queue announcements. It is read-only. Use it to check that a music or announcement name exists before sending it in a skill setting or an IVR configuration. This page is the endpoint reference.

📘

Requires Version 5.67.5 or Higher

The Audio Files API is available on CCaaS version 5.67.5 and later. On an earlier version, the endpoint does not exist and requests fail.


This API returns file names and not actual files

Overview

Base URLhttps://<hostname>.xima.cloud/rest/api
AuthenticationBearer token from an API Service User
Request and response formatJSON
Minimum version5.67.5
AccessRead-only. The API never changes the tenant's audio

Authentication

Every request requires a Service User bearer token in the Authorization header:

Authorization: Bearer <api_bearer_token>

Service Users are created under API Enablement > API Service Users. See API Service Users. Any valid Service User token can read the audio list.

Identifying Audio

Music and announcements are identified by name, not by an id. Wherever audio is configured, such as a skill's queue music or a queue announcement, it is referenced by its name, so the name this API returns is the value to send. Names are matched exactly as returned.

Endpoints

MethodPathSummary
GET/v1/audio-filesList every configured audio file

List Audio Files

GET /v1/audio-files

Lists the tenant's music, IVR announcements, and queue announcements: the same audio an administrator can choose from in the admin pages. Each list is sorted by name, ignoring case.

Parameters

NameInTypeRequiredDescription
AuthorizationheaderstringYesBearer <api_bearer_token>

Responses

CodeDescription
200 OKAn AudioFileList
401 UnauthorizedMissing or invalid token

Example Request

curl -L -X GET 'https://<hostname>.xima.cloud/rest/api/v1/audio-files' \
-H 'Authorization: Bearer <api_bearer_token>'

Example Response — 200 OK

{
  "music": [
    { "name": "Energy by Bensound", "standard": true },
    { "name": "Happiness by Bensound", "standard": true },
    { "name": "Hey by Bensound", "standard": true },
    { "name": "Holiday Hold Loop", "standard": false },
    { "name": "Memories by Bensound", "standard": true },
    { "name": "Smile by Bensound", "standard": true },
    { "name": "Smooth Jazz", "standard": true },
    { "name": "Snap Clap Whistle", "standard": true },
    { "name": "Sunny by Bensound", "standard": true },
    { "name": "The Jazz Piano by Bensound", "standard": true },
    { "name": "Ukulele by Bensound", "standard": true },
    { "name": "Vivaldi", "standard": true }
  ],
  "ivrAnnouncements": [
    { "name": "After Hours Message" },
    { "name": "Main Greeting" }
  ],
  "queueAnnouncements": [
    { "name": "Estimated Wait Reminder" },
    { "name": "Please Hold" }
  ]
}

On a tenant with no uploaded audio, ivrAnnouncements and queueAnnouncements are empty arrays, and music still lists the standard tracks.


Models

AudioFileList

FieldTypeDescription
musicarray of AudioFileStandard music tracks that ship with CCaaS, plus music uploaded in Manage Music Files. Use for queue and hold music
ivrAnnouncementsarray of AudioFileAnnouncements uploaded as IVR announcements. Use in IVR call flows
queueAnnouncementsarray of AudioFileAnnouncements uploaded as in-queue announcements. Use for a skill's queue announcements

Every uploaded file appears in exactly one list: the same one it appears in on the admin pages. If an administrator moves an upload between announcements and music, it moves between lists here too.

AudioFile

FieldTypeDescription
namestringThe audio's name, as shown in the admin pages. This is the value to send wherever the audio is referenced
standardbooleanMusic only. true for a track that ships with CCaaS, false for one the tenant uploaded. Omitted on announcements
📘

What This API Does Not Include

  • Voicemail greetings. Skill and agent voicemail greetings are not listed.
  • The audio itself. The API returns names only; it does not download or stream audio.
  • System prompts. Language-pack audio and built-in system messages are not listed.
  • Silence. The built-in Silence option is not listed as a music track, matching Manage Music Files.

Using the Names

The names this API returns are the values the Skill Management APIs expect for audio settings:

Skill settingList to use
voiceSettings.queueMusicmusic
voiceSettings.queueAnnouncements.announcements[].announcementNamequeueAnnouncements

Read the list first, then send a name exactly as returned. A name that does not exist on the tenant is not applied; see Skill Management APIs for how a skill write reports a value it could not resolve.

⚠️

Audio Names Can Change

Administrators can delete or re-upload audio at any time, and an upload can be moved between announcements and music. Read the list shortly before you use a name, rather than storing names long-term.


Limits

LimitDescription
Version5.67.5 or higher
AccessRead-only. Audio cannot be uploaded, renamed, or deleted through this API
PagingNone. Every list is returned in full

See API Limits & Statuses for statuses shared by every CCaaS API.


Related Pages