How to Use the cm_areacode.agi Call Menu Script

When a caller dials in and you want to send them to a regional team based on where their phone number originates, cm_areacode.agi does that work automatically inside a Call Menu. It reads the caller's inbound CID, pulls the area code, looks it up in the vicidial_phone_codes table to resolve the state, then searches the vicidial_inbound_dids table for a DID whose did_carrier_description field matches that state.

A DID is a phone number routed into your VICIdial system and tied to a handling rule — an in-group, a Call Menu, or a direct extension DID (direct inward dialing). By pointing a state's DID to a specific in-group Ingroup, you can ensure callers from Florida reach the Florida queue and callers from Texas reach the Texas queue, all without the caller pressing a single digit.

The five flag arguments

Arguments are separated by three dashes ---. Position 1 is the country code to search the area code within. The default is 1 (North America). Position 2 is the number of digits in the area code. The default is 3. Position 3 is a DID prefix to filter by when searching for the destination DID. The default is 999. This lets you maintain multiple DID groups and have the script target only the ones with the right prefix. Position 4 is the name of a vicidial_list field to update when the call is already tagged to a lead. Position 5 is the value to write to that field.

Two fallback routes exist. If the area code is not found in vicidial_phone_codes, the call goes to option D in the Call Menu. If the area code resolves to a state but no matching DID is found, the call goes to option C. A successful state-to-DID match sends the call on to that DID for normal inbound handling.

Setting up the Call Menu

In Admin > Call Menus, create or open the menu that will act as the routing entry point. Set the prompt to sip-silence so nothing plays while the lookup runs. Set the Timeout to 1 second. Then configure the Timeout option's Route to AGI and enter the script call in the AGI field:

cm_areacode.agi,1---3---999

Because the script fires on timeout rather than on a digit press, no digit input is required from the caller. The call simply arrives, waits one second for the Timeout to fire, the AGI runs, resolves the state, and the caller is bridged to the matched DID handling.

How the area code routing decision flows

flowchart TD
  A[Inbound call arrives] --> B[Call Menu prompt fires sip-silence]
  B --> C[1-second timeout triggers AGI]
  C --> D[cm_areacode.agi reads CID area code]
  D --> E{Area code in vicidial_phone_codes?}
  E -- No --> F[Route to option D]
  E -- Yes --> G[Resolve to state]
  G --> H{State DID found with prefix?}
  H -- No --> I[Route to option C]
  H -- Yes --> J[Bridge call to matched DID]

The DID prefix filter in position 3 is the key to maintaining clean routing tables. If you assign the prefix 999 to all your state-routing DIDs, the script will never accidentally pick up a DID from a different routing group that happens to have the same state label in its description field. Use distinct prefixes for each routing family and the lookups stay isolated.

Options C and D in the Call Menu should always be configured. A common pattern is to send option C (state found but no DID) to a general in-group that handles all states, and option D (area code not found) to a prompt that asks the caller to press a digit to select a region manually through your IVR menu IVR (interactive voice response). This gives unknown callers a graceful path instead of a dead end.

For the full process of attaching an AGI script to a Call Menu option through the VICIdial admin interface, see How to Add an AGI to a Call Menu. The broader context is in the VICIdial API and AGI overview.

Every VICIfast plan deploys a fully configured VICIdial server with DID routing, Call Menus, and AGI support ready in under 40 seconds.