Silent agent monitoring with agent_monitor.agi

Quality assurance in a call center depends on being able to listen to live calls without alerting the Agent. VICIdial supports this through agent_monitor.agi, a script that lets a manager dial in to an Extension and attach silently to a running Agent session. The script is part of the AGI (Asterisk Gateway Interface) family that ships with VICIdial, and it handles everything: prompting the supervisor for the agent or phone ID, looking up the active session, and bridging the audio in listen-only mode.

"Silent" here means the agent and the caller hear nothing unusual. The supervisor can hear both sides of the conversation. By default the script runs in LISTEN mode; switching to BARGE mode lets the supervisor speak into the call — useful for coaching in urgent situations.

How the monitor session is established

sequenceDiagram
  participant S as Supervisor Phone
  participant AST as Asterisk
  participant AGI as agent_monitor.agi
  participant DB as VICIdial DB
  participant A as Agent Session
  S->>AST: Dial monitor extension
  AST->>AGI: Launch agent_monitor.agi
  AGI->>S: Prompt for user ID or phone login
  S->>AGI: Enter ID and press hash
  AGI->>DB: Look up active agent session
  DB-->>AGI: Session channel found
  AGI->>AST: Bridge supervisor to agent channel
  AST->>A: Attach in LISTEN mode
  S->>A: Supervisor hears both sides silently

Script settings and argument positions

The script takes up to six positional arguments separated by triple dashes. The first argument sets the lookup method: USER matches by user ID, PHONE matches by phone extension, PLOGIN matches by phone login, REDIRECT redirects to the session, and RANDOM selects a session at random. The default is USER.

The second argument is a Y/N flag to log the monitoring event to the API log (default N). The third argument is BARGE or LISTEN (default LISTEN). The fourth is a pre-populated ID for use when the script is called from a context where the target is already known. The fifth is a double-dash-delimited list of campaign IDs that restricts which campaigns the supervisor can monitor — for example TEST--TEST2. The sixth controls whether the script reads out available user IDs to the supervisor before prompting (default N).

# As a Call Menu AGI route entry
agent_monitor.agi,USER---N---LISTEN------TEST--TEST2---N

# As a direct extension in extensions.conf, routing to up_monitor context
exten => s,1,AGI(agent_monitor.agi,USER---N---LISTEN)

The required Custom Dialplan Entry

The lookup requires that the user ID or phone extension being monitored contains only digits. If a user ID includes letters or special characters, the script cannot resolve the session and the monitor attempt fails. If you are using PHONE mode, all phone extensions on the system must also be unique — duplicate extensions across devices will cause unpredictable results.

The script can be invoked from a Call menu AGI route or as a direct extension in the up_monitor context with the s extension. Both paths work; the call menu route is more convenient for environments where supervisors dial a well-known number to start monitoring, while the direct dialplan entry gives tighter control over which callers can reach the context.

For Call monitoring that goes beyond listen-only — including barge and whisper via enhanced monitoring — VICIdial also ships the enhancedMONITORswitch.agi script, which requires no additional configuration beyond the dialplan context.

To understand how AGI scripts fit into VICIdial's broader control surface alongside the HTTP API, see the VICIdial API and AGI overview. For how to wire up a call menu so supervisors can reach the monitor extension without a raw dialplan edit, see the guide on calling VICIdial API functions. A VICIfast managed server ships with all AGI scripts in place and the dialplan pre-configured, so monitoring works from day one.