Setup guide · Carrier entry

Connect a SIP trunk to Vicidial

Vicidial adds trunks as carriers. One carrier entry holds the SIP peer, an optional registration, a global variable and a dialplan. Campaigns then use a dial prefix to send calls through it.

Get Rates Talk to NOC

Before you start

What you need

Vicidial / ViciBox with admin access to Admin › Carriers
The public IP of each dialer server (we whitelist them all)
Your agreed calls-per-second (CPS) and channel limits
Your SIPTrunkHub account details: SIP server, auth method, tech prefix if any

IP auth or register auth?

IP authentication

Recommended

Recommended for dialers. Whitelist every dialer server IP with us. Leave the registration string empty.

Register (digest) authentication

Fill in the registration string. Use only for single-server installs without a static IP.

Step by step

Configure Vicidial

sip.example-host.net and 203.0.113.10 are documentation placeholders. Replace them, and the username, password and tech prefix, with the values from your account.

01
Add a carrier
Admin › Carriers › Add New Carrier. Set Carrier ID to SIPTRUNKHUB, protocol SIP, and select the server IP. Leave Registration String blank for IP auth.
Registration String (register auth only)
```
register => YOUR_SIP_USERNAME:[email protected]:5060
```

Account entry

This becomes the SIP peer. For register auth add username, fromuser and secret.

Account Entry

[siptrunkhub]
disallow=all
allow=ulaw
allow=g729
type=friend
host=sip.example-host.net
dtmfmode=rfc2833
context=trunkinbound
canreinvite=no
insecure=port,invite
qualify=yes
nat=force_rport,comedia

03
Globals string
A variable the dialplan uses.
Globals String
```
SIPTRUNKHUB = SIP/siptrunkhub
```
04
Dialplan entry
Calls dialled with prefix 9 go out through SIPTrunkHub with the 9 stripped. Add your tech prefix in front of ${EXTEN:1} if your account has one.
Dialplan Entry
```
exten => _9X.,1,AGI(agi://127.0.0.1:4577/call_log)
exten => _9X.,n,Dial(${SIPTRUNKHUB}/${EXTEN:1},,tTo)
exten => _9X.,n,Hangup()
```
05
Point the campaign at the carrier
Campaigns › your campaign › Dial Prefix: 9. Phone numbers in your lists should include the country code (for example 447700900123). Set Campaign CID to a valid number you own.
06
Pace the dialer
Keep Auto Dial Level and the number of agents within your CPS and channel limits. Bursts above the agreed CPS are rejected with 503, which hurts your ASR and drop rate.

Media

Codec order

G.711 u-law first for best AMD (answering machine detection) accuracy. G.729 lowers bandwidth but AMD gets less reliable.
Keep disallow=all at the top of the account entry.
Recordings are stored in your codec of choice by Asterisk; G.711 recordings transcode cleanly.

NAT notes

Most ViciBox servers sit on public IPs. If behind NAT, set externip and localnet in sip-vicidial.conf (or sip.conf).
nat=force_rport,comedia in the account entry handles symmetric RTP.
Open RTP 10000–20000 inbound from our media IPs.

Verify

Test the trunk

Check the peer from the Asterisk CLI, then dial a test number from an agent phone using manual dial.

Asterisk CLI

asterisk -rx "sip show peer siptrunkhub"
asterisk -rx "sip show registry"
asterisk -rx "sip set debug peer siptrunkhub"

Troubleshooting

Common SIP errors

What each response means and what to check first on Vicidial. If you still need help, send the Call-ID and timestamp to the NOC.

Common SIP error codes and fixes for Vicidial
Code	Meaning	Likely cause	Fix on Vicidial
401	Unauthorized	We challenged the INVITE or REGISTER and the credentials were wrong or missing. With IP auth it usually means the call arrived from an IP we have not whitelisted.	Check the username, password and auth realm. For IP auth, confirm the public IP your PBX actually sends from matches the one on your account.
403	Forbidden	Authenticated, but not allowed: wrong or missing tech prefix, zero prepaid balance, destination blocked on your account, or an invalid caller ID.	Calls from a second dialer server we have not whitelisted. Send us every server IP in your cluster.
404	Not Found	The dialled number is not in a format we can route: missing country code, an extra 00 or +, or a local trunk prefix left in.	List numbers are missing the country code, or the dial prefix is not being stripped.
408	Request Timeout	No response came back. Usually a firewall, wrong port or transport, a DNS failure, or SIP ALG on the router eating packets.	Confirm UDP/TCP 5060 is open outbound and to 203.0.113.10. Disable SIP ALG. Test with an OPTIONS ping.
480	Temporarily Unavailable	The far end could not be reached: handset off, out of coverage, or the route for that prefix is temporarily down.	Retry later or route to another trunk. If it hits one prefix repeatedly, send examples to the NOC.
486	Busy Here	The called party is busy, or you reached the concurrent-channel limit on your account.	Treat as a normal busy. If every call returns 486, check your active channel count against your limit.
503	Service Unavailable	Capacity limit hit (calls per second or channels), or every route for that destination failed.	You are above your CPS. Lower the auto dial level or ask sales for a higher CPS limit.

Seeing one-way audio instead of an error? Read One-Way Audio on VoIP Calls.

FAQ

Vicidial questions

Does this work on a multi-server cluster?

Yes. Create the carrier with Server IP set to each dialer, or 0.0.0.0 for all, and whitelist every server IP with us.

Can I use different caller IDs per campaign?

Yes. Campaign CID, or the CID group feature, sets it per campaign. The number must be valid and one you are allowed to use.

Is predictive dialing allowed?

Yes, within the law of the country you call and our acceptable use policy. Robocalls and spam are not allowed.

Other setup guides

All 12 guides

Popular destinations

Stuck on a step?

The NOC answers 24/7. Send your platform, a SIP trace and the Call-ID of a failed attempt.

Ready to connect Vicidial?

Prepaid from $200. No setup fee, no contract. Get rates and your account details from sales.