Treat Sounds as a read-only discovery index
GET /sounds lists the sounds Asterisk exposes through ARI, while GET /sounds/{soundId} retrieves one exact case-sensitive ID. The list can be filtered with lang and format. Use the specific read for a required application prompt and the filtered list for deployment validation; do not scrape filenames from an assumed directory and treat that as the ARI contract.
A sound ID is the media identifier used with a sound: playback URI, not a filesystem path, package name or proof that a channel can hear it. Retain the Asterisk instance, API result and inventory timestamp because package and runtime state can differ across cluster members.
Read every language-format pair
The Sound model contains a required id, a required list of formats and optional descriptive text. Each FormatLangPair contains one language and one format. Validate the pair required by the application instead of accepting the ID alone; a prompt available as one format in one language does not establish another variant.
Treat text as descriptive metadata, usually the spoken words, not a transcript guarantee, localization approval or audio-content checksum. ARI does not expose duration, sample rate, channel count, package version, file hash, speaker, loudness or licensing status in this model. Keep those controls in the media release process.
Keep list filters separate from playback selection
The lang and format query parameters narrow sound lookup. They are useful for preflight inventories, but the filtered result is not a command that pins a later channel playback to that exact variant. Validate the selected channel language and playback request separately.
Build a deployment manifest from required sound IDs and acceptable language-format pairs, compare it with each Asterisk instance and fail the application readiness check when a mandatory pair is absent. Do not silently fall back to an unrelated language merely because the sound ID exists somewhere in the list.
Reconcile the in-memory index after file changes
Asterisk's ARI playback guidance says sounds are read from the sounds subdirectory of the configured astdatadir, commonly /var/lib/asterisk/sounds, and indexed in memory at startup. ARI sound queries consult that index rather than searching the filesystem for every request. Copying a file into a directory after startup therefore does not by itself prove that ARI can discover it.
After a controlled package or file deployment, validate ownership, permissions, directory layout and the running instance, then use the documented module reload sounds operation to re-index and repeat the exact ARI read. Confirm the installed branch and operational policy before reload; a successful filesystem copy or package transaction is not an index result.
Model language fallback and format choice independently
Asterisk documents hierarchical prompt lookup for channel language: a value such as en_GB_female_BT is reduced through progressively broader paths before the base sounds directory. That fallback can intentionally select a more general prompt, so compare the channel's exact language with the returned Sound pairs and the deployed directory hierarchy before calling the result wrong.
Asterisk can choose among available formats based on the call codec and conversion cost. A listed format is therefore inventory evidence, not proof that it will be selected, that the required codec and translation modules are loaded, that transcoding capacity is adequate or that the decoded prompt is audible. Preserve channel, codec and translation evidence for the actual call.
Deploy and test prompts as versioned media
Give one release process ownership of custom sound IDs, language directories, formats, file content, permissions, index refresh and rollback. Avoid overwriting a built-in ID in place without a versioned change record. Validate hashes outside ARI, keep untrusted upload paths away from the Asterisk sounds tree and restrict ARI and host access.
Acceptance covers exact and filtered reads on every instance, intended language selection, a deliberate fallback case, format availability, index refresh after a staged addition, playback state and an authorized audible check. Restore temporary logs and test files. No prompt content, translation performance, compatibility or audible result was tested for this guide.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Asterisk 22 ARI Sounds REST API ↗
- Asterisk 22 ARI REST data models ↗
- Asterisk ARI media guide: playbacks and the sound index ↗
- Asterisk sound-prompt searching by channel language ↗
- Asterisk sound prompts and format selection ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.