Listening to a phone with agi-phone_monitor.agi

Call monitoring — listening to a live call without interrupting it — is a standard supervision tool in any call center. VICIdial provides agi-phone_monitor.agi to let managers dial in and attach to an active Agent session by entering the agent's user ID or Extension. The script supports two modes: listen-only, where the manager can hear the call but cannot speak, and barge, where the manager can be heard by both the agent and the caller.

This is a phone-based alternative to the web supervisor panel. It is useful when a supervisor is on a mobile or desk phone and wants to check in on a call without opening a browser.

There are a few moments when this script earns its place. A floor manager doing quality checks can dial in between meetings and listen to a handful of live calls without sitting at a desk. A trainer can use BARGE mode to whisper guidance during a new Agent's first calls, then drop back to LISTEN. And during an escalation, a supervisor who is away from their workstation can attach to the exact session a customer is complaining about, identified by the agent's user ID, and hear what is happening in real time. Because the entry point is just an extension, it works from any phone that can reach the server, including a cell on the road.

How the monitor session connects

flowchart TD
  A[Supervisor dials monitor extension] --> B[agi-phone_monitor.agi runs]
  B --> C[Prompt for user ID or phone extension then press #]
  C --> D{Lookup type}
  D -- USER --> E[Find agent by user ID]
  D -- PHONE --> F[Find agent by phone extension]
  D -- PLOGIN --> G[Find agent by phone login]
  E --> H{Active agent session found?}
  F --> H
  G --> H
  H -- Yes --> I{Mode}
  H -- No --> J[Prompt fails / no connection]
  I -- LISTEN --> K[Silent monitor only]
  I -- BARGE --> L[Supervisor heard by agent and caller]

Setup requirements

This script has one hard requirement that is easy to overlook: it needs custom dialplan lines added to your extensions.conf file, separate from the AGI entry point itself. These lines define the conference bridge extensions that the monitoring session uses. The two required blocks are:

; quiet entry, listen-only conferences for VICIDIAL
exten => _588600XXX,1,Dial(${TRUNKblind}/56${EXTEN:2},55)
exten => _588600XXX,n,Hangup()

; barge conferences for VICIDIAL
exten => _598600XXX,1,Dial(${TRUNKblind}/57${EXTEN:2},55)
exten => _598600XXX,n,Hangup()

These lines must be placed in the same location as the other VICIdial custom dialplan additions. Without them, the AGI script will start but will not be able to connect the supervisor to the conference bridge that holds the agent's active call.

Parameters and call menu usage

The script takes up to four parameters. Parameter 1 selects the lookup method: USER (default) looks up by VICIdial user ID, PHONE looks up by the phone extension field on the agent record, and PLOGIN looks up by the phone login string. Parameter 2 controls whether the session is logged to the API log: Y or N (default N). Parameter 3 sets the mode: LISTEN (default) or BARGE. Parameter 4 accepts a pre-populated ID to skip the prompt entirely, which is useful when the context itself already knows which agent to monitor.

As a call menu AGI route entry:

agi-phone_monitor.agi,USER---N---LISTEN---

The choice between LISTEN and BARGE is the one to think about. LISTEN attaches the supervisor in a quiet, listen-only conference — the agent and the caller cannot hear them, which is what you want for unobtrusive quality monitoring. BARGE puts the supervisor into the conference with two-way audio, so anything they say is heard by both the agent and the customer. Use BARGE deliberately, because a stray comment lands directly in the customer's ear. The conference patterns in the dialplan reflect this split: the _588600XXX pattern carries the listen-only bridge, and _598600XXX carries the barge bridge.

Beyond a Call menu entry, the script can be wired as a direct extension transfer into the up_monitor_exit context on the s extension. That path lets a supervisor exit the monitor with a DTMF key press rather than hanging up the whole call, which is handy when moving from one agent to the next. Parameter 4, the pre-populated ID, is what you set when the context already knows which agent to monitor — for example a per-agent monitor extension where no prompt should be played at all.

Like the other dial-in AGI scripts, the user ID or phone extension values entered at the DTMF prompt must be digits only. The SIP (Session Initiation Protocol) channel variables and Agent session lookup all depend on the numeric ID matching an active session in the VICIdial database.

For the full picture of how AGI scripts and the API surface fit together in VICIdial, see the VICIdial API and AGI overview. If you are also looking at what data the API exposes about agent activity, how to read VICIdial API responses is a good companion.

Every VICIfast plan ships with the AGI scripts installed and the base dialplan in place — you add the custom dialplan blocks for the monitor conferences and the feature is ready to use.