VICIdial connection troubleshooting: calls not reaching your bots

VICIdial did not accept the API user, or your web server answered HTTP 401 or 403. A 403 does not always mean a wrong password: a web server or firewall rule that blocks the master server address gives the same answer. The table in What does each Test connection message mean? explains each message.

“API authentication failed” means VICIdial answered with an error that is not a plain login failure. The usual reason is an API user without API access.

Open the VICIdial connection on Integrations and read API user and API password. Use the show-password icon to look for a typo or a trailing space.

Ask your VICIdial admin to confirm that the API user exists, that the password matches, and that it has the settings in Connect VICIdial: API Access and Agent API Access set to 1, and Modify Leads set to 1 (not 5, which is read-only). The VoiceOI team confirms the exact permissions during onboarding.

Ask your admin whether a web server or firewall rule limits who may use the API, and whether the master server address the team gave you is allowed.

Correct the user or the password in the connection on Integrations, press Save, then press Test connection again. If your login cannot edit the connection, ask the VoiceOI team how to hand over the new password safely. Do not send it in an ordinary message.

Have your VICIdial admin fix the permissions, or allow the master server address on the web server.

If the Server URL is wrong, see the wrong-address entry.

“Connection timeout. Verify server is online and URL is correct.” means nothing answered within about 5 seconds. A common reason is a firewall on your side that drops traffic from the master server, because its address is not allowed on your VICIdial web server. Other reasons are a wrong address or port in the Server URL, and a VICIdial web server that is down or too busy to answer.

“Connection failed” is the general message for any other network error that has no detail. Examples are a server that refuses the connection because nothing listens on that port, and a firewall that rejects the traffic instead of dropping it.

Read the Server URL on Integrations. It must start with http:// or https:// and use the address and port your VICIdial web pages open on, for example http://192.0.2.10.

Open the Server URL in a browser from a network that your VICIdial web server accepts, such as your office. This only shows that the address and port are right, not that VoiceOI’s master server is allowed in.

Ask your VICIdial admin whether the web server’s access log or the firewall log shows requests from the master server address when you press Test connection, and whether the firewall or the web server allows that address.

Allow the master server address and the bot server addresses the VoiceOI team gave you to reach your VICIdial web server. If you do not have the addresses, contact the team. If your server uses the firewall that comes with ViciBox, add the addresses to its white list (in VICIdial, Admin then IP Lists, usually the list ViciWhite) and check that the firewall has loaded them.

Correct the Server URL if it is wrong, press Save, and test again.

If the web server is down or overloaded, fix that first. A pass starts with “Connection successful”.

“Server not found” means the host name does not resolve. Look for a typo.

“API endpoint not found” means the server answered 404. The address is reachable, but VICIdial’s API is not where VoiceOI looked. VoiceOI adds the API file name to the address you enter, so enter the address of the VICIdial server, for example http://192.0.2.10, not a page inside it.

A redirect message means the address forwards somewhere else, for example from http to https. “The server returned HTTP” and a number means your web server answered with that error. A certificate message means the certificate is expired, self-signed or issued for another name. A private-address message means the address is on a private range that VoiceOI’s servers cannot reach. The redirect, certificate and private-address messages appear only if stricter address checks are switched on for your account.

Open the Server URL in a browser. You should reach your VICIdial web page. Compare it with the address in the browser bar when you open your VICIdial admin.

For a certificate message, open the address with https:// in a browser and read the warning it shows.

Enter the address of the server only: the scheme, the host and the port if the web server uses one. Press Save, then Test connection.

For a redirect, enter the address it forwards to.

For a certificate message, install a valid certificate on the VICIdial web server. For a private address message, use the public address of the server. If it has none, ask the VoiceOI team what to use.

A pass means the web server answered and VICIdial’s reply held no login or API error. The master server runs the test. During calls it is the bot servers that talk to your VICIdial, and they have their own addresses. So a pass says nothing about them.

When the test passes and writes still fail, the bot server addresses may not be allowed on your VICIdial web server (only the master server is). The API user may have Modify Leads set to 5, which is read-only and makes status updates fail. It may be limited in other ways: a pass followed by “(Note: API User lacks ‘check_phone_number’ permission, but creds are valid)” means VICIdial would not run that check for it. Or the VICIdial card on Integrations says Switched off, and the bots do not use the connection at all.

A separate reason is a status that is not in your campaign’s status list: VICIdial does not set it, and the lead keeps its old status.

Open Integrations and read the VICIdial card. It must say Live.

Pick a finished call in Call Logs and compare its outcome, such as NI, with the lead’s status in VICIdial. An outcome in Call Logs with the old status still on the lead means the update did not arrive, or VICIdial did not set the status.

Ask your VICIdial admin whether the web server’s access log shows requests from the bot server addresses, not only the master server address, and what permissions the API user has.

Allow every bot server address the team gave you, as well as the master server address, on your VICIdial web server. If your server uses the firewall that comes with ViciBox, add them to its white list (Admin then IP Lists) and check that the firewall has loaded them.

Ask your VICIdial admin to set Modify Leads to 1 (not 5) and to give the API user the other settings and permissions in Connect VICIdial and the ones the team confirmed.

If the card says Switched off, use the switch on the VICIdial card on Integrations to switch the connection on. Without it the bots do not use the connection.

If only some statuses are missing, check the campaign’s status list. See the status codes VoiceOI writes.

This applies when your script uses the lead’s name. The script reads the lead’s name and other details from your VICIdial while the call runs. When that lookup fails, the lead name falls back to “Valued Customer”.

The usual reason is that the API user cannot see the lead: VICIdial answers that no matches were found, although the lead exists. Other reasons: the bot server addresses are not allowed on your VICIdial web server, your web server answers too slowly, or the lead has no name stored. After many lookups fail in a row, the bot server stops asking for a while and then tries again, so calls get the fallback during that pause even after you fix the cause.

Open the lead in VICIdial and check that a name is stored.

Ask your VICIdial admin which leads the API user is allowed to see, and whether the web server’s access log shows requests from the bot server addresses.

Ask your VICIdial admin to give the API user access to your leads and to allow every bot server address on the web server, as in the pass-but-nothing-written entry.

Place a test call after the change. The bot server tries the lookup again after its pause, which can take a while. Ask the team to confirm that lookups work again.

The bot server accepts calls only from the addresses on your account’s allow-list. When a call arrives from another address, it answers 403 Forbidden - IP Not Whitelisted.

On many bot servers a call from an address that is not on the list gets no answer at all, because the bot server’s firewall drops it before the bot sees it. Your dialer then shows a timeout instead of a 403: also read the no-answer entry.

The bot server compares the address it sees the call arrive from, which can differ from the one you expect: a dialer behind NAT shows its public address, a cluster places calls from several servers, and a call routed through another server arrives from that server.

A plain 403 Forbidden with no more text means the address is not on the list and the call carried no VICIdial call code, so the bot server treats it as internet noise. It happens when the call does not come through the bot route the team set up on your dialer.

403 Forbidden - No IP Whitelist Configured means the account has no allow-list on the bot server: see the paused-account entry. A 403 on a transfer is a different problem: see audio, transfer and disposition troubleshooting.

Ask your VICIdial admin for the SIP response to the bot trunk (see the SIP refusal codes) and for the address the call left from. Compare it with the list you sent the team.

Ask support to check the bot server for the time of the failed call. For a recent call the team can usually see the address the bot server saw and the reason it gave.

Send the team the public address of every VICIdial server that places calls to the bots, including servers you plan to add. See A VICIdial cluster: add every server.

Allow a few minutes after the team confirms. To make the bot servers pick up the new address sooner, press Force bot sync on Integrations, then place a test call.

For a plain 403 Forbidden, ask the team to check the bot route on your dialer. Do not edit it yourself.

VoiceOI bills from a prepaid balance. When it runs out, the Dashboard first shows a note that starts “Your balance has run out. Calls stop on” followed by a date. If no credit is added, VoiceOI pauses the account and clears its allow-list. With no allow-list the bot server refuses every call with 403 Forbidden - No IP Whitelist Configured. Log-in is then refused with “Organization is frozen”, and a dashboard that was already open fails with “Couldn’t load your dashboard. Account access restricted. Please contact support.” The same happens when the VoiceOI team pauses an account for another reason: ask the team why.

Log in again at the log-in page. “Organization is frozen” means the account is paused. You see it only when your email and password are right. If you can log in, the Dashboard note and Remaining Balance in the sidebar show the warnings that come before a pause.

Contact the team by the contact page, WhatsApp or email: see How do you reach VoiceOI support?. The dashboard has no top-up page, so the team applies your payment to the balance: see How do you add balance or pay an invoice?.

When the balance is above zero again, the account is restored and the allow-list returns exactly as it was before the pause. You do not need to send the addresses again. Allow a few minutes, then place a test call.

Your dialer dials the bot with a script ID. If the bot server has no script or campaign with that ID, it refuses the call with 480 Temporarily Unavailable. It does this on purpose: running a different script would put the wrong words in front of your lead.

The usual reasons are an ID that was mistyped, an ID of a script that was deleted and rebuilt (a rebuilt script has a new ID), and a script created or changed a moment ago that has not reached the bot servers yet (changes reach the bots on their next sync, which can take longer than a minute).

In Scripts, open the row menu of the script and choose Copy Script ID. Compare it with the ID in the Dial line of the bot route on your dialer. See Always dial the script ID.

Press Force bot sync on Integrations. Wait for a result that says every bot is fully in sync, such as “Your bot is fully in sync” or “All 3 bots are fully in sync”, then place another call. A result such as “2 of 3 bots fully in sync” means a bot did not confirm.

If the script is new or changed, press Force bot sync and test again.

If the IDs differ, ask the VoiceOI team to correct the bot route on your dialer with you. Do not guess an ID.

Ask the VoiceOI team to confirm that the script is linked to a campaign. The team does the campaign setup.

The call carried no script ID, lead, bot slot or campaign. The usual reason is a bot route that does not add the lead and campaign headers or does not name the script.

Ask your VICIdial admin to read the Dial line of the bot route and compare it with Copy Script ID in Scripts. See Always dial the script ID. A 404 leaves no entry in Call Logs.

Do not edit the route yourself. Ask the VoiceOI team to check it with you.

503 Service Unavailable means the bot server’s audio engine was not connected when the call arrived. This happens for a few seconds after a restart or an update of the bot server, and it clears by itself.

500 Server Internal Error means something failed while the bot server set up the call. The bot server records the error.

Write down the time of the first and the last refused call. A short burst that ends by itself fits a restart or an update: ask the team whether one ran then, and place a test call a minute later.

A refused call is a call the person already answered, so that person hears no bot. A short burst that stops by itself needs no change to your VoiceOI setup. VoiceOI does not know how your VICIdial logs those leads, so look at them in VICIdial’s own reports and in your own abandoned-call tracking. What happens to the lead and the redial is decided by VICIdial and your campaign settings, not by VoiceOI.

If a 503 continues for more than a few minutes, or a 500 repeats, contact the team. Both need attention on the bot server.

Many dialers report a refusal from the bot server as CONGESTION on the bot trunk, whatever the SIP code. Depending on the Asterisk version and SIP module you may see another failed-call result instead, such as CHANUNAVAIL or BUSY. The reason is in the SIP response and in the bot server’s own records.

The table in What do the SIP refusal codes mean? lists the possible reasons, from an address that is not on the allow-list (403) to a setup error (500).

CONGESTION on your carrier trunk is a different case. That is the leg to the person you call, and a carrier problem or a limit on your side causes it. This entry is about the leg to the bot.

Ask your VICIdial admin to find the dial to the bot trunk in the dialer’s Asterisk log and read the SIP response next to it. Use the table linked above to find the entry for that code.

If the log shows no response at all, see the no-answer entry.

Ask support to check the bot server for the time of the call.

Follow the entry for the code you found: SIP 403, paused account, SIP 404, SIP 480 or SIP 503 and 500.

The call left your dialer, but no answer came back from the bot server. There are four usual reasons.

Your dialer’s address is not on the allow-list and the bot server’s firewall drops the call, so you see a timeout instead of a 403.

The bot route on your dialer points to the wrong address or port. The bot server’s SIP port can change when the team reinstalls or moves a bot server, and the peer on your dialer must then change to match.

A firewall on your side, or on the way, blocks UDP or TCP to the bot server addresses the team gave you. SIP uses both.

The bot server is stopped or restarting.

Ask your VICIdial admin whether the dialer’s Asterisk log shows the call going to the bot trunk with no response, and whether Asterisk reports the bot peer as reachable.

Ask the team to confirm the bot server address and SIP port in your bot route, and whether the bot server was recently reinstalled, moved or updated.

Make sure the address your dialer calls from is on the allow-list. See SIP 403.

Allow UDP and TCP between your dialer and the bot server addresses the team gave you. The team confirms the ports during onboarding. If your dialer uses the ViciBox firewall, add the bot server addresses to its white list too. If the team gives you a new address or port, it updates the peer on your dialer with you, and you allow the new address on your firewall.

The bot server accepted the call but could not start a script, so it hung up. That happens when the script behind the call has no steps, or when the call names a campaign that has no script with steps. Dial the script ID so the call runs the script you chose: see Always dial the script ID.

A rule on Immediate Hangups can also end a call right after the first thing the person says. See Bots hang up on real people.

If the person hears nothing and then the call ends, the cause may be audio. See audio, transfer and disposition troubleshooting.

Open the call in Call Logs. A call the bot answered and then dropped has an entry with no Bot Said, AI Opening, AI Voice or AI Bot lines. If there is no entry at all, the bot server refused the call: use the SIP refusal codes.

Open the script in Scripts and check that it has steps.

Press Show System Nodes on the call to read the technical flow. If a rule ended the call, the ending event names it.

Finish and save the script, press Force bot sync, and place a test call. If the script is complete, ask the team to check that the campaign has it linked.

If a rule ended the call, follow the remote agent entry linked above.

Every call fails from a certain time: the balance ran out and the account was paused. See the paused-account entry.

Only calls from one VICIdial server fail: that server is not on the allow-list. See the cluster entry.

Failures come in a short burst and stop: the bot server restarted or was updated. See SIP 503.

Failures appear when many calls run at once: answered calls find no free bot. See the abandoned-calls entry.

Failures start after you edited or rebuilt a script: the dial string names an ID the bot server does not have. See SIP 480.

Failures start after a change on your dialer: see the server-change entry.

Write down the time of the first failed call, then three failed and three good calls, with the campaign and the dialer server for each. Compare the two lists.

Follow the entry that matches. If none does, send both lists to support.

A VICIdial cluster can place calls from every one of its Asterisk servers. The bot server checks the address of the server that placed each call. If only some of your servers are on the allow-list, calls from the others are refused or get no answer, and you see a mix of working and failing calls.

The usual trigger is a server added to the cluster, or load balancing that starts to send calls through a server that never carried bot calls before.

In your VICIdial admin, list the servers that place calls. Ask the team to read back the addresses on your allow-list, and compare the two lists.

In the Asterisk log of each server, look at the response to the bot trunk. A refusal or no response on one server and a success on another confirms the cause.

Send the team the public address of every server that places calls, including those you plan to add. Tell the team which server runs your VICIdial web pages, so it can match the calls to your connection on Integrations.

Allow a few minutes after the team confirms. To make the bot servers pick up the new addresses sooner, press Force bot sync on Integrations, then test a call from each server.

Live on the card means only that the connection is saved and switched on. VoiceOI does not start calls on VICIdial: VICIdial dials your leads and hands each answered call to a bot remote agent, so nothing dials when VICIdial has no reason to dial or no bot line is free.

In VICIdial, check that the campaign is Active; that its lists are active and hold leads the campaign’s dial statuses allow; that the hopper has leads; that Local Call Time allows dialing now; that the dial method and dial level are set; and that the bots’ remote agent entries are Active, belong to that campaign and have lines. These are VICIdial settings.

On the VoiceOI side, the bots’ entries must have been started with START, and the account must not be paused.

Open the live agent view in VICIdial’s admin for the campaign and look for the bot lines. If they are missing or not ready, VICIdial has nothing to hand calls to. See START problems.

If VICIdial is dialing and answered calls are connecting but never reach a bot, use the SIP refusal codes.

Correct the VICIdial settings above. Your VICIdial admin owns them.

If the bot lines are missing, ask the VoiceOI team to check the remote agent entries.

Saved changes reach the bot servers on their next sync, which can take longer than a minute. A bot server that was offline, restarting or running an older bot version can miss a change.

The call runs the script whose ID is in the bot route on your dialer. If you built a copy or a new script, the route still points at the old one until the team changes it.

Press Force bot sync on Integrations and read the result. A result that says every bot is fully in sync, such as “Your bot is fully in sync” or “All 3 bots are fully in sync”, means every bot that reports back has your current scripts. A line such as “problem with scripts”, “no report yet (offline, or restarting)”, “No bot answered” or “Sync not delivered” means a bot did not confirm. A bot that “runs an older bot version, which syncs but does not report back” cannot confirm: ask the team.

In Scripts, choose Copy Script ID on the script you edited and compare it with the ID in your bot route. See Always dial the script ID.

If a bot did not report, wait a few minutes and press Force bot sync again. If it still does not report, or the message says the bot runs an older version, the bot server needs the VoiceOI team.

If the IDs differ, ask the team to point the bot route at the script you want.

In VICIdial, an answered call that finds no free agent is dropped, also called abandoned. With bots, each bot line takes one call at a time, and a line that is busy, stuck or not Active is not free. If VICIdial dials faster than there are free bot lines, answered calls find no bot.

Other reasons: only some bots are Active, some lines are stuck on a call, or a burst of refused calls (a bot server restart, a paused account) left answered people with no bot.

The dial level, the drop settings and any limit on abandoned calls are VICIdial settings. VoiceOI does not set, measure or limit your abandoned-call rate.

During the busy period, compare the campaign’s dial level with the number of Active bot lines in the live agent view in VICIdial’s admin.

Compare the times of the drops with refused calls. See the SIP refusal codes.

Ask your VICIdial admin to lower the dial level until the lines keep up.

To take more calls at once, ask the VoiceOI team about more bots. Each bot is one line.

For stuck lines, see stuck INCALL lines.

Three things link your dialer to the bots, and a change on your side can break each one. The address your dialer calls from must be on the allow-list. The bot route and the SIP peer on your dialer must match the bot server address and SIP port. And the Server URL, the API user and the allowed addresses must still match your VICIdial web server.

So a new dialer server or a new public address is refused with a 403 or gets no answer. A new web address or a changed API password makes Test connection fail, and on some accounts an invalid certificate does too. A change to the bot route or the SIP peer can make calls fail before they reach the bot server, so they leave no entry in Call Logs.

Ask your VICIdial admin what changed and when: server, address, firewall, certificate or API user.

Press Test connection on Integrations. A failure points at the web address, the API user or the allowed addresses. See What does each Test connection message mean?.

Place a test call and read the response in the SIP refusal codes. No entry in Call Logs and no SIP response from the bot server point at the route, the peer or a firewall.

Tell the VoiceOI team about the change as early as you can, ideally before it. The team updates the allow-list and the connection, and checks the bot route and the SIP peer on your dialer with you.

Do not rebuild the bot route or the peer from memory. The team writes them for your install.