Skip to content

Prepare your VICIdial

This takes about ten minutes. The connection wizard shows a shorter version of this list on its last step.

  1. Use an https address. Outside a test setup Vodial refuses a plain http address, because the API password is sent in every request.
  2. Create an API user with all of these:
    • user level 8 or higher
    • Vdc Agent API Access set to 1
    • API Allowed Functions set to ALL_FUNCTIONS
    • Modify Leads set so leads can be added (on VICIdial 2.14 the value 4 worked in a lab test)
    • a name of up to 20 characters
  3. Create the list and the campaign the leads go to. Both must exist before the first lead is sent. Write down the list number. It is digits only, up to 14.
  4. Create a read-only database user, only if you want Vodial to import a list’s leads directly. Give it SELECT on the asterisk database and nothing else. See the ports below.
  5. Open the firewall to the addresses the wizard shows under “Let these addresses through”. If it says to ask Vodial, ask your Vodial contact.
  6. Self-signed certificate? If your web server uses a self-signed or private-CA certificate (ViciBox does until you install a real one), tick “My VICIdial uses a self-signed certificate” in the wizard, then confirm the fingerprint it shows. See below.
  7. Private network only? Vodial cannot reach a 10.x, 172.16 to 172.31.x, 192.168.x, loopback or link-local address. Give VICIdial a public address, or set up a VPN with your Vodial contact.

If the user lacks a permission, VICIdial answers USER DOES NOT HAVE API ACCESS or USER DOES NOT HAVE PERMISSION TO .... The Test button explains both in plain words.

  1. Check that the statuses Vodial will set already exist in VICIdial. See the status map.
  2. If calls should land in a VICIdial in-group, create the in-group. Decide the SIP address that reaches it.
  3. Make sure the people you hand over have US numbers. Only +1 numbers are sent to VICIdial, and Canadian numbers are never dialled, so do not upload them.
  4. Set your campaign’s calling hours. See Calling hours in VICIdial.
  5. Give your Vodial admin: the address, the API user, its password, the list number and, if you use one, the in-group and the database user.

Vodial calls the Non-Agent API at /vicidial/non_agent_api.php with four functions and nothing else.

Function Used for
version The Test button. It only asks for the version.
lead_search Finds a lead by phone number.
add_lead Adds a new lead to your list.
update_lead Changes a lead’s comments or status.

It never deletes a lead and never reads a list.

The calls come from Vodial’s servers, not from your users’ browsers.

  • The web address must be public. In production, private, loopback and link-local addresses (10.x, 172.16 to 172.31.x, 192.168.x) are refused. A numeric address like that is refused when you save it. A name that points to one is refused when Vodial tries to reach it. A VICIdial that has only a private address needs a VPN or a public address.
  • No redirects. If your server sends http to https with a redirect, the call fails. Enter the final https address.
  • Use https. The address must start with https://. The password travels in the body of each request, not in the address.
  • Self-signed certificate. Tick “My VICIdial uses a self-signed certificate” in the wizard (setting api_tls: verify is the default, pinned is the option). The wizard shows the certificate’s SHA-256 fingerprint. Compare it with the one on your server (openssl x509 -noout -fingerprint -sha256 -in <your certificate file>), then confirm. Vodial then accepts only that certificate. If you replace the certificate, Vodial stops connecting (“the server’s certificate changed”) until you press Test and confirm the new fingerprint. A connection saved with the old self_signed value must be confirmed again the same way.
  • Allow our addresses. Your firewall must let through the addresses the wizard lists under “Let these addresses through”. If the wizard says to ask Vodial, ask your Vodial contact.
  • Database port. The optional read-only database connection accepts port 3306 or any port from 1024 to 65535. Other ports below 1024 are refused. Its encryption setting is required by default (encrypted, certificate not checked) or insecure (no encryption, your choice).
  • Be quick. A call that takes longer than 15 seconds is treated as failed and retried.

Vodial checks calling hours only for calls Vodial dials itself. Calls that VICIdial dials and then hands to Vodial’s agent do not pass that check. Only your VICIdial campaign settings limit them, so set them carefully.

  • Local Call Time. Set it to 8am to 9pm. VICIdial works out each person’s local time from the lead’s area code or ZIP code.
  • State Call Times. Some states allow fewer hours than the federal window. Add a State Call Times record for each strict state and include those records in the campaign’s call time.
  • Each lead needs a two-letter state. State Call Times do nothing for a lead with no state. A ZIP code helps VICIdial find the right time zone.
  • US numbers only. Canada is not supported yet. Canadian +1 numbers have no time zone in Vodial and are never dialled, so do not upload them.

The phone call is a separate path from the API. Vodial’s phone servers call the address you enter on the campaign step. Allow them on your SIP side the same way you would allow a carrier.

The call is shown to VICIdial with the person’s own number as the caller ID. Vodial waits up to 30 seconds for your side to answer.