Looking up the calling number with VDL_CID_lookup.agi

When a contact calls in, the most useful thing you can do before connecting them to an Agent is identify who they are. VDL_CID_lookup.agi is an AGI (Asterisk Gateway Interface) script that takes the inbound caller ID CID (caller ID) and looks it up against the vicidial_list table to find the matching Lead record. If a match is found, downstream scripts can use that lead context — the name, list assignment, previous notes — to populate the agent screen before the agent even picks up.

VICIdial marks this script as no longer in active use. It has been superseded by the caller ID lookup modes built into agi-VDAD_ALL_inbound.agi (specifically the CIDLOOKUP and CIDLOOKUPRC methods). Understanding how VDL_CID_lookup.agi works still matters if you are maintaining an older VICIdial installation or tracing how a legacy dialplan was assembled.

How the lookup fits into an inbound dialplan

flowchart TD
  A[Inbound call arrives on extension 8369] --> B[Ringing and Wait for CID delivery]
  B --> C[Answer]
  C --> D[VDL_CID_lookup.agi runs]
  D --> E{Caller number found in vicidial_list?}
  E -->|Yes| F[Set lead context on channel]
  E -->|No| G[Continue with no lead context]
  F --> H[agi-VDAD_ALL_inbound.agi routes to in-group]
  G --> H
  H --> I[Agent receives call with lead data]

The script takes no arguments. It reads the inbound caller number directly from the channel variables Asterisk has already populated, then queries vicidial_list for a match. Once done, control passes to the next dialplan step — in practice, a call to agi-VDAD_ALL_inbound.agi with the Ingroup parameters.

exten => 8369,1,Ringing
exten => 8369,2,Wait(1)
exten => 8369,3,Answer
exten => 8369,4,AGI(VDL_CID_lookup.agi)
exten => 8369,5,AGI(agi-VDAD_ALL_inbound.agi,CID-----LB-----IN_TEST-----7275551212-----Closer-----park----------999-----1)
exten => 8369,6,Hangup

Notice the Wait(1) on step 2. This is important on PRI lines where caller ID delivery is slightly delayed. Answering immediately before the CID signal arrives means the lookup runs against an empty or unknown number. The one-second pause gives the PRI time to deliver the caller number before the script starts querying the database.

Why the modern replacement is preferred

The lookup modes in agi-VDAD_ALL_inbound.agi provide options that VDL_CID_lookup.agi does not: restricting the search to a single Lead list, restricting it to one Campaign's lists, searching by alternate phone number, and searching by address3. These restrict variants are useful when you have multiple independent campaigns sharing the same system and do not want a caller to one product's inbound line pulling up a lead from a completely different Lead list with the same phone number.

When you will encounter this script

You are most likely to encounter VDL_CID_lookup.agi when auditing a VICIdial installation that has been in production for several years without a major dialplan revision. Installations built before the CIDLOOKUP modes were added to the inbound script may still be using it. If you are doing a dialplan cleanup on such a system, replace this script's step with the CIDLOOKUP method flag on the agi-VDAD_ALL_inbound.agi call instead. The result is equivalent and the single-script approach is less error-prone to maintain.

The Caller ID spoofing topic is also worth understanding here: if inbound calls arrive with spoofed or obscured caller IDs, both this script and the CIDLOOKUP modes will fail to find a match, and the call will be treated as a new contact.

For the broader picture of AGI scripts in VICIdial, see the VICIdial API and AGI overview. For how the Non-Agent API handles lead data over HTTP, the guide on securing the VICIdial API is a useful companion.

If you are setting up a fresh VICIdial system and want to start with a modern dialplan, every VICIfast plan provisions a fully configured server in under 40 seconds.