How to add an agent soundboard in VICIdial

Adding a Soundboard in VICIdial is a short form, but each field carries weight, and one of them can never be changed later. This walkthrough covers creating the soundboard record itself. The audio buttons that the Agent actually clicks are added afterward, once the shell exists.

Open the add screen

Go to Admin and find Agent Audio Soundboards. At the top of the soundboard listing there is a link to add a new soundboard. Selecting it opens the fields below, which you fill once to define the soundboard before adding any audio. Think of this as creating an empty container: you are naming the board and handing it the credentials it needs, not yet loading any sound into it. The whole flow lives in the admin area alongside the rest of the agent screen configuration guide settings.

Fill the fields

• Soundboard ID - the unique identifier. It can contain only letters, numbers, dashes, and underscores, with no spaces or other special characters. You will reference this exact ID inside the script later, so pick something readable like customer_order_test.
• Soundboard Name - shown to the agent at the top of the soundboard control screen, so make it human-friendly.
• Soundboard Notes - administrative notes only, never shown to agents.
• Soundboard API User and Pass - a valid system user with permission to use the API (application programming interface), plus their password. These trigger the audio events.
• Active - must be Y for agents to use the soundboard. The default is Y.

Of all these, the Soundboard ID is the one to think hardest about, because it is what the script references to find this board. The Name is purely cosmetic and can be reworded anytime, the Notes are a private scratchpad for admins, and Active is a simple on or off switch. The credentials are where most setup time goes, since they have to be a real, API-enabled account rather than a placeholder.

The order of operations

flowchart TD
  A[Open Add New Soundboard] --> B[Set Soundboard ID]
  B --> C[Set Name and Notes]
  C --> D[Set API User and Pass]
  D --> E[Set Active to Y]
  E --> F[Save soundboard record]
  F --> G[Add audio buttons later]

Save the record first, then come back to add audio entries. The diagram shows why the ID and credentials come before anything plays: nothing works until the shell exists and points at a working API account.

Common gotcha

The most frequent mistake is putting a space or stray character in the Soundboard ID, which breaks the link from the script. Keep it to letters, numbers, dashes, and underscores. The other trap is reusing a full-access agent login as the API user; a dedicated reduced-permission account is far safer, because the credentials end up visible inside the script that embeds the board. A third snag is leaving Active set to N during testing and forgetting to flip it, which leaves agents staring at a board that never loads. Once the record is saved, your next stop is creating the script that embeds it, covered in our guide on how to add a VICIdial script.

That is the whole add flow. Build the record, wire the script, then load your audio. If you would rather skip server setup entirely and start configuring soundboards on a ready VICIdial instance, see VICIfast pricing.