Optimizing VICIdial Inbound Routing with CNAM Lookup Integration

Add CNAM Lookup to VICIdial and Stop Answering Inbound Calls Blind

VICIdial systems often receive inbound calls as anonymous 10-digit numbers, leaving agents without context. Implementing Caller Name (CNAM) lookups maps these numbers to subscriber names, enabling data-driven routing before the call reaches the queue.

Why This Matters

In high-volume environments, relying on carrier-side CNAM can cost upwards of $75/month for a 25-agent center due to lack of caching. A technical implementation using a local AGI script with SQLite caching can reduce these costs to $12/month while preventing call blockage through strict 2-second API timeouts. This transition from ‘blind answering’ to data-aware routing is essential for maintaining a competitive 10-20% improvement in inbound conversion rates.

Key Insights

• CNAM integration typically improves inbound conversion by 10-20% according to deployment data (ViciStack, 2026).
• Caching lookup results in SQLite with a 30-day TTL can achieve a 60% hit rate, reducing costs from $0.005 to effectively $0.002 per dip.
• API latency for CNAM queries must target sub-500ms to ensure callers are not left in silence during the lookup phase.
• BulkCNAM offers a low-cost alternative at $0.002/dip compared to standard carrier rates of $0.01.
• Regex-based routing in the dialplan allows for automated identification of business entities like ‘CORP’ or ‘LLC’ to prioritize commercial traffic.

Working Examples

Basic AGI integration in the Asterisk dialplan for CNAM lookup.

[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)

Advanced dialplan routing logic based on CNAM string matching.

[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)

Practical Applications

• Use case: Routing ‘WIRELESS CALLER’ IDs to specific callback in-groups to capture warm leads. Pitfall: Allowing CNAM API outages to block calls; always implement a 2-second timeout and failover.
• Use case: Cross-referencing vicidial_list in an AGI script to auto-populate agent screens with existing lead data. Pitfall: High latency lookups (>1s) causing caller abandonment before the IVR or queue.
• Use case: Mapping Google Ads DIDs to high-priority in-groups while using CNAM to filter for business entities. Pitfall: Neglecting TTL settings in the cache which can lead to stale caller ID data.

References:

• https://dev.to/gamlin/add-cnam-lookup-to-vicidial-and-stop-answering-inbound-calls-blind-4hf4
• https://vicistack.com/blog/vicidial-cnam-lookup-inbound/