How to attach an AGI script to a call menu

VICIdial call menus accept AGI scripts as actions, letting you add database-driven routing and custom logic without editing extensions.conf directly.

A Call menu in VICIdial is an in-database construct that tells Asterisk what to do with an inbound call: play a prompt, collect a digit, route to an IVR (interactive voice response) branch, or hand off to a script. That last option — attaching an AGI (Asterisk Gateway Interface) script — is where menus gain real flexibility. Instead of editing extensions.conf and reloading Asterisk every time the routing logic changes, you configure the AGI in VICIdial admin and the behavior updates immediately on the next call.

flowchart TD
  A[Inbound call hits DID] --> B[agi-DID_route.agi looks up DID]
  B --> C[DID points to a Call Menu]
  C --> D[Call Menu plays prompt]
  D --> E{Digit pressed or AGI route?}
  E -- Digit pressed --> F[Route to in-group or extension]
  E -- AGI route configured --> G[Asterisk runs AGI script with args]
  G --> H[AGI queries DB and decides next step]
  H --> I[Call continues on new path]

The most common pattern starts with an inbound call entering the Dialplan through the default trunkinbound context, where agi-DID_route.agi picks up the call and checks the dialed number against VICIdial's DID table. If that DID points to a call menu, VICIdial runs the menu. A menu can then call another AGI as one of its routing actions.

In the call menu admin screen, each option (digit 0–9, plus timeout and invalid) can be assigned an action. One of those actions is "AGI". When you choose AGI as the action type, a text field appears where you enter the script name and its arguments as a single comma-separated string:

# Example: attach agi-AGENT_route.agi to a call menu option
agi-AGENT_route.agi,default---AGENTDIRECT---ACTIVE

# Example: agent dial-in with all options spelled out
agi-AGENT_route.agi,default---AGENTDIRECT---LOGGED_IN---if-u-know-ext-dial---X---invalid---please-try-again---3---TEST_IN3---pbxtransfer---outside-transfer---

# Matching dialplan extension for 4-digit agent IDs
exten => _XXXX,1,AGI(agi-AGENT_route.agi,default---AGENTDIRECT---ACTIVE)

Arguments to the script are positional. They are separated by triple dashes (---). The first position for agi-AGENT_route.agi is the DID pattern to use for in-group settings. The second is the AGENTDIRECT in-group to send calls to. The third controls whether VICIdial looks for an ACTIVE agent or any LOGGED_IN agent. Subsequent positions handle the digit prompt, validation length, audio files for invalid entries, retry count, no-agent fallback in-group, and audio before the no-agent route. Any position you want to leave as default can be left blank between the dashes.

Scripts that also need a Custom Dialplan Entry

Some AGI scripts can run from a call menu alone. Others require a corresponding entry in the System Settings "Custom Dialplan Entry" field to work. A call menu AGI route tells VICIdial to run the script during an inbound session; a Custom Dialplan Entry adds the Asterisk-level extension context that the script relies on. Scripts like agent_monitor.agi need both: the call menu entry so a caller can reach it, and the custom dialplan context so the monitor session can establish correctly.

If an AGI script requires a Custom Dialplan Entry and that entry is missing, calls that hit the AGI route will fail silently or produce an Asterisk "application not found" error. Always read the script's documentation before attaching it to a call menu in production.

The Extension used in the dialplan when you add a script directly — rather than through a call menu — follows the same argument convention. The difference is that a direct dialplan entry gives you more control over exactly when and how Asterisk invokes the script, while a call menu entry is easier to update without touching the server configuration.

For the broader picture of what AGI scripting is and why it exists, start with the VICIdial API and AGI overview. For details on how the HTTP-based Non-Agent API compares to AGI for runtime control, read the Non-Agent API vs Agent API guide. To get a managed VICIdial server with all AGI scripts pre-installed, see VICIfast plans.