cm_phonesearch.agi: Route Inbound Calls by Lead Match

cm_phonesearch.agi matches an inbound caller's phone number against vicidial_list and routes the call to the in-group tied to the best matching lead.

When a previous customer or warm lead calls back in, you usually want them handled by the same team that worked with them originally, not dropped into a generic queue. cm_phonesearch.agi does that routing automatically inside a Call Menu Call menu. It takes the caller's inbound phone number, searches vicidial_list for the best matching lead record, finds the list that record belongs to, determines which campaign owns that list, reads that campaign's default transfer in-group, and bridges the call there.

A lead is a single dialing record — a phone number plus the contact details attached to it Lead. A campaign is the named outbound job that ties a set of agent seats to a group of lead lists Campaign. The script traces from lead to list to campaign to in-group in a single call, with no agent involvement.

The two flag arguments

Arguments are separated by three dashes ---. Position 1 is the country code to search the area code within. The default is 1. Position 2 is the match order, which determines which lead record wins when multiple records share the same phone number. The options are:

entry_newest picks the most recently inserted record. entry_oldest picks the oldest. modify_newest picks the record most recently modified. modify_oldest picks the least recently modified. call_newest picks the record most recently called. call_oldest picks the least recently called. rank_highest and rank_lowest pick by the lead's rank field value. The default is entry_newest.

The most common setup is a DID pointed directly at a Call Menu that runs this script on arrival. In Admin > Call Menus, set the prompt to sip-silence and the Timeout to 1 second. Configure the Timeout option's Route to AGI and enter:

cm_phonesearch.agi,1---entry_newest

Alternatively, you can put the script call directly in the prompt field:

sip-silence|cm_phonesearch.agi,1---entry_newest

The B, C, and D options in the Call Menu must all be configured. The B option handles the success case (match found, in-group found) using the CLOSER Handle Method. The C option handles the case where a lead was found but the campaign has no default transfer in-group, also using CLOSER. The D option handles the not-found case and should use the CID Handle Method to treat the caller as a fresh inbound contact.

How the phone search routing flows

flowchart TD
  A[Inbound call arrives at DID] --> B[Call Menu fires sip-silence]
  B --> C[1-second timeout triggers AGI]
  C --> D[cm_phonesearch.agi searches vicidial_list]
  D --> E{Phone number found?}
  E -- No --> F[Route to option D - CID method]
  E -- Yes --> G[Find list then campaign]
  G --> H{Default in-group found?}
  H -- No --> I[Route to option C - CLOSER method]
  H -- Yes --> J[Route to option B - CLOSER method]

Because the match order determines which lead wins when there are duplicates, choose carefully based on your operational logic. For re-engagement campaigns where the most recently imported lead is most authoritative, use entry_newest. For a support line where the agent who most recently worked the account should get the call back, call_newest paired with a campaign-level transfer in-group pointing to a skills-based routing group gives the most accurate match.

The campaign's default transfer in-group must be populated in the campaign settings. If that field is blank, every matched call will fall through to option C even when a perfect lead match is found.

One thing to keep in mind is that the script only works if the phone number on the inbound CID matches a number stored in vicidial_list. If your lead lists store numbers with a country code prefix (such as 17275551212 instead of 7275551212), make sure the CID your carrier delivers is in the same format. A mismatch on leading digits will send every call to option D even when the contact is in the database.

This script is particularly effective when it is the first stop for a DID that your outbound campaign used as the caller ID for an earlier call. The contact recognizes the number, calls it back, and the script routes them straight to the in-group that the original campaign's agents belong to. No IVR prompts, no digit presses, no hold time explaining which department to choose.

If you have leads appearing in more than one campaign and both campaigns have different default transfer in-groups, the match order argument becomes the tie-breaker. entry_newest routes the caller to whichever campaign imported them most recently, which is usually the active campaign. For a compliance-heavy operation where you need to route based on the oldest record (to track the original consent record), use entry_oldest instead. Choosing the right order prevents the wrong team picking up the call when a lead has been touched by multiple campaigns Lead.

For the step-by-step process of adding an AGI route to a Call Menu option through the admin panel, see How to Add an AGI to a Call Menu. The full API and AGI context lives in the VICIdial API and AGI overview.

Every VICIfast plan provisions a production-ready VICIdial server with full inbound routing, Call Menus, and AGI support active in under 40 seconds.