Setting channel variables with agi-set_variables.agi

Every outbound call your dialer places carries a Lead record behind it — a row in vicidial_list that holds the phone number, name, address, and any custom fields your campaign tracks. Most of the time, VICIdial keeps that data inside the database. agi-set_variables.agi is the AGI (Asterisk Gateway Interface) script that changes that — it runs between the call log step and the trunk dial, reading every column from that lead record and making each one available as a live Dialplan channel variable so your extensions.conf logic, SIP headers, or downstream scripts can act on them in real time.

The most common reason to reach for this script is carrier enrichment. Some SIP trunk providers accept custom SIP headers that let you pass caller context — account numbers, lead codes, or your own CRM reference — without modifying the phone number itself. Without agi-set_variables.agi, none of those fields are visible at the Asterisk channel layer.

How it fits into the dialplan

The script always runs after call_log.agi and before the Dial() application sends the call to the Server trunk. Inserting it in any other position will either miss the call log entry or send headers after the trunk negotiation has already started.

sequenceDiagram
  participant DP as Dialplan
  participant CL as call_log.agi
  participant SV as agi-set_variables.agi
  participant TR as Trunk Dial
  DP->>CL: log call to DB
  CL-->>DP: done
  DP->>SV: set vicidial_list fields as channel vars
  SV-->>DP: vars available eg phone_number lead_id
  DP->>TR: Dial with SIP headers or dialplan vars

Dialplan entries and the argument options

The script accepts a single optional argument that controls what gets sent to the carrier alongside the call. If you leave the argument empty, the fields are set as plain channel variables and nothing extra is added to the protocol layer. Pass SIP to add them as SIP headers, PJSIP for PJSIP headers, or IAX for IAX variable forwarding. You can combine options with an underscore, for example SIP_dialplan, but mixing SIP and PJSIP in the same argument is not supported and will produce unpredictable results.

; Basic: set channel vars only
exten => _91NXXNXXXXXX,1,AGI(agi://127.0.0.1:4577/call_log)
exten => _91NXXNXXXXXX,n,AGI(agi-set_variables.agi,)
exten => _91NXXNXXXXXX,n,Dial(${TESTSIPTRUNK}/${EXTEN:2},,tTor)
exten => _91NXXNXXXXXX,n,Hangup

; Send SIP headers to carrier
exten => _91NXXNXXXXXX,1,AGI(agi://127.0.0.1:4577/call_log)
exten => _91NXXNXXXXXX,n,AGI(agi-set_variables.agi,SIP)
exten => _91NXXNXXXXXX,n,Dial(${TESTSIPTRUNK}/${EXTEN:2},${CAMPDTO},To)
exten => _91NXXNXXXXXX,n,Hangup()

When you add the dialplan suffix, the fields are also accessible in subsequent dialplan steps as named variables. That lets you use a Verbose() line for debugging or pass specific fields like ${phone_code} or ${lead_id} into a custom application lower in the dialplan.

What to watch out for

For PJSIP, the header-setting step runs in a pre-dial handler context, not inline. You define a small handler exten named pjsipheaders that calls the script and returns, then reference it with the b() dial option. If you skip this structure, the PJSIP headers are set after the channel negotiation and the carrier never sees them. The Vendor lead code and other custom fields only appear in the carrier headers if you have them populated on the Lead record before the call is queued.

This script is one of several AGI tools that extend what the dialer can do between the database and the trunk. For a broader look at how AGI scripts and the HTTP API work together, see the VICIdial API and AGI overview. If you are routing calls based on a carrier source parameter, the source parameter guide covers how to trace calls back to their origin.

Every VICIfast plan ships a fully configured VICIdial box in under 40 seconds, with a working extensions.conf that you can extend to include agi-set_variables.agi from day one.