Routing inbound calls to a logged-in agent with agi-AGENT_route.agi

When an inbound caller needs to reach a specific agent rather than the next available one in a queue, agi-AGENT_route.agi is what handles that routing decision. It sits in your Asterisk Dialplan — the set of rules that control how calls move through your phone system — and it works either inside a Call menu AGI route or as a standalone custom dialplan extension. The result is a direct connection from an inbound call to a named agent's active Agent session.

This is different from sending a call to a general Ingroup (in-group: a named pool of agents who share inbound calls). Here, the caller — or your dialplan logic — specifies an individual agent, and the script confirms that agent is present before bridging the call.

How the routing decision works

flowchart TD
  A[Inbound call arrives] --> B{Prompt for user ID?}
  B -- Yes prompt file set --> C[Caller enters agent user ID]
  B -- No prompt use extension --> D[Use dialplan extension as user ID]
  C --> E{Validate digit count}
  D --> E
  E -- Valid --> F{Agent status check}
  E -- Invalid --> G[Re-prompt up to retry limit]
  G --> C
  F -- ACTIVE or LOGGED_IN --> H[Bridge call to agent session]
  F -- Not found --> I[Route to no-agent in-group or s exten]

The script accepts up to 12 arguments, all passed as a single string with triple-dash separators. The most important ones are:

The parameters

Parameter 1 is the DID pattern used to look up in-group initiation settings. The value default applies when you have not created a specific pattern. Parameter 2 is the AGENTDIRECT in-group name, defaulting to AGENTDIRECT. An AGENTDIRECT in-group is a special in-group type VICIdial uses when routing directly to a named agent rather than pooling the call.

Parameter 3 controls which agent states are eligible: ACTIVE (default) or LOGGED_IN. ACTIVE means the agent is currently on the agent screen and ready. LOGGED_IN is broader and includes agents who are logged in but may be paused. Parameter 4 is an audio filename that, when set, prompts the caller to enter the agent's user ID. If left blank, the script reads the dialed extension directly as the user ID — useful for a dialplan pattern like exten => _XXXX,1,AGI(agi-AGENT_route.agi,default---AGENTDIRECT---ACTIVE) where four-digit extensions map directly to four-digit agent IDs.

Parameters 5 and 8 pair together: parameter 5 sets the required digit count for user ID validation (use X to accept any length), and parameter 8 sets how many re-entry attempts the caller gets before being routed elsewhere. These only apply when a prompt file is configured in parameter 4.

Parameter 9 is the fallback in-group if no valid agent is found. If left blank, the call lands on the s extension in the current dialplan context instead. Parameters 11 and 12 offer two finer controls: parameter 11 plays an audio file when the agent is logged in to the system but not actively logged in to the VICIdial agent screen, and parameter 12 accepts the value PL to search by the agent's phone login field rather than their user ID.

A full call menu example

agi-AGENT_route.agi,default---AGENTDIRECT---LOGGED_IN---if-u-know-ext-dial---X---invalid---please-try-again---3---TEST_IN3---pbxtransfer---outside-transfer---

This tells the script to accept any digit length, play the if-u-know-ext-dial audio prompt, allow three re-entry attempts, and fall back to the TEST_IN3 in-group if no agent is matched.

For a broader look at how this AGI fits alongside other routing tools and the Non-Agent API, see the VICIdial API and AGI overview. If you are comparing what the agent-facing API does versus the back-end non-agent calls, the non-agent API vs agent API guide covers that split clearly.

Every VICIfast plan ships with a fully configured Asterisk dialplan and the complete set of AGI scripts, so you can wire up agi-AGENT_route.agi from day one without any manual script installation.