agi-3way_press_agent.agi: the first script behind 3-way press-1 calls

Some teams send qualified calls to an outside agent who is not logged into the dialer at all, just sitting on a regular phone. To stop those calls landing on an unattended line, the outside agent has to press 1 before the customer is connected. VICIdial handles that with a pair of AGI (Asterisk Gateway Interface) scripts, and agi-3way_press_agent.agi is the first one to run.

When this script runs

It fires when an agent places a Three-way call through a special extension that carries a dial override out to the outside agent. The agent triggers it from the transfer-conference frame on their screen; the special extension tells the dialplan to send the call here first. This script is the agent-side half of the feature, the part that kicks off the outbound leg and starts the clock that the outside agent has to beat by pressing 1.

It does not connect anyone on its own. Its job is to launch the call to the outside agent and hand control to the second script once that party answers. Think of this one as the initiator and the next one as the gatekeeper.

The dialplan that invokes it

You wire it in with a pattern-match extension in your Dialplan that answers the channel, plays a moment of silence, then calls the script. A typical block answers the _49907. pattern, plays sip-silence, and runs AGI(agi-3way_press_agent.agi,start---50---30) before a final Hangup. The three dash-delimited arguments are the only knobs you need to understand.

• stage: the value is always start. This script has only one stage, so do not change it.
• 3way agent timeout: the number of seconds after launching the outside-agent call before the script gives up. In the example above that is 50.
• 3way dial timeout: the Asterisk Dial() timeout for the outside-agent call itself. In the example that is 30.

Keep the dial timeout shorter than or close to the agent timeout. If the dial timeout is longer, the outer script can give up while the line is still ringing, which leaves you with a confusing half-launched call and an annoyed customer waiting on the Extension.

How it fits the two-script flow

sequenceDiagram
  participant Agent
  participant Dialplan
  participant PressAgent as agi-3way_press_agent
  participant Outside as Outside Agent
  Agent->>Dialplan: Dial special extension 49907
  Dialplan->>PressAgent: Answer then run start
  PressAgent->>Outside: Launch call with dial override
  Note over PressAgent,Outside: agent timeout and dial timeout apply
  Outside-->>PressAgent: Phone rings then answers

This is the first required script of two for the press-1 feature. On its own it gets the outside agent ringing; the handoff prompt and the press-1 check belong to its partner. If you want the full picture of why press-1 exists and when to use it, read our overview of 3-way press-1 calls. The companion script that runs the outside agent's prompt is covered in our writeup of agi-3way_press_outside.agi.

A few gotchas. The special extension must be reachable in your dialplan, so the _49907. pattern has to exist on the server placing the call. The Playback of sip-silence before the AGI matters because it lets the channel answer cleanly before the script starts timing things. And because both timeouts are passed as plain arguments, a typo in the dash delimiters silently breaks the launch rather than throwing a loud error.

This whole mechanism is part of the larger handoff story in our transfers and closers guide. If wiring dialplan extensions by hand is not how you want to spend your week, a managed dialer ships with this already working. Take a look at our pricing to see what that costs.