agi-VDADfixCXFER.agi: fixing the agent record after a consultative transfer

Consultative transfers are great for the customer and a little messy for the database. When a fronter briefs a closer and then steps off, the call moves onto a different channel, and the record that tracks who is on what call can be left describing a state that no longer exists. agi-VDADfixCXFER.agi is the small cleanup script that fixes that the moment the transferred call arrives.

What goes stale and why

In a Warm transfer done as a consultative handoff, the Fronter talks to the receiving party first, then releases the call. At the instant of release the call lands on another channel. The live-agent record, which VICIdial uses to know which agent owns which call right now, can still point at the old arrangement. Left alone, that mismatch shows up as an agent who looks busy when they are free, or a call that looks attached to the wrong person.

This script runs exactly when the released call arrives on the new channel, and its only job is to update that record so it is accurate again. It is not something an Agent ever sees; it is plumbing that keeps reports and agent states honest. The check happens once, at arrival, so there is no ongoing cost to having it in place. It either has work to do because the record drifted, or it confirms the record is already right and moves on without changing anything.

Where it sits in the dialplan

You add it to your Dialplan on the extensions that carry consultative-transfer traffic. A typical entry matches a pattern such as _8600XXX*. and runs AGI(agi-VDADfixCXFER.agi) with no extra arguments. There is also a longer pattern with several 010* segments in front for the meet-me style routing some setups use. Either way the script takes nothing from the command line; it reads what it needs from the channel and the call context.

sequenceDiagram
  participant Fronter
  participant Closer
  participant Channel as New Channel
  participant Fix as agi-VDADfixCXFER
  participant DB as Live Agent Record
  Fronter->>Closer: Consultative briefing
  Fronter->>Channel: Release the transfer
  Channel->>Fix: Call arrives and triggers AGI
  Fix->>DB: Update record to match reality
  DB-->>Closer: Closer correctly owns the call

Why you should care

If this script is missing from the right extensions, the symptoms are subtle. A Closer might be stuck in a state that does not match the call they are actually on, agent-time reports drift, and the floor manager starts seeing phantom busy agents. On a busy floor those phantom states pile up over a shift, and they are hard to spot because each one looks like a normal in-call agent until you notice the call ended minutes ago. Because nothing throws an error, these problems get blamed on everything except the missing cleanup line. The fix is cheap: make sure the AGI entry exists on every extension that carries released consultative transfers, and confirm it survives any future dialplan edits.

Modern VICIdial no longer needs the old CXFER prefix to do consultative transfers, since there is a CONSULTATIVE checkbox on the agent screen. The behind-the-scenes record fixing, though, still depends on this script being present, so do not assume the checkbox alone covers everything. If your consultative handoffs feel right to agents but your reports look off, this is one of the first places to check.

For the mechanics of the handoff itself, read our explainer on the consultative transfer, and for how it sits alongside every other handoff option, see the transfers and closers guide.

Keeping cleanup scripts like this wired correctly is exactly the kind of thing a managed dialer handles for you. If you would rather not audit dialplan patterns by hand, see our pricing.