Asterisk Gateway Interface

AGI (Asterisk Gateway Interface) is a protocol that allows Asterisk to execute external programs during call processing. When a call reaches an AGI step in the dialplan, Asterisk launches an external script (written in any language — Perl, PHP, Python, etc.) and communicates with it through stdin/stdout. The script can control call flow, play audio, collect DTMF input, query databases, and make routing decisions.

How It Works in VICIdial

VICIdial uses AGI scripts extensively for its core call handling logic. When the dialer places an outbound call and it is answered, an AGI script processes the call — performing AMD detection, looking up the lead in the database, selecting the appropriate agent, and bridging the call into a ConfBridge conference. Inbound calls pass through AGI scripts that handle DID routing, call menu execution, and queue placement.

AGI scripts run as separate processes forked by Asterisk for each call. This means each concurrent call using AGI consumes system resources (memory, CPU, file handles). On high-volume VICIdial servers handling hundreds of concurrent calls, the overhead of forking AGI processes can become significant.

VICIdial’s AGI scripts are written in Perl and located in the /var/lib/asterisk/agi-bin/ directory. Key scripts include agi-VDAD_ALL_outbound.agi (outbound call handling) and agi-VDADfirstreq.agi (inbound call processing).

Why It Matters

AGI is one of the primary mechanisms through which VICIdial extends Asterisk’s capabilities beyond basic PBX functionality. Custom AGI scripts enable advanced features like CRM integration, dynamic call routing based on external data, custom IVR logic, and real-time lead data lookup during call processing.

For VICIdial customization, understanding AGI provides the ability to modify call handling behavior at the deepest level. However, AGI script modifications require careful testing — a bug in an AGI script can affect all calls. FastAGI is the recommended alternative for performance-sensitive deployments. See the VICIdial setup guide for AGI configuration details.