Connecting a SIP Carrier to VICIdial: The Complete Guide

VICIdial is a dialer, not a phone company. It decides who to call, when to call, and which agent picks up. But the actual call has to leave your server and travel across the public phone network, and that handoff is the job of a carrier. If you have just stood up a fresh dialer and you are staring at agents who can log in but can't make a single call connect, the missing piece is almost always the carrier trunk. This guide is the map for that whole topic.

We are going to cover the full picture: what a carrier trunk is, the two ways a carrier authenticates you, the four building blocks every trunk entry uses, how to route outbound calls, how to run two or more carriers with automatic failover, how least-cost routing picks the cheapest path, and how STIR/SHAKEN call signing fits in. Each section is short on purpose. Where you need the click-by-click steps, we link out to a focused deep-dive so this page stays readable as a hub.

One framing note before we start. You bring your own carrier to VICIdial. The dialer does not sell you minutes. You sign up with a SIP provider, get credentials or an IP whitelist, and plug those in. That separation is a feature: you can shop carriers on price and quality without touching your dialer.

What a carrier trunk actually is

A carrier trunk is a configured connection between your VICIdial server and a phone-network provider. In VICIdial's admin it lives under Carriers, and each entry is one logical link to one provider. A Trunk carries many simultaneous calls over a single connection, so you do not create one entry per call. You create one entry per carrier relationship, and it carries as many concurrent calls as your provider and server allow.

VICIdial supports SIP and IAX2 carriers out of the box. It does not handle T1, E1, PRI, or analog POTS lines through this screen, because those need physical telco cards and manual conf work. For modern call centers that is fine, because nearly every provider you would pick today is a SIP trunk reachable over the internet. We explain trunks from the ground up here if this is your first dialer.

Registration vs IP authentication

Before a carrier will accept your calls it has to know the calls are really from you. There are two ways to prove that, and picking the right one is the single most common cause of a brand-new trunk that simply will not connect.

With registration, your server logs in to the carrier with a username and password, the same way an email client logs in to a mail server. VICIdial sends a SIP REGISTER message on a timer, and as long as that registration stays alive the carrier knows where to send your inbound calls and trusts your outbound ones. You enter this in the Registration string field, in the form register => user:pass@host:port. Registration is the right choice when your server has a changing or NAT'd IP address, which is why the host=dynamic value shows up so often in carrier examples.

With IP authentication, there is no login at all. You tell the carrier your server's public IP address, the carrier whitelists it, and any SIP traffic from that IP is trusted automatically. No registration string, no password. This is cleaner and slightly more reliable for a server with a fixed public IP, which is exactly what a dedicated hosting box gives you.

For the full decision tree and the exact symptoms of each, read registration vs IP authentication. When you need the precise syntax of the register line itself, the registration string walkthrough covers every field.

The four building blocks of a trunk entry

Every carrier entry is assembled from a small set of fields. Once you know what each one does, every provider's setup is just filling in the same boxes with different values.

1. Registration String: the login line, used only when you authenticate by registration rather than by IP.
2. Account Entry: the peer definition that tells Asterisk how to talk to this carrier. This is where codecs, the peer type, the secret, and the inbound context live.
3. Global String: an optional global variable, like SIP/testcarrier, that the dialplan can reference instead of hard-coding the peer name everywhere.
4. Dialplan Entry: the rules that match a dialed number pattern and send it out through this carrier.

The Account Entry is the heart of it. A typical block disallows all codecs, then allows just the one your carrier wants (often allow=ulaw), sets type=friend so the trunk takes calls in as well as out, and sets context=trunkinbound so inbound calls hit VICIdial's DID handling. The right Codec choice here matters: a mismatch is a classic cause of calls that ring but carry no audio. The account entry field is broken down line by line here.

The Dialplan Entry is where outbound calls actually leave. A standard pattern logs the call, dials the number through the peer with the right options, and hangs up. We dissect the dialplan entry here, and the global string field gets its own walkthrough so you can keep your dialplan readable as you add carriers. For the whole assembled entry start to finish, follow the step-by-step add-a-carrier walkthrough.

SIP vs IAX2

VICIdial lets you set the Protocol field to either SIP (Session Initiation Protocol) or IAX2. SIP (and its newer Asterisk variant PJSIP) is the standard nearly every commercial carrier speaks today, so unless your provider hands you IAX2 credentials, choose SIP. IAX2 is an older Asterisk-native protocol that bundles signaling and audio onto one port, handy for Asterisk-to-Asterisk links but rare for a public carrier.

The practical upshot: match whatever your carrier offers, and when both are on the table, pick SIP. We compare SIP and IAX2 for VICIdial in detail here, including the firewall and audio-quality trade-offs.

Conf file templates and template IDs

Once you run more than a couple of carriers, you will notice you are typing the same codec and peer settings over and over. Conf file templates fix that. A template holds a reusable block of parameters, and you attach it to a carrier with a Template ID instead of filling in the Account Entry by hand. Change the template once and every carrier that points at it updates together.

A Template ID is 2 to 15 characters, no spaces. One rule worth remembering: the per-account secrets do not belong in a shared template. Fields like secret, username, accountcode, account, and mailbox stay on the individual carrier entry, because they are unique to each one. Everything generic, like your allowed codecs, goes in the template. The template ID field is explained here, with examples you can copy.

Routing outbound calls to the right carrier

When an agent or the dialer places a call, VICIdial does not magically know which trunk to use. It matches the dialed string against Dialplan patterns, and the first matching pattern wins. That is why a Dial prefix matters so much. VICIdial prepends a configurable prefix to the number, the dialplan pattern keys off that prefix, and the matching Dialplan Entry routes the call out a specific carrier. Change the prefix and you change which carrier the call rides.

The dialplan also reshapes the number before it leaves. In the classic example, a pattern like _91NXXNXXXXXX matches a 1 plus a ten-digit number, and the dial line uses ${EXTEN:2} to strip the leading 9 and 1 before handing the call to the carrier. Stripping and adding digits this way lets you keep one internal dialing convention while sending each carrier exactly the format it expects.

Here is the high-level flow from agent to carrier so you can see where the routing decision happens.

flowchart TD
  A[Agent or dialer places call] --> B[VICIdial adds dial prefix]
  B --> C{Match dialplan pattern}
  C -->|Pattern 1| D[Strip or add digits]
  C -->|Pattern 2| E[Strip or add digits]
  D --> F[Dial out Carrier A]
  E --> G[Dial out Carrier B]
  F --> H[Carrier to PSTN]
  G --> H
  H --> I[Called party rings]

For the full mechanics, outbound dialplan routing is covered end to end here. Mapping a dial prefix to a specific carrier is its own focused piece, and stripping and adding digits in the dialplan walks through ${EXTEN} surgery with concrete patterns.

Running multiple carriers with failover

No carrier is up one hundred percent of the time, and no single carrier is the cheapest to every destination. Both problems are solved by running more than one trunk and arranging them so a call that fails on the first carrier rolls over to the next. That rollover is Failover, and in VICIdial it is built right into the dialplan: list a second Dial line in the same pattern with a higher priority, and if the first carrier returns congestion or a busy peer, the call falls through to the backup.

The discipline is to design failover before you need it, not during an outage. Decide which carrier is primary, which is backup, and what counts as a failure worth rolling over for. Running multiple carriers with failover lays out the dialplan pattern, and VICIdial Server Trunks shows how to reserve and cap lines per campaign so one campaign cannot starve another of channels.

Least-cost routing

Failover asks which carrier is up. Least-cost routing asks which carrier is cheapest for this specific number. Different providers charge different rates by region, area code, and country, so a smart setup looks up the destination and sends the call out whichever carrier is cheapest to that destination. VICIdial supports this with an LCR table keyed on the NPANXX (the area code plus prefix) and an AGI script that sets the trunk variable per call.

Least-cost routing is the natural next step once you have failover working and more than one carrier with overlapping coverage. Least-cost routing in VICIdial explains the rate-deck logic and how it interacts with your failover order so cost optimization never breaks reachability.

STIR/SHAKEN and call attestation

If you call US or Canadian numbers, STIR/SHAKEN is no longer optional. It is the framework that lets carriers cryptographically sign a call so the terminating network can confirm the calling number is legitimate. A well-signed call earns higher Call attestation, which is the difference between your number showing the business name and your number showing as Spam Likely. Sign poorly and your answer rates collapse.

In VICIdial this is wired through an AGI script that runs before the call leaves, tagging it with the identity headers your carrier needs to route it with full attestation. It requires a recent VICIdial revision and a small dialplan addition placed before the Dial line that sends the call out. The signing service and the attestation policy ultimately live with your carrier, so this is a place where the trunk config and your provider relationship meet.

For the concepts, the STIR/SHAKEN overview is the place to start before you touch any dialplan.

Server-level trunk assignment

Each carrier entry is tied to a Server IP, which is the box that carrier lives on. Set it to a specific server and the trunk is generated only there. Set it to 0.0.0.0 and the entry is pushed to every active Asterisk server, which is handy in a cluster but rarely what you want on a single box. On a single-tenant server the answer is simple: point the carrier at that one server's IP.

Beyond placement, VICIdial Server Trunks let you cap and reserve outbound lines per campaign so a busy campaign cannot consume every channel. This keeps a server predictable when several campaigns share one carrier. The companion server trunks guide covers the reservation math and the Max VICIdial Trunks ceiling that governs the whole server.

Picking the carrier itself

All of the config above assumes you have already chosen a provider, and that choice shapes everything downstream: your codec, authentication method, attestation, and per-minute cost. Coverage, channel limits, calls-per-second caps, and audio quality vary widely, and the cheapest rate deck is not always the one that gets your calls answered.

If you are still deciding, our guide to choosing a SIP carrier walks through what to compare before you sign anything.

How a call actually flows

To tie it together, here is the path of a single outbound call from the moment an agent triggers it to the moment audio is bridged. Every box you configured shows up somewhere in this sequence.

sequenceDiagram
  participant AG as Agent
  participant VD as VICIdial
  participant DP as Dialplan
  participant CA as Carrier
  participant PS as PSTN
  AG->>VD: Request next call
  VD->>DP: Apply dial prefix and pattern
  DP->>DP: Strip or add digits
  DP->>CA: INVITE via trunk
  CA->>PS: Route to called party
  PS-->>CA: 200 OK answered
  CA-->>VD: 200 OK
  VD-->>AG: Bridge audio

Read it left to right: the agent asks for a call, VICIdial applies the prefix and matches a dialplan pattern, the pattern reshapes the digits and sends an INVITE out the trunk, the carrier reaches the PSTN, and when the called party answers, audio is bridged back to the agent. STIR/SHAKEN signing, if enabled, slots in just before that INVITE leaves.

How VICIfast handles this for you

You can do every step above by hand, and many operators do. But most of the pain in carrier integration is not the concepts, it is the conf-file plumbing: getting the Account Entry codec line right, remembering which secret cannot go in a template, waiting on conf regeneration, and reading sip show peers at the CLI to find out why a peer is unreachable.

VICIfast gives you a hardened, ready VICIdial server in under 40 seconds, on a single-tenant box with a public IP, which is exactly what IP-authenticated carriers want. You still bring your own carrier and own the trunk config, but you start from a clean, secured install instead of a blank Ubuntu server. The dialer is yours; we handle the part nobody enjoys.

From here, pick the deep-dive that matches where you are. New to trunks? Start with what a carrier trunk is. Ready to build one? Follow the add-a-carrier walkthrough. Scaling up? Move on to multiple carriers and failover. And when you would rather skip the server setup entirely, spin up a dialer in under a minute. See pricing.