The VICIdial soundboard API user explained

Two fields on every Soundboard record decide whether audio plays at all: the Soundboard API User and the Soundboard API Pass. They are easy to skim past, but they are the engine room of the whole feature. This post explains what the API user does, why it matters, and how to set it up so a button click safely turns into sound on the call.

What the API user actually does

When an Agent clicks a button on the soundboard control screen, the action does not run under the agent's own login. It runs under the configured Soundboard API User. That account triggers the soundboard audio events, so it must be a valid system user with permission to use the API (application programming interface). The Soundboard API Pass is simply that user's password. Without a working pair, the buttons render but nothing happens when clicked. This design keeps the agent's regular session out of the audio-triggering path entirely, which is both cleaner and safer than letting each agent fire events under their own elevated permissions.

Why a dedicated account is the right move

flowchart LR
  A[Agent clicks button] --> B[Request runs as API User]
  B --> C{API permission set}
  C -->|Yes| D[Audio event triggered]
  C -->|No| E[Click does nothing]
  D --> F[Customer hears recording]

The recommended pattern is a separate API user with reduced permissions, used only for soundboards. The diagram shows why: every click flows through that one account, so its permission set is the only gate. Give it just enough access to trigger audio and nothing more. If that account is ever compromised or its credentials leak into a script, the blast radius is tiny compared to reusing a full-permission login. A useful habit is to name the account so its purpose is obvious, something like soundboard_api, so nobody later mistakes it for a real agent and starts widening its access.

Where the credentials live

The user and pass you enter on the soundboard record get echoed into the iframe inside the script you build, so treat them as semi-public to anyone who can view the script source. That is one more reason not to reuse a privileged login. Manage the account itself like any other user, and keep it tidy within its own User group if you want clean administrative separation. For the bigger picture of how scripts, screens, and accounts fit together, see the agent screen configuration guide.

Common gotcha

The classic failure is an API user that exists but lacks API permission, so buttons silently do nothing. Always confirm the account is valid and API-enabled before blaming the audio files. A second common slip is a password mismatch between the soundboard record and the actual account, often after someone rotates the password but forgets the board still holds the old one. When you change one, change both. When you are ready to embed those credentials, our walkthrough on embedding an iframe in a VICIdial script shows exactly where the user and pass go.

Get the API user right and the rest of the soundboard just works. If you would like a managed VICIdial environment where API users and permissions are simple to provision, take a look at VICIfast pricing.