Connect VICIdial to TelecomsXchange

This guide connects VICIdial, the open-source contact-centre suite that runs on Asterisk, to TelecomsXchange: outbound campaign and manual calls to a purchased route, and inbound calls on numbers you bought. For the full list of TelecomsXchange values, see Connect a SIP platform. VICIdial writes the carrier into Asterisk for you; the underlying Asterisk settings are the same as in Connect Asterisk.

Before you start#

• A SIP account with the public IP of each VICIdial server that places calls, for example 203.0.113.10 (extra servers go under Additional Allowed IPs), or a VoIP login and password from Edit Account → Add SIP Digest Auth.
• A purchased route and its tech prefix from My Interconnections, for example 80039#.
• VICIdial admin access with permission to modify carriers, and leads loaded with a country phone code so VICIdial dials full international numbers.
• The examples use the SIP/ channel driver that ViciBox installs. If your build uses PJSIP for carriers, use the endpoint, aor and identify sections from the Asterisk guide in the account entry instead.

How do I send calls to TelecomsXchange?#

1. Go to Admin → Carriers → Add A New Carrier. Set Carrier ID to TCXC, Carrier Name to TelecomsXchange, Protocol to SIP, Server IP to your dialer (or 0.0.0.0 for all servers), and Active to Y. Leave Registration String blank.
2. In Account Entry, define the peer. There is no register line:

[tcxc]
type=peer
host=sip01.telecomsxchange.com
port=5060
transport=udp
disallow=all
allow=g729
allow=ulaw
allow=alaw                 ; TCXC passes codecs through: offer what the route supports
dtmfmode=rfc2833
context=trunkinbound       ; VICIdial's inbound DID context
insecure=port,invite       ; TCXC sends from source ports 5060-5072
nat=force_rport,comedia
canreinvite=no
qualify=no                 ; TCXC answers OPTIONS only within a call
;defaultuser=VOIP_LOGIN    ; digest variant (below)
;secret=VOIP_PASSWORD

3. In Globals String, name the trunk:

TCXC=SIP/tcxc

4. In Dialplan Entry, match the campaign's Dial Prefix (9 here), strip it, and dial the tech prefix in front of the number. VICIdial dials the Dial Prefix, then the lead's phone code, then the phone number, so 9 + 44 + 7700900123 arrives as 9447700900123. Replace 80039# with your route's TECH_PREFIX:

exten => _9X.,1,AGI(agi://127.0.0.1:4577/call_log)
exten => _9X.,n,Dial(${TCXC}/80039#${EXTEN:1},60,tTo)
exten => _9X.,n,Hangup()

If your campaigns dial 011 before non-North-American numbers, add a pattern that strips it too: exten => _9011X.,n,Dial(${TCXC}/80039#${EXTEN:4},60,tTo) with the same AGI and Hangup lines.

5. Open the campaign (Campaigns → Campaign ID → Detail) and set Dial Prefix to 9. Use a different prefix digit, and a second carrier dialplan entry, for each route or routing group such as 444101# you want campaigns to choose between.

Digest variant. If a dialer sends from an IP that isn't on the account, uncomment defaultuser and secret in the account entry and fill in the account's VoIP Login and VoIP Password. Asterisk answers TelecomsXchange's 401 or 407 challenge with them.

How fast can the dialer send?#

TelecomsXchange accepts 10 calls per second per authorised IP; Edit Account shows it as IP CPS Limit (read-only). Predictive campaigns burst well above that when many agents go ready at once, and the excess is rejected.

• Pace each server: cap simultaneous calls with Max VICIDIAL Trunks in Admin → Servers and Max Trunks in the campaign, and raise the Auto Dial Level gradually. Trunk caps limit concurrent calls rather than the rate, so check the attempt rate in Live Calls while a campaign ramps up.
• Agents × Auto Dial Level is roughly the number of lines VICIdial tries to keep ringing; when many agents go ready together, it places those calls in a burst.
• To go beyond 10 calls per second, spread campaigns over several dialer servers, each with its own public IP added under Additional Allowed IPs, or ask support@telecomsxchange.com to raise the limit. See Create your first account.

How do I receive calls from TelecomsXchange?#

Calls on numbers you bought (and on any route you sell) come from 174.136.44.213 over UDP, from source ports 5060 to 5072, with the number in E.164 format such as 14165551234.

1. Allow 174.136.44.213 on the dialer's firewall for UDP 5060, and open the RTP range (by default 10000 to 20000).
2. The account entry above matches that IP (host=sip01.telecomsxchange.com resolves to it) and puts calls in trunkinbound, where VICIdial looks up the dialled number in its DID list.

How do I receive calls on numbers I bought?#

1. On TelecomsXchange, set the number's SIP Endpoint (Primary) in DID Settings to the dialer, for example sip:14165551234@203.0.113.10:5060.
2. In VICIdial, go to Admin → Inbound → Add A New DID. Set DID Extension to the number exactly as it arrives, 14165551234, and choose the DID Route: IN_GROUP to queue it to agents, or EXTEN, VOICEMAIL, PHONE or AGENT.
3. If you use in-groups, assign the in-group to the campaign under Allowed Inbound Groups so agents receive the calls.

How do I test it?#

1. Log in an agent and place a Manual Dial call to a number covered by the route.
2. On the dialer, run asterisk -rvvv and sip set debug peer tcxc (or sngrep port 5060 on the shell). Look for the INVITE to 80039#447700900123 (or 80039%23447700900123) and the reply.
3. In the portal, watch the call in Live Calls and find its SIP code in Logs → CDR (Voice).
4. In VICIdial, the carrier log (Reports, when enabled under System Settings) shows the SIP hangup cause for each attempt.

What if something goes wrong?#

References#

• VICIdial Manager Manual (vicidial.org)
• VICIdial documentation index and ViciBox
• Telnyx: configure a VICIdial carrier
• Asterisk chan_sip / sip.conf reference