How agi-DID_route.agi sends inbound calls where they belong

When an inbound call arrives on a Trunk — the carrier connection that delivers calls to your Asterisk server — VICIdial needs to decide where to send it. The tool that handles that decision for most inbound traffic is agi-DID_route.agi. DID stands for Direct Inward Dial DID (direct inward dialing), which is the specific phone number the caller dialed. This AGI script looks at that number, checks how it is configured in VICIdial, and routes the call accordingly.

This is the standard catch-all for inbound routing. Rather than writing custom dialplan logic for every phone number you own, you define routing rules for each DID in the VICIdial admin interface, and this single script enforces them all. It supports routing to an Ingroup (a named pool of inbound agents), a call menu, an external number, or other destinations depending on what the DID record specifies.

How the routing decision works

flowchart TD
  A[Inbound call arrives on trunk] --> B[agi-DID_route.agi runs]
  B --> C{DID lookup}
  C -- DID found --> D[Read DID routing settings]
  C -- DID not found --> E[Default dialplan handling]
  D --> F{Route type}
  F -- In-group --> G[Send to ingroup queue]
  F -- Call menu --> H[Play call menu options]
  F -- USE-ORIGINATING-DID --> I[Look up the actual dialed DID]
  F -- External --> J[Transfer to outside number]
  G --> K[Agent answers]
  H --> K
  I --> D

Dialplan setup

The recommended placement is in the inbound trunk context. The default VICIdial Dialplan includes a context called trunkinbound for exactly this purpose:

[trunkinbound]
exten => _X.,1,AGI(agi-DID_route.agi)

The wildcard pattern _X. matches any extension of one or more digits, so every inbound call that arrives in the trunkinbound context gets handed to the script regardless of which DID was dialed. The script then reads the EXTEN channel variable — the dialed number — and looks it up in the VICIdial DID table to find the matching route.

The USE-ORIGINATING-DID option

One option worth understanding is USE-ORIGINATING-DID. This appears as the DID pattern value in a call menu AGI route. When a call is transferred from one part of your system to a call menu that has an AGI route using agi-DID_route.agi, the USE-ORIGINATING-DID option instructs the script to look up the DID route settings for the DID the caller originally dialed, rather than using a static DID pattern. This is useful when multiple phone numbers feed into the same call menu but need to produce different routing outcomes based on which number the customer called.

For example, a single call menu can serve as a shared entry point for a sales line and a support line. The sales DID has an in-group configured to route to sales agents, and the support DID routes to a different in-group. With USE-ORIGINATING-DID set, one call menu handles both without needing two separate menus.

The CID (caller ID) (caller ID) of the inbound call is available to the routing logic and can influence what happens downstream, but the primary routing key is always the dialed DID. For a broader look at how AGI routing scripts and the HTTP API work together, see the VICIdial API and AGI overview. If you are working on securing API access to your system, how to secure the VICIdial API covers that topic directly.

If you want a hosted VICIdial system with inbound routing pre-configured and all AGI scripts installed, check the available VICIfast plans — every server ships with a working dialplan and the full set of AGI tools.