Listing audio prompts with the sounds_list API

Every VICIdial system keeps an audio store full of recorded prompts — greetings, IVR (interactive voice response) menus, hold messages and the like. When you are building a tool that lets someone pick one of those files, you need the current list. The sounds_list function on the VICIdial Non-agent API outputs that list straight from the audio store, served by non_agent_api.php. It is one of the simpler read calls in the whole API (application programming interface). For the bigger map of every endpoint, see the VICIdial API and AGI overview.

When you'd use it

It fits any place where a human or a script needs to choose an audio prompt. A custom admin screen that builds a call menu, a deployment script that confirms a freshly-uploaded greeting actually landed, or a dropdown that populates a form field — all of them want the live file list rather than a hard-coded guess. The selectframe format makes the dropdown case especially easy.

How the call works

sequenceDiagram
  participant App
  participant API as non_agent_api.php
  participant V as VICIdial
  App->>API: sounds_list (format, stage)
  API->>V: read audio store directory
  V-->>API: list of audio files
  API-->>App: formatted list
  App->>App: build prompt picker

You send the request, the endpoint reads the audio store directory, and it returns the files in the format and sort order you asked for. Success here is inferred — there is no SUCCESS line, the list of files is the result. If you have not wired up one of these calls before, how to call the non-agent API walks through the basics. If something is misconfigured you get a clear ERROR line instead.

Parameters

There are no required fields beyond the standard user, pass and function. The optional fields shape the output:

• format — how to format the output: tab, link or selectframe
• stage — how to sort the output: date, size or name
• comments — the name of the field to populate (used with the selectframe format)

An example call

http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=sounds_list&format=selectframe&comments=fieldname&stage=date

That returns the audio files sorted newest-first, formatted as a selectframe that writes the chosen value into a field named fieldname. Switch format to tab for a plain machine-readable list, or to link if you want clickable entries. The stage value just reorders the same set of files by date, size or name.

Permissions and a gotcha

The api user must have user_level 7 or higher, or you get NO PERMISSION TO VIEW SOUNDS LIST. The two errors that catch people out are environmental, not permission-related. "audio store web directory does not exist" means the path tied to your user is wrong, and "CENTRAL SOUND CONTROL IS NOT ACTIVE" means the system-wide sound control feature is switched off — neither is fixed by changing the api user, both are a server-config problem. If your VICIdial box uses a lazily-created random folder name for the audio store, make sure a file has actually been uploaded so the directory exists before you call this.

Pulling the live prompt list keeps your tooling in sync with what is actually on the box. If you would rather not manage the VICIdial server behind these endpoints, our managed servers are provisioned in under 40 seconds — see our pricing — or read another live-read companion, reading one agent's live status.