How to wire a soundboard to a VICIdial script

Creating a Soundboard record does not put it in front of anyone. To make the buttons appear, you embed the soundboard inside an Agent script using a small iframe snippet. The two are joined by the Soundboard ID, and getting that link right is the whole job. This post walks through wiring them together.

The script snippet

Inside the script body you place an iframe that points at vdc_soundboard_display.php. It carries the API user, the API pass, a bcrypt flag, and the soundboard_id, and it is styled with a transparent background so it blends into the script frame. The single most important piece is the soundboard_id value: it must match the Soundboard ID you set on the soundboard record exactly. Swap the example ID for your own, like customer_order_test, and the iframe loads that specific board. Everything else in the snippet is presentation: the width, height, scrolling, and border settings just control how the board sits inside the agent's view.

• user and pass - the Soundboard API User and password that trigger the audio events.
• soundboard_id - the exact ID of the soundboard record you want to display.
• width and height - sized so the buttons fill the agent script frame comfortably; a generous height keeps a tall board from clipping.

Because the script accepts raw HTML, the iframe is just markup you paste into the script body. There is no separate soundboard-attach setting elsewhere; the embed is the link. That is also why the credentials live in plain sight inside the script source, and the reason a dedicated, low-privilege API account is the smart choice rather than a real agent login. Save the script, and the board becomes available wherever that script is shown.

How the pieces connect

flowchart LR
  A[Soundboard record] -->|Soundboard ID| B[Script iframe]
  B -->|soundboard_id param| C[vdc_soundboard_display]
  C --> D[Renders buttons in script frame]
  D --> E[Agent sees and clicks audio]

As the diagram shows, the Soundboard ID is the thread running through everything. The record defines it, the iframe references it via the soundboard_id parameter, and vdc_soundboard_display.php uses it to render the right buttons inside the script frame. Break that match and the agent sees an empty or wrong board.

Get the script in front of agents

Embedding the iframe is only half the wiring; the script itself still has to reach the Agent. That means assigning the script to the right campaign or in-group so it loads during calls. If you have not done that step before, our guide on assigning a script to a campaign covers it, and the wider agent screen configuration guide shows where scripts sit on the screen.

Common gotcha

Most wiring failures trace back to a soundboard_id typo or a mismatched API (application programming interface) user, since the credentials in the iframe must be a real account with API access. Copy the ID straight from the record rather than retyping it, and paste the user and pass exactly as they appear on the account. If the board loads but the buttons play nothing, the problem is usually the audio files rather than the wiring, so check the Audio Store next. Ready to build this on a managed VICIdial instance? See VICIfast pricing.