How to Use the cm_lookup.agi Call Menu Script

A Call Menu is the VICIdial construct that handles inbound calls before they reach an agent: it plays a prompt, waits for a digit, and routes the caller to an in-group, another menu, or an AGI script Call menu. One of the most useful AGI scripts you can drop into a Call Menu is cm_lookup.agi. It searches your lead database for a record that matches a caller-supplied or caller-ID-derived value, then routes the call one way if a match is found and another way if it is not.

The script is meant for the Custom Dialplan section of a Call Menu, not for the standard digit routes. A lead is a single dialing record in vicidial_list: a phone number plus the name, address, and notes attached to it Lead. When a caller dials in, cm_lookup.agi looks up a field in that table, finds the matching record, and returns the call to either option A or option B in the same Call Menu. Found goes to A; not found goes to B.

The eight flag arguments

Arguments are separated by three dashes ---. Here is what each position controls:

Position 1 is the vicidial_list field to search against. The default is vendor_lead_code, the external ID you load when you import records Vendor lead code. You can substitute any column in the table, such as phone_number or a custom field.

Position 2 defines the scope of the search. SYSTEM searches every record in the database. CAMPAIGNLISTS limits the search to the active lists tied to a specific campaign. CAMPLISTSALL includes both active and inactive lists in that campaign. LIST searches a single list. A campaign is the named outbound job that ties agents to a set of lists Campaign.

Position 3 is the campaign ID or list ID when position 2 requires one. Positions 4 through 8 handle optional write-back operations. Position 4 controls TTS confirmation of the matched record's name (pass a TTS prompt ID for yes, or N to skip). Position 5 controls whether to update the record's phone number with the caller ID of the incoming call. Position 6 controls whether to write the call's unique ID to the lead's address3 field. Position 7 controls whether the call's agent_user_id variable is written to the lead's user field or its comments field. Position 8 controls whether the call's title variable is written back to the lead's title column.

Wiring it into the Call Menu dialplan

In the VICIdial admin panel, navigate to Admin > Call Menus and open or create the menu you want. Scroll to the Custom Dialplan Entry section. The extension pattern determines what digits trigger the lookup. An eight-X pattern matches any eight-digit entry the caller presses:

exten => _XXXXXXXX,1,AGI(cm_lookup.agi,vendor_lead_code---CAMPLISTSALL---TESTCAMP---lastname_oneyestwono---N---N---Y---N)

This line tells Asterisk: when an eight-digit number arrives, run cm_lookup.agi. Search the vendor_lead_code field across all lists (active and inactive) in the campaign named TESTCAMP. If a match is found, speak the last name via TTS and write the agent_user_id to the lead's user field. Do not update the phone number and do not update the address3 or title fields.

How the routing decision flows

flowchart TD
  A[Caller dials in] --> B[Call Menu plays prompt]
  B --> C[Caller enters 8-digit code]
  C --> D[cm_lookup.agi runs]
  D --> E{Match found?}
  E -- Yes --> F[Route to Option A]
  E -- No --> G[Route to Option B]
  F --> H[Agent in-group or next menu]
  G --> I[Fallback prompt or default in-group]

Once the script finishes, control returns to the Call Menu and the A or B option executes whatever route you have configured there: an in-group, another Call Menu, a DID route, or any other supported handle method. The AGI script itself plays no audio; all audio comes from the prompts you configure on the Call Menu options.

A common use case is account-code self-service: a caller presses their account number, the script finds their record, and the A option routes them to a priority in-group rather than the general queue. The B option catches callers whose code is not in the system and plays an error message via a second Call Menu. Because the script can write back to the lead record without agent involvement, it works well in fully automated IVR flows too IVR (interactive voice response).

For a step-by-step walkthrough of creating the Call Menu and wiring the AGI route through the admin panel, see How to Add an AGI to a Call Menu. For the full picture of where cm_lookup.agi fits alongside every other API and AGI function in VICIdial, see the VICIdial API and AGI overview.

If you want a VICIdial server that comes pre-configured with AGI scripting enabled and a working Asterisk dialplan, every VICIfast plan provisions a hardened, production-ready dialer in under 40 seconds.