Setting up the STIR/SHAKEN API integration

VICIdial signs outbound calls by calling out to the TILTX Call Shaper API before each call is dialed. You set up an API key, store it in a Settings Container, and add one AGI line to the carrier dialplan so every call gets tagged with the SIP headers the carrier needs.

STIR/SHAKEN is the framework that lets a carrier cryptographically vouch for the caller ID on your call. The signing itself happens at the carrier, but VICIdial has to hand the carrier the right information first, and that is what the integration does.

What you need before you start

Three things, in order:

• A TILTX API key. You get this from the TILTX Call Shaper service after signing up.
• A working outbound Carrier already added under Admin then Carriers, with its Dialplan entry dialing calls correctly.
• A caller ID on each campaign that you actually have the right to use, since Call attestation depends on that.

Store the API key in a Settings Container

VICIdial keeps the key in a Settings container so the AGI script can read it at call time. Go to Admin then Settings Containers, add a new one with the Container ID exactly TILTX_SHAKEN_API_KEY and type OTHER, and paste your key into the body. The container ID has to match exactly, or the AGI line will not find the key.

Add the AGI line to the carrier dialplan

In your carrier's Dialplan Entry, add an AGI (Asterisk Gateway Interface) line for the agi-TILTX_SHAKEN.agi script before the line that actually dials out. It needs to run first so the SIP headers are attached to the channel before the Dial command sends the call. A typical line looks like AGI(.../agi-TILTX_SHAKEN.agi,${EXTEN:-10}-----${CALLERID(num)}-----YES-----), passing the dialed number, the caller ID, and a flag.

The script calls the TILTX API, gets back identity data, and sets three SIP headers on the Channel: X-TILTX-ID, Identity, and CAID. Those travel with the INVITE to your carrier, which uses them to sign the call and apply the attestation level.

How the call flows

sequenceDiagram
  participant D as VICIdial Dialer
  participant T as TILTX API
  participant C as Carrier
  participant U as Callee
  D->>T: AGI call (number, caller ID)
  T-->>D: X-TILTX-ID, Identity, CAID
  D->>C: INVITE with SIP headers
  C->>C: Sign call (attestation A/B/C)
  C->>U: Signed call delivered

After saving the dialplan, wait about a minute for the Conf file regeneration, then place a single test call from Campaign Detail. If the headers are arriving, the carrier reports the call as signed. If you also run outbound across more than one trunk, see how to keep this consistent when you run multiple carriers with failover.

Optional add-ons

TILTX offers paid extras the same integration can call: a National DNC check, a disconnected-number check, and a caller-ID NumberRisk score that can flag or replace a risky number before it dials. None of these are required to get signing working — they are reputation and compliance helpers you can add later.

Signing is one piece of a clean carrier setup. For the full picture, start with our VICIdial carrier integration guide. If you would rather skip the server build entirely, a VICIfast box ships with a fixed public IP and a branded subdomain in under 40 seconds — see our pricing to get started.