Connect VICIdial® to VoiceOI voice bots

There are nine steps, in this order. Each step shows who does it. What you need first is in What do I need before I start?.

1. 1

   Get your VICIdial ready

   You

   Make sure the campaign the bots will work exists, has a list with test leads, and runs the way you want.

   Check the campaign’s status list. VICIdial sets only statuses that are on it. See Which statuses does VoiceOI write back to VICIdial?.

2. 2

   Create the API user

   You

   In your VICIdial admin, create a user for VoiceOI with the settings in What does the VICIdial API user need?. Give the user name and password to the team the way the team asks during onboarding. Do not put them in a support message or a screenshot.

3. 3

   Open the network path in both directions

   Both

   The team gives you VoiceOI’s addresses, and you allow them on your VICIdial and firewall.

   You send the team the address of every VICIdial server that places calls, as single addresses, and the team adds them to your account’s allow-list. See Which addresses must be allowed, and where?.

4. 4

   Connect the server on Integrations

   VoiceOI team

   The team enters your Server URL, API user and API password on Integrations and presses Test connection. A message that starts “Connection successful” means the web server answered and VICIdial’s reply held no login or API error.

   If you would rather enter the password yourself, the Connect Vicidial panel on Integrations has the fields.

5. 5

   Set up the in-group, the campaign and a test script

   Both

   The team sets up the in-group that receives transfers, allows it in the campaign settings so transfers are accepted, and creates the test campaign in VoiceOI.

   You decide who the closers are and keep them signed in and ready. You build or review the script in Scripts and try it in the Simulator, which tests the conversation only, not the VICIdial connection.

6. 6

   Create the bot users, phones and remote agents

   VoiceOI team

   The team creates a VICIdial user and a phone for each bot, then a remote agent entry that starts Inactive, and normally adds the matching rows to Remote Agents. Tell the team your free User ID range first.

7. 7

   Add the SIP peer and the bot route on your dialer

   Both

   The team writes the SIP peer and the dialplan route and adds them to your Asterisk together with your VICIdial administrator. See Which SIP settings, transport and codec does the bot use? and What is the dialplan hook?.

8. 8

   Start the bots

   Both

   On Remote Agents, check that each bot is listed with the full External Extension (for example 888881001) and the right Lines. Press START. In your VICIdial admin, the remote agent entries should now show Active.

9. 9

   Test end to end

   Both

   Place a test call to a phone you control. Check the audio in both directions, the status in VICIdial and a transfer to your in-group. See How do I check that it works?.

• A working VICIdial with the campaign the bots will work, a list of test leads, a status list with the codes you want, and an administrator who can create an API user, change the firewall and apply a dialplan change with the VoiceOI team.
• The address of every VICIdial server that places calls: the web server, and each Asterisk server in a cluster.
• A range of VICIdial User IDs that no person uses, for the bot users, the number of bots you want (one call each at a time), and the closers and in-group for transfers.

VoiceOI bots appear in VICIdial as remote agents. A remote agent is a VICIdial entry with no agent screen: VICIdial forwards the calls it routes to that entry to a number you set, the External Extension. For VoiceOI, that number leads to a route on your VICIdial’s Asterisk server, which dials a VoiceOI bot server over SIP.

On the bot server, the bot plays its script or holds an AI conversation. When the call ends, VoiceOI writes the outcome back through VICIdial’s own API: the lead’s status, the call log entry and, on a transfer, notes for the closer. SIP is the current call path, and this page covers it only. VoiceOI also has an older FastAGI path. If you are not sure which one your account uses, ask the VoiceOI team.

1. VICIdial dials a lead from your campaign. When the lead answers, VICIdial passes the call to a ready line of a bot’s remote agent entry, as it would to a person who is ready.
2. Your Asterisk dials the bot server over SIP and adds headers that say which lead, campaign and bot line the call is for.
3. The bot server checks that the call comes from an address on your allow-list, finds the script named in the dial string, and answers.
4. The bot talks, and can hand a qualified call to your closers with notes in the lead’s Comments. When the call ends, VoiceOI writes the status to the lead and to VICIdial’s call log.

The VoiceOI team does the onboarding. You do the VICIdial side that only your administrators can do, and the decisions that are yours. The team’s provisioning tool is not part of customer logins, so you never run it.

VoiceOI uses VICIdial’s own API to read the lead, write the status and the notes, and start and stop remote agents. It authenticates each request with the API user you create, on the standard VICIdial API pages of your web server: /vicidial/non_agent_api.php and /agc/api.php. Create a separate user for this. Do not reuse a person’s login.

These three settings are required. The VoiceOI team confirms the exact settings and permissions with you during onboarding. Do not remove any other permission from this user until the team has confirmed them.

What the connection on Integrations contains

Press Test connection after any change. A message that starts “Connection successful” means the web server answered and VICIdial’s reply held no login or API error. It does not prove that the user may change leads or remote agents. If the message goes on to say the API user lacks the check_phone_number permission, VICIdial would not run that check for this user, so its API permissions are limited: tell the team before you go further. For a failed test, see connection troubleshooting.

Traffic must be allowed in both directions, and each side keeps its own list. The team gives you VoiceOI’s addresses. You send the team yours. Only your VICIdial administrator can change your VICIdial and firewall settings. If you are not sure who will do it, say so during onboarding.

VoiceOI has two kinds of server, and both need access. The master server handles Test connection, START, STOP and the notes sent to a closer dialer. The bot servers take the calls and write statuses and notes during and after them.

A VICIdial cluster: add every server

A VICIdial cluster sends calls from every one of its Asterisk servers. A call from a server that is not on the list is refused or gets no answer, even when the other servers of the cluster work. Your dialer may report SIP 403, or see nothing at all when the bot server’s firewall drops the call first. Send single addresses, not ranges: the address the call arrives from, as seen from outside your network (a server behind NAT uses its public address). When you add a server later, send its address to the team before it starts sending bot calls.

Web server (API):   192.0.2.10
Asterisk server 1:  198.51.100.11
Asterisk server 2:  198.51.100.12

The path between your Asterisk and the bot server is plain SIP. The bot server answers SIP OPTIONS pings, so a peer that checks whether the bot is reachable (qualify) works.

[voiceoi_bot]
type=peer
host=203.0.113.10
port=<SIP port from the team>
allowtransfer=yes
transfer_context=default
dtmfmode=rfc2833
context=default
qualify=yes
disallow=all
allow=ulaw
insecure=port,invite
nat=force_rport,comedia
directmedia=no

The dialplan hook is the route on your VICIdial’s Asterisk that handles the External Extension of the bots. It adds SIP headers that tell VoiceOI which lead, campaign and bot line the call is for, and it dials the bot server through the SIP peer. The VoiceOI team writes the route with your VICIdial administrator.

; In the route for the External Extension of the bots (prefix 88888 here).
; Lines before these load the lead variables and keep the lead ID for transfers. Keep them.
same => n,SIPAddHeader(X-VICIdial-Lead-Id: ${lead_id})
same => n,SIPAddHeader(X-VICIdial-Caller-Id: ${phone_number})
same => n,SIPAddHeader(X-VICIdial-User-Id: ${EXTEN:5})
same => n,SIPAddHeader(X-VICIdial-Campaign-Id: ${campaign_id})
same => n,SIPAddHeader(X-VICIdial-CallerID-Code: ${CALLERID(name)})
same => n,Dial(SIP/<script-id>@voiceoi_bot)
same => n,Hangup()

Always dial the script ID

The text before the @ in the Dial line is the ID of the script the call runs. Find it in VoiceOI under Scripts: open the row menu and choose Copy Script ID. Always name the script. If the dial string names none, VoiceOI tries to work out the script from the campaign and can pick the wrong one.

If the ID names a script the bot server does not have, for example one that has not synced yet or a mistyped ID, the bot server refuses the call with SIP 480. Press Force bot sync on Integrations, compare the ID with Copy Script ID, and check the Campaign Assignment column on Scripts. If it says Unassigned, ask the team to link the script to a campaign. Then place the call again.

What VoiceOI answers when it refuses a call

Causes and fixes in full: connection troubleshooting.

Each bot is a line on a remote agent entry in VICIdial. The entry has a User ID, a campaign, an External Extension, a number of lines and a status of Active or Inactive. Each line takes one call at a time, so the lines of all your bot entries add up to the calls the bots can hold at once.

An entry’s extra lines use the numbers above its User ID, so the ranges of different entries must not overlap. Leave room between the starting User IDs. If you run more than one VICIdial, give each system its own User ID ranges so VoiceOI can tell which one a bot belongs to, and set each row’s Dialer Connection: see two agents that share lines and two VICIdial servers and the wrong one is used.

The Remote Agents page (titled Remote Agent Command Center) lists the rows VoiceOI keeps for your bots. Single Agent, Bulk Fleet and Import CSV link users that already exist in VICIdial to rows on this page. Their buttons read “Provision Bot” and “Link existing Fleet”, but they create nothing in VICIdial: the VoiceOI team creates the users, phones and remote agent entries, so you normally do not need these dialogs. If you edit a row, a change to its name or user group is also sent to the VICIdial user. Ask the team what to enter in the password field before you use Single Agent. Rows linked this way have a default of 1 line, and START, STOP and Update Dialer Parameters send the row’s Lines to VICIdial, so on an entry with more lines they cut it to the row’s number: set Lines to match the VICIdial entry first.

START, STOP and Live Status

• START asks VICIdial to set the bot’s remote agent entry to Active, with the row’s Lines. New entries start Inactive, so no bot takes calls until START.
• STOP sets the entry to Inactive. VICIdial may need a short time after that before it stops sending calls to the entry.
• START, STOP and Update Dialer Parameters apply to every line of that agent.
• Live Status is the last START or STOP that VICIdial accepted. It is not VICIdial’s live state. To see the real state, open the live agent view in VICIdial’s admin.
• The message “Bulk Operation Initiated” appears for every START or STOP, even for one agent. It means the request was queued, not that VICIdial accepted it.
• Purge Agent removes only the row on this page. The entry in VICIdial stays as it was.
• START sends the row’s External Extension, but VICIdial’s own API notes list no extension field for that call. Do not rely on START to correct a wrong extension in VICIdial. The team or your VICIdial administrator changes it there.

VoiceOI writes one status per call to the lead in VICIdial and to VICIdial’s call log. VICIdial sets a status only if it is on the campaign’s status list. For any other, the lead keeps the status it had. VoiceOI cannot add statuses to your VICIdial, so check the list before you go live.

How a call is written back

1. The call ends: the person hangs up, or the script finishes.
2. VoiceOI works out the status: the one a script step sets, or else the hang-up rules in the table below.
3. VoiceOI updates the lead in VICIdial, then, a few seconds later and with one retry, the call’s entry in VICIdial’s call log.
4. VoiceOI saves its own record, which you see in Call Logs.

A transferred call is different: VoiceOI writes the notes, then hands the call over, and the status goes with the transfer, without the two final writes. Call Logs shows the status VoiceOI chose, even when VICIdial did not accept it, so compare the code with the campaign’s status list.

A script step can also set a status from its Vicidial Disposition list, which includes A, B, CALLBK, CBHOLD, DAIR, DC, DEC, DNC, N, NI, NP, NQ, SALE and XFER. The list also shows OVERAGE: do not pick it, because VICIdial cannot store a status of 7 characters. Check the campaign’s status list for every code you use and for every code in the table above, including HANGUP, HU, DROP and NQ. Ask your VICIdial administrator to add any that are missing, or change the step to use a status the campaign has.

See also audio, transfer and disposition troubleshooting and the glossary.

When a call qualifies, the script can hand the live call to your closers. The bot does not stay on the line to introduce the caller. The transfer is a hand-off with notes.

Two transfer methods work on the VICIdial path. The other modes in the Transfer Mode list of the Script Builder belong to the Asterisk engine of the built-in dialer, so do not use them here.

• ViciDial Native API Transfer (Instant Release): VoiceOI asks VICIdial, through its API, to move the call to the destination you enter.
• SIP Blind Transfer (REFER): VoiceOI sends a SIP REFER to your Asterisk, which then sends the call to the destination. Your Asterisk must accept the transfer, and the destination must exist on your dialer. If the REFER is refused, the bot still ends its side of the call and the caller is dropped, so test it first. See SIP settings.

The destination is a number or extension that your dialer routes to the in-group your closers use. In the Transfer Call step the field is labelled Destination Phone Number for the default hand-off (the label changes with the transfer mode), and the team sets it with you. If a transfer step has no destination, no transfer happens and the script ends, so the caller is hung up. Check that every transfer step has one.

A transfer reaches your closers only if the in-group is allowed in the campaign and at least one closer is signed in and ready in it. Otherwise the call arrives at the in-group and nobody answers.

Notes for the closer

Before the transfer, VoiceOI writes the caller’s answers into the lead’s Comments in VICIdial, so the closer sees them when the call arrives. Comments holds 255 characters, and longer text is cut. VoiceOI sends the notes as the whole new value, so text that was there may be replaced: do not keep your own text in that field on leads the bots call. In the Script Builder this is the Notes for the closer section of the Transfer Call step. In the AI Voice Agent editor, it is Comments on the Handoff tab. If the write fails, the closer may see the previous value.

If your closers work on a separate VICIdial, the switch Also send the notes to a closer dialer on the Transfer step sends the same notes to the lead with the caller’s phone number on that system. It uses the Closer dialer connection on Integrations, which the team sets up. Only one closer dialer connection receives the notes. If the closer dialer has no lead with that phone number, VoiceOI adds one in the list you set under List for new leads on that connection (list 999 if you set none). It sends only for phone numbers with at least 10 digits. For transfer modes and closer routing rules, see Transfers and closers.

1. 1

   Check the connection

   You

   On Integrations, find the Vicidial connection. Its card should read Live. Press Test connection and look for “Connection successful”. Remember that a pass only means VICIdial’s reply held no login or API error.

2. 2

   Start one bot and look at VICIdial

   You

   On Remote Agents, press START on one bot. In your VICIdial admin, open Remote Agents and check that the same User ID shows Active, with the right External Extension and number of lines. Then open the live agent view in VICIdial’s admin: the bot’s lines should appear for your campaign.

3. 3

   Place a test call

   You

   Put a lead with a phone number you control in a test list and let the campaign dial it. Check that the list and campaign are active and that the lead may dial now under your campaign’s Local Call Time. If nothing dials, see Integrations shows VICIdial as Live, but nothing dials. Make sure no person is signed in to that campaign, because VICIdial chooses which ready agent gets the call. Answer, and listen for the bot to start its script.

4. 4

   Find the call in Call Logs

   You

   Open Call Logs (the page is titled Interaction Logs) and search for your number. Only Admin and SubManager logins can open it. Expand the row: Bot Said and User Spoke lines show the conversation, and Show System Nodes shows the full log. If there is no row at all, the call never got past the bot server’s checks, or never arrived: see What VoiceOI answers when it refuses a call.

5. 5

   Check the status in VICIdial

   You

   Open the lead in your VICIdial admin, on the lead search and the lead’s detail page. A few seconds after the call, its status should be the one VoiceOI chose, and the call log entry should show the same.

   If the lead keeps its old status, the code is probably not on the campaign’s status list, or the API user’s Modify Leads is 5. If the call log entry stays at XFER, the route is missing the X-VICIdial-CallerID-Code header.

6. 6

   Test a transfer

   Both

   Run a test lead through the script until it qualifies. Check that the call arrives in your in-group, that a closer who is signed in and ready hears the caller and the caller hears the closer, and that the lead’s Comments show the notes.

After you change a script or a setting, the change reaches your bots on their next sync, which can take longer than a minute. To push it now, press Force bot sync on Integrations.

• The connection test fails, calls are refused, or no row appears in Call Logs: see connection troubleshooting.
• No audio or one-way audio, a transfer fails, the notes are missing, or the status is not written: see audio, transfer and disposition troubleshooting.
• START did nothing, the External Extension is wrong, a line is stuck, calls go to a person, or bots hang up on people: see remote agent and answering machine troubleshooting, and START did nothing in particular.

If the checks do not explain it, contact the VoiceOI team through Contact. Send the time of the call with the time zone, the lead ID, the campaign, the remote agent’s User ID and External Extension, and what the screen showed. Do not send passwords. What to send support has the full list.

• VoiceOI does not do predictive or power dialing for your human agents. VICIdial keeps your lists, hopper and dial method.
• The bot cannot leave a voicemail message. It hangs up on a machine and logs AM.
• Calls are in English only today, and the VICIdial path records no calls in VoiceOI.
• There is no native CRM sync, no outbound webhook, and no public API or SDK. To move results, use the Google Sheets step (one row per call that reaches it), Call Logs, or VICIdial’s own dispositions.
• VoiceOI is built for outbound campaigns. It does not offer an inbound receptionist.