Letting agents dial in with agi-AGENT_dial_in.agi

Not every agent sits in front of a softphone that auto-registers. Remote agents, home workers, and people using physical desk phones often need to call in to establish their phone leg before the Agent session starts. That is the job of agi-AGENT_dial_in.agi. The agent dials a designated Extension — a number in your Asterisk Dialplan — and the script prompts them for their user ID and passcode, validates both, then bridges their phone into their active VICIdial session.

One constraint applies to all login values: the user ID and password must be digits only. Alphanumeric credentials cannot be entered over DTMF (the tone signals a keypad generates), so any agent account using this dial-in method needs an all-numeric password set.

You reach for this script in a few common situations. The first is a Remote agent working from home on a cell phone or a regular landline, where there is no softphone to register against the server. The second is a phone room where agents share desk handsets and log in to whichever seat is free, so the phone leg and the browser session need to be tied together at login time. The third is a fallback path for when an agent's primary Webphone fails to connect — rather than troubleshooting registration mid-shift, the agent dials the extension and is bridged in within seconds. In all three cases the browser side of the Agent session is opened normally, and this script only handles the audio leg.

How the dial-in flow works

sequenceDiagram
  participant Agent as Agent phone
  participant AGI as agi-AGENT_dial_in.agi
  participant DB as VICIdial DB
  Agent->>AGI: Dial extension 2345
  AGI->>Agent: Prompt for user ID then press #
  Agent->>AGI: Enter user ID digits
  AGI->>Agent: Prompt for passcode then press #
  Agent->>AGI: Enter passcode digits
  AGI->>DB: Validate user ID and password
  DB-->>AGI: Valid match found
  AGI->>Agent: Forward to active agent session

The script prompts the caller for their user ID first, asking them to press the pound key to confirm. Then it prompts for the passcode in the same way. Once both values are validated against the VICIdial database, the call is forwarded directly to the agent's active session. If the agent has not opened the VICIdial agent screen yet, there is nothing to forward to — the agent must start the session in the browser before dialing in.

Dialplan setup

The simplest setup assigns the script to a single extension:

exten => 2345,1,Answer ; Answer the line
exten => 2345,2,AGI(agi-AGENT_dial_in.agi)
exten => 2345,3,Hangup

The Answer step matters: the script needs an answered channel before it can play prompts and collect DTMF, so do not skip it. Pick an extension number that does not collide with any other dialplan pattern or agent Extension on the box. A number like 2345 that is short and easy to recall is a reasonable choice, because agents will dial it from memory at the start of every shift. If you run multiple campaigns from one server, a single dial-in extension serves all of them — the agent's user ID is what ties the call to the right Campaign and session, not the extension they dialed.

The script can also be attached to a Call menu as an AGI route entry. When used inside a call menu with both optional flags set to Y, the format is:

agi-AGENT_dial_in.agi,Y---Y

The two optional settings

Setting 1 controls whether the script requires a password at all. The default is N (password required). Setting it to Y allows login with a user ID only and no passcode. There is also a special value: CONTACTS makes the script look up the user ID against the office_num field in the contact_information table rather than the standard agent user table, which is useful in contact-center environments where agents are tracked separately.

Setting 2 changes what happens after a valid or invalid entry. The default is to go directly to the agent session. Setting it to Y redirects valid logins to the A option on the call menu and invalid entries to the B option. This lets you use the dial-in script as a branching gate — authenticated callers continue, unauthenticated callers go somewhere else — without writing custom dialplan logic.

This script pairs naturally with Remote agent setups where agents are not on the same local network as the server. For the full picture of how dial-in scripts, routing scripts, and the HTTP API all fit together, see the VICIdial API and AGI overview. If you are deciding which API surface to use for agent interactions, the non-agent API vs agent API comparison is a useful reference.

Every VICIfast plan ships with the full AGI script set already installed, so you can add the dial-in extension to your call menu or dialplan without downloading or compiling anything manually.