How to add audio buttons to a VICIdial soundboard

Once a Soundboard record exists, the next job is filling it with audio buttons, the actual clickable tiles an Agent uses on the call. Each button is its own audio entry with a handful of settings that control what plays, what label shows, and where the button lands on screen. None of this appears until the board is embedded in an Agent script, but the buttons themselves are built right on the soundboard record. This post walks through adding them.

The fields on each audio entry

• Audio Filename - the file to play, entered without its extension. It must already be present in the Audio Store to work. It can also show on the button if FILE is in the Audio Display field.
• Audio Name - a descriptive label, shown on the button when NAME is in the Audio Display field.
• Rank and Horz - Rank sets the vertical order shown to the agent and Horz sets the horizontal order, so together they place the button.
• Type - a clickable button that plays a sound, a non-clickable header that only shows its NAME in white text on black, or a blank spacer. There is also a head2r header that extends into a second row of columns.
• Font - larger numbers mean bigger text; add B to bold or I to italicize.
• Level and Add - Level 1 is primary and Level 2 audio always sits below a Level 1 item; the Add control places the new entry on level 1 or underneath one in the level 2 position.

Two settings on the soundboard itself shape how all these buttons look together. The Audio Display field decides whether each button shows the FILE name, the descriptive NAME, both, or hides the button numbers with HIDENUMBERS; the default is FILE-NAME. The Layout field decides the overall arrangement: the default layout builds top-down to fill the script frame, while the columns layout uses separated columns and lets you cap how many appear per row with a Columns Limit. Plan these before you add many buttons, since they affect every tile at once.

How a new button gets placed

flowchart TD
  A[Pick audio file in Audio Store] --> B[Set Audio Filename no extension]
  B --> C[Set Audio Name]
  C --> D{Type}
  D -->|button| E[Plays sound when clicked]
  D -->|header| F[Shows label not clickable]
  D -->|space| G[Blank spacer]
  E --> H[Set Rank Horz and Level]

The diagram captures the flow for each entry: choose a file that exists in the Audio Store, name it, decide whether it is a playable button, a header, or a spacer, then position it with Rank, Horz, and Level. Headers and spacers are how you keep a busy board readable when there are dozens of buttons.

Common gotcha

The number one issue is a missing Audio Store file: if the filename is not actually present there, the button shows but plays nothing. Confirm the upload before adding the entry. Also remember the Audio Display field on the soundboard controls whether the agent sees the FILE name, the NAME, or hidden button numbers, so set it to match the labels you intend. Once your buttons are in place, you still need a script to surface them, which our guide on embedding an iframe in a VICIdial script walks through, and the overall agent screen configuration guide puts it in context.

With files uploaded and entries placed, your soundboard goes from an empty shell to a working panel agents can actually use. To build it on a hosted VICIdial stack, check VICIfast pricing.