When an inbound call arrives at your VICIdial system, your agent sees a 10-digit number and nothing else. They answer blind — no idea if it's a hot prospect returning a call, a business lead, or a wrong number. CNAM (Caller Name) lookup fixes that. Dip the caller ID against a national database before the call reaches the agent, and suddenly you have context: a name, a caller type, and the information needed to route intelligently.
What CNAM Actually Does
CNAM maps phone numbers to subscriber names. When you see "JOHN SMITH" on caller ID instead of just a number, that's a CNAM lookup at work. The receiving carrier (or your Asterisk server) queries a CNAM database, which responds with the registered name — up to 15 characters.
For a call center, this gives you agent preparation (seeing "ACME CORP" vs. a bare number), routing intelligence (send businesses to your commercial team, residential callers to consumer agents), lead matching (cross-reference against your vicidial_list to identify returning leads), and basic fraud detection (calls showing "WIRELESS CALLER" from numbers that should be landlines can indicate spoofing).
Two Ways to Set It Up
Option 1: Let your carrier do it. Most SIP trunk providers offer CNAM as an add-on. They perform the dip before delivering the call. The name arrives in the SIP INVITE's From header and Asterisk reads it automatically. Zero configuration on your end. The downside: per-dip charges ($0.004-$0.01), no caching control, and you pay even for calls you don't answer.
Option 2: Do it yourself with an AGI script. More control, lower costs at volume. Write a Python AGI script that queries a CNAM provider's API, caches results in SQLite with a 30-day TTL, and sets the caller ID name before routing. Add it to your dialplan:
[inbound-cnam]
; CNAM lookup before routing to VICIdial
exten => _X.,1,AGI(cnam_lookup.py)
exten => _X.,n,NoOp(CNAM Result: ${CNAM_RESULT})
exten => _X.,n,Goto(trunkinbound,${EXTEN},1)
The self-service approach matters at scale. A 25-agent center handling 500 inbound calls/day at $0.005/dip without caching costs $75/month. With 60% cache hits (common for repeat callers), it drops to $30. Using a cheaper provider like BulkCNAM at $0.002/dip with caching, you're at $12/month.
The timeout on your API call should be 2 seconds max. If the CNAM provider is slow or down, calls proceed without name data. Never let a CNAM outage block your inbound queue. For extra resilience, configure a secondary CNAM provider as failover.
Route Smarter With CNAM Data
Once you have CNAM data on the call, you can make routing decisions in the Asterisk dialplan before VICIdial's in-group routing takes over:
You can use regex in the dialplan to detect business callers:
[inbound-routing]
exten => _X.,1,AGI(cnam_lookup.py)
exten => _X.,n,Set(IS_BUSINESS=${REGEX("(CORP|LLC|INC|LTD|COMPANY)" ${CNAM_RESULT})})
exten => _X.,n,GotoIf($[${IS_BUSINESS} = 1]?business)
exten => _X.,n,GotoIf($["${CNAM_RESULT}" = "WIRELESS CALLER"]?wireless)
exten => _X.,n,Goto(default)
exten => _X.,n(business),Set(__CAMPAIGN=COMMERCIAL_INBOUND)
exten => _X.,n,Goto(trunkinbound,${EXTEN},1)
exten => _X.,n(wireless),Set(__CAMPAIGN=CALLBACK_INBOUND)
exten => _X.,n,Goto(trunkinbound,${EXTEN},1)
exten => _X.,n(default),Set(__CAMPAIGN=CONSUMER_INBOUND)
exten => _X.,n,Goto(trunkinbound,${EXTEN},1)
"WIRELESS CALLER" usually means a mobile callback — likely a lead returning your outbound call. Route those to your callback in-group. Blank or "UNKNOWN" could be spoofed or VoIP — handle with care.
If your AGI script also checks vicidial_list for the caller's phone number, you can set the lead_id as a channel variable so the agent screen auto-populates and route the call to the agent who last spoke with them. A returning lead hears a familiar voice instead of a cold open from a stranger.
DID-to-Campaign Mapping
Proper DID mapping is the foundation for CNAM-enhanced routing. Assign different DIDs to different traffic sources:
- Google Ads DID → highest priority in-group
- TV commercial DID → high volume, lower intent in-group
- Existing customer line → senior agent queue
- Outbound callback number → callback in-group (these are warm leads returning your calls)
The callback DID is the one most shops neglect. When your outbound campaigns use a specific caller ID, the return calls to that number are your warmest inbound leads. CNAM lookup combined with a vicidial_list cross-reference identifies the lead and routes them to the original agent.
In VICIdial admin, go to Inbound > DIDs and set the Extension Context to your CNAM AGI context for each DID that should get name lookup. The calls flow through your custom dialplan context, get the CNAM dip, and then hand off to VICIdial's standard in-group routing.
Performance Notes
Benchmark your CNAM provider's latency from your server:
# Test CNAM API latency — run from your Asterisk box
for i in {1..10}; do
START=$(date +%s%N)
curl -s "https://api.cnam-provider.com/v1/lookup?number=5551234567&api_key=KEY" > /dev/null
END=$(date +%s%N)
echo "Dip $i: $(( (END - START) / 1000000 ))ms"
done
Target under 500ms average. Over 1 second consistently means callers are waiting too long — switch providers or cache more aggressively.
Monitor your cache hit rate. If you're serving 60%+ of lookups from cache, your per-dip costs stay minimal. With a 30-day TTL, you only pay for the first lookup of any given number in a month.
CNAM integration touches /etc/asterisk/extensions.conf, AGI scripts in /var/lib/asterisk/agi-bin/, database queries against vicidial_list, and in-group routing configuration. Getting it wrong means missed routing at best and blocked inbound calls at worst. We've integrated CNAM into VICIdial deployments handling 1,000+ inbound calls per day — the combination of caller identification, lead matching, and intelligent routing typically improves inbound conversion by 10-20% according to our deployment data.
Originally published at https://vicistack.com/blog/vicidial-cnam-lookup-inbound/
Top comments (0)