How to Use the CID_change.agi Script to Change Caller ID

When your outbound caller ID (CID) — the number a customer sees on their phone when you call — does not match the area code you are dialing into, answer rates drop. CID_change.agi is a built-in VICIdial AGI script, part of the Asterisk Gateway Interface layer that lets Asterisk hand control to an external program mid-call AGI (Asterisk Gateway Interface), that solves this by swapping the CID before the call goes out to your trunk. You wire it into the dialplan once and every call that passes through that extension gets a fresh caller ID Caller ID spoofing.

The script has two modes. In CID Group mode you give it the name of a CID Group you have defined in VICIdial, and the script first tries to find an active CID within that group whose area code matches the area code of the number being dialed. If it cannot find one, it grabs a random active CID from the group. In fixed mode you pass a specific phone number and every call out of that dialplan extension uses exactly that number, regardless of destination.

The four flag parameters

The script takes four arguments, separated by three dashes. The first is either a CID Group ID (a short alphanumeric name you set in the Admin panel under CID Groups) or a fixed phone number. The second is the number of digits to strip from the front of ${EXTEN} before reading the area code — typically 2 for a dial prefix like 91 (the outbound 9 plus the country code 1). The third is the number of digits in the area code, which is 3 for North American numbers. The fourth is always ${EXTEN}, the current dialplan extension variable — the script needs the full dialed string to know what it is working with.

Dialplan flow

sequenceDiagram
  participant Dialer as VICIdial
  participant AGI as CID_change.agi
  participant CIDGroup as CID Group DB
  participant Trunk as Outbound Trunk
  Dialer->>AGI: call reaches exten _91NXXNXXXXXX
  AGI->>CIDGroup: look up CIDs matching area code
  CIDGroup-->>AGI: matched CID or random fallback
  AGI->>Dialer: set CALLERID(num) to new CID
  Dialer->>Trunk: Dial with new CID in SIP From header

Wiring it into the Custom Dialplan

You do not edit extensions.conf directly on a running VICIdial box. Instead, create a new Call Menu in the VICIdial Admin panel, paste the dialplan lines into its Custom Dialplan Entry field, and then set each phone's Phone Context to that Call Menu ID. All outbound calls from that phone will then run through the CID swap before they hit the trunk.

For CID Group mode, where the group name is testCIDgroup, your dialplan entry looks like this:

exten => _91NXXNXXXXXX,1,AGI(CID_change.agi,testCIDgroup---2---3---${EXTEN})
exten => _91NXXNXXXXXX,n,Goto(default,${EXTEN},1)

For a fixed CID — say you always want to present 9998887112 — the first argument is the number itself, and the strip and area-code fields are left empty (still three-dash-separated):

exten => _91NXXNXXXXXX,1,AGI(CID_change.agi,9998887112---------${EXTEN})
exten => _91NXXNXXXXXX,n,Goto(default,${EXTEN},1)

The Goto(default,${EXTEN},1) line on the second priority hands the call back to the default context where VICIdial's normal outbound dialing happens. Without it the call would hang up after the CID swap rather than continuing to the trunk.

Practical tips

Keep your CID Group stocked with numbers that are genuinely registered to your organization. Using numbers you do not own can violate STIR/SHAKEN attestation rules and result in calls being marked as spam or blocked by the carrier. The area-code matching only works if you have at least one CID in the group for each area code you dial frequently — gaps fall back to a random CID from the group, which defeats the local-presence strategy CID (caller ID).

If you are also using the API to push leads into campaigns Non-agent API, you can pair the CID Group with the campaign's Dial Prefix so outbound calls naturally flow through your CID-swap context without manual dialplan intervention per campaign.

For the bigger picture of how AGI scripts fit alongside the full API and AGI toolkit, see the VICIdial API and AGI overview. If you want to see how to add an AGI to a call menu step by step, read how to add an AGI to a call menu.

If you want a VICIdial box that is already configured and ready to take these dialplan changes without touching a bare server, every VICIfast plan ships a hardened VICIdial installation in under 40 seconds, with the AGI scripts already in place.