VICIdial Carrier Setup: Connecting a SIP Trunk Step by Step

Before you start

• Admin access to VICIdial (Admin → Carriers) and SSH access to the dialer servers.
• Your trunk details from the portal: SIP host, port, authentication method, username and password or the IP addresses to whitelist.
• The CLIs you are approved to present, in E.164 format.
• The public IP addresses of every VICIdial server that will send calls.

Setup steps

1. 1

   Choose authentication

   Use IP authentication if your dialer servers have static public IPs; add them under Endpoints in the portal. Otherwise use username and password registration. IP authentication is simpler and avoids registration timeouts.

2. 2

   Create the carrier

   In VICIdial go to Admin → Carriers → Add a New Carrier. Set Carrier ID to CLIROUTES, Protocol to SIP, Server IP to the dialer server, and Active to Y once testing is complete.

3. 3

   Enter the account entry

   Paste the account entry below into the Account Entry field. It defines how Asterisk talks to the trunk.

4. 4

   Enter the registration string

   If you use registration, add the registration string. Leave it blank for IP authentication.

5. 5

   Enter the dialplan entry

   Add the dialplan entry that strips your dial prefix and sends calls in E.164 to the carrier.

6. 6

   Set caller ID

   Set the campaign CallerID to an approved CLI in E.164 format, and decide whether list-level or in-group CallerID overrides apply.

7. 7

   Set the campaign dial prefix

   In Campaigns → Detail, set Dial Prefix to 9 so calls match the dialplan entry.

8. 8

   Reload and test

   Submit the carrier, then run the verification checks below before activating the campaign.

Account entry (chan_sip)

Most VICIdial builds still use chan_sip for carriers. The entry below is a safe starting point.

[cliroutes]
type=peer
host=sip.example-carrier.net
port=5060
username=YOUR_SIP_USERNAME
secret=YOUR_SIP_PASSWORD
fromuser=YOUR_SIP_USERNAME
fromdomain=sip.example-carrier.net
insecure=port,invite
context=trunkinbound
disallow=all
allow=ulaw
allow=alaw
dtmfmode=rfc2833
qualify=yes
nat=force_rport,comedia
sendrpid=pai
trustrpid=yes

sendrpid=pai sends your caller ID in a P-Asserted-Identity header as well as From, which is how most carriers expect identity between trusted peers. For IP authentication remove username, secret and fromuser.

register => YOUR_SIP_USERNAME:[email protected]:5060

Dialplan entry

VICIdial adds the campaign dial prefix in front of the number. The entry below matches prefix 9, strips it, and sends the rest with a leading +. Adjust the pattern if your lists store numbers without country code.

exten => _9X.,1,AGI(agi://127.0.0.1:4577/call_log)
exten => _9X.,n,ExecIf($["${CALLERID(num):0:1}" != "+"]?Set(CALLERID(num)=+${CALLERID(num)}))
exten => _9X.,n,Dial(SIP/cliroutes/+${EXTEN:1},,tTo)
exten => _9X.,n,Hangup()

Using PJSIP instead

Newer VICIdial installs on Asterisk 18+ can use PJSIP carriers. The equivalent configuration is below; change the Dial line to PJSIP/+${EXTEN:1}@cliroutes. Our Asterisk PJSIP integration guide covers this in more detail.

[cliroutes]
type=endpoint
context=trunkinbound
disallow=all
allow=ulaw,alaw
dtmf_mode=rfc4733
aors=cliroutes
outbound_auth=cliroutes-auth
from_domain=sip.example-carrier.net
send_pai=yes
trust_id_outbound=yes
rtp_symmetric=yes
force_rport=yes

[cliroutes]
type=aor
contact=sip:sip.example-carrier.net:5060
qualify_frequency=60

[cliroutes-auth]
type=auth
auth_type=userpass
username=YOUR_SIP_USERNAME
password=YOUR_SIP_PASSWORD

Verification checks before going live

1. In the Asterisk CLI, run sip show peer cliroutes (or pjsip show endpoint cliroutes) and confirm status is OK with a sensible latency.
2. Place a manual call from an agent screen to your own mobile. Confirm the CLI displays correctly and audio flows both ways.
3. Run sip set debug peer cliroutes and check the INVITE: Request-URI in E.164, From and PAI carrying your approved CLI.
4. Test DTMF on an IVR you control to confirm RFC 2833 events arrive.
5. Check the call appears in your CLIRoutes portal CDRs with the same CLI and duration.
6. Start the campaign at a low dial level, watch ASR, PDD and SIP responses for 30 minutes, then ramp.

Routing inbound DIDs into VICIdial

If you also receive calls on DID numbers, the context=trunkinbound in the account entry sends them into VICIdial's inbound handling. Create the DID under Inbound → Add a New DID, using the number in the format the carrier sends it (usually E.164 without the +, for example 442071234567), and route it to an in-group, a call menu or an extension.

asterisk -rx "sip set debug peer cliroutes"
# place a test call to your DID, then look for:
# INVITE sip:[email protected]:5060 SIP/2.0
# The user part (442071234567) is what VICIdial must match.

If the carrier sends a + and VICIdial does not match it, either create the DID with the + or strip it in a custom dialplan entry before the call reaches trunkinbound.

Caller ID strategy in VICIdial

VICIdial lets you set caller ID at several levels, and the most specific one wins. Plan this deliberately so agents always present an approved number.

Every number used in any of these places must be approved in your portal. Calls presenting numbers that are not approved are rejected with 403, which is the most common cause of "some calls fail" reports after a new list is loaded with its own CID override.

Clusters and failover

In a VICIdial cluster, add the carrier on every dialer server (the Server IP field is per carrier entry) and whitelist each server's public IP. For resilience, configure a second endpoint in the portal and a second carrier entry pointing at it, then use a dialplan with Dial() to the primary and a fallback to the secondary only on CHANUNAVAIL or CONGESTION, never on busy or no-answer.

exten => _9X.,n,Dial(SIP/cliroutes/+${EXTEN:1},,tTo)
exten => _9X.,n,GotoIf($["${DIALSTATUS}" = "CHANUNAVAIL"]?alt)
exten => _9X.,n,GotoIf($["${DIALSTATUS}" = "CONGESTION"]?alt:end)
exten => _9X.,n(alt),Dial(SIP/cliroutes-b/+${EXTEN:1},,tTo)
exten => _9X.,n(end),Hangup()

Securing the dialer

Dialer servers are a common target for toll fraud because a compromised server can place expensive international calls quickly. Protect yours before going live:

• Allow SIP (5060/5061) only from your carrier's signalling IPs and your own phones or WebRTC gateway; block it from everywhere else.
• Use strong, unique passwords for every phone and agent account, and disable unused phone extensions.
• Run fail2ban against Asterisk security logs to block repeated registration attempts.
• In the CLIRoutes portal, enable only the destinations you call and set a daily spend alert on the wallet.
• Keep VICIdial, Asterisk and the operating system patched.

IP authentication to the carrier combined with destination restrictions limits the damage even if an agent credential leaks, because calls can only leave from your servers and only to the countries you have enabled.

Common problems

For a full list of response codes and what they mean on dialer traffic, see SIP Response Codes for Dialer Operators. For capacity planning, see SIP Channels & CPS Sizing.