VICIdial Dialplan Entry: Routing Outbound Calls to a Carrier

The Dialplan Entry is where your carrier trunk earns its keep for outbound calls. It is a short set of rules that say: when a number matches this pattern, log it, dial it out this carrier, and hang up when done. Three lines, but they decide every outbound call's fate.

This post breaks the Dialplan entry down line by line and shows how the prefix and pattern work together. It is one field on the carrier form from adding a carrier trunk.

A worked example

Here is a standard three-line Dialplan Entry for a SIP carrier:

• exten => _91NXXNXXXXXX,1,AGI(agi://127.0.0.1:4577/call_log)
• exten => _91NXXNXXXXXX,2,Dial(newsip:test@10.10.10.15:5060/${EXTEN:2},,tTor)
• exten => _91NXXNXXXXXX,3,Hangup

Reading the pattern

The part after exten => is a match pattern. The leading underscore means "this is a pattern, not a literal number." Then 91 is a Dial prefix — a fixed lead-in that VICIdial adds so the dialplan can recognize a campaign call and route it. After that, NXXNXXXXXX is Asterisk shorthand for a North American 10-digit number, where N is any digit 2 through 9 and X is any digit 0 through 9.

So this rule fires only on numbers that start with 91 followed by a valid 10-digit number. The prefix is how you steer different calls to different carriers; matching it is the first job of the entry.

What the three lines do

1. Priority 1 runs an AGI call to call_log. AGI is the Asterisk Gateway Interface, the hook VICIdial uses to log the call before it goes out.
2. Priority 2 is the Dial command — it sends the call to the carrier peer. ${EXTEN:2} strips the first two digits (the 91 prefix) so the carrier receives the clean 10-digit number, not your internal prefix.
3. Priority 3 hangs up cleanly when the call ends.

That ${EXTEN:2} is the part people miss. The 91 is internal plumbing; your carrier does not want it. Stripping it sends the actual destination number. If you strip the wrong count of digits, the carrier rejects the call as malformed. The flow below traces a single outbound call through the entry.

flowchart TD
  A[Campaign dials number] --> B[VICIdial adds 91 prefix]
  B --> C{Matches _91NXXNXXXXXX?}
  C -->|No| D[No match, call fails]
  C -->|Yes| E[Priority 1: log via AGI]
  E --> F[Priority 2: strip 91, Dial peer]
  F --> G[Carrier sends to PSTN]
  G --> H[Priority 3: Hangup]

Routing to more than one carrier

Because the Dial prefix is part of the match, you can point different prefixes at different carriers. Calls that come in prefixed 91 go out Carrier A; prefixed 81 go out carrier B. That is the basis of both prefix-based routing and simple Failover when one provider has trouble. We dig into multi-carrier setups in running multiple carriers with failover.

The Dialplan Entry pairs with the Account Entry — the dialplan matches and dials, the account block defines the peer it dials. For the full set of fields, see the carrier integration guide.

Wrap up

Once you can read a Dialplan Entry — match the prefixed pattern, log, strip the prefix, dial the peer, hang up — outbound routing stops being a black box. Want a server to practice on? VICIfast provisions a secured VICIdial box in under 40 seconds, ready for your first trunk. See pricing.