Dialing

Why VICIdial is not dialing: reading the hopper, in order

Twelve checks, in the order the hopper applies them, that explain why a VICIdial campaign has leads but places no calls. With the queries to run.

By Published Updated 5 min read
A focused call center agent wearing a headset checks the time on his wristwatch in a modern office setting.

To the point

VICIdial dials only from the hopper, a small table of the next leads per campaign. Every minute the hopper script writes why it is or is not filling, and it applies its rules in a fixed order, so the first check that fails is your answer.

  • Read the row in vicidial_campaign_stats_debug where server_ip is HOPPER first. Often you are done.
  • An expired list is as invisible as an inactive one.
  • Calling hours are judged at 104 GMT offsets, in quarter-hour steps.
  • A wrong server clock shifts every calling window by the difference.

Start with what the hopper says

The hopper is vicidial_hopper. So "not dialing" means either the hopper is empty or nobody is taking from it. AST_VDhopper.pl writes one row per campaign at the end of every pass:

SELECT entry_time, debug_output
FROM vicidial_campaign_stats_debug
WHERE campaign_id = 'YOURCAMP' AND server_ip = 'HOPPER';

On our test campaign it read campaign lists count ACTIVE: 0 | TOTAL: 0, then leads to call count: 0, then ERROR CANNOT ADD ANY LEADS TO HOPPER. That is the whole diagnosis.

The twelve checks, in order

  1. Is the dialer alive? SELECT last_update FROM server_updater; should be seconds old, and the debug entry_time under a minute. If not, stop.
  2. Is the campaign active? Read active, dial_method, hopper_level, local_call_time, dial_statuses and lead_filter_id.
  3. Is there a usable list? The hopper sees lists attached to the campaign with active = 'Y' and expiration_date >= today.
  4. Do the lists hold leads? Count per list with FORCE INDEX(list_id), the index the hopper forces.
  5. Are leads in a dialed status? dial_statuses is a space-separated string ending in -. A list worked for a month can be full and hold almost nothing dialable.
  6. Called since the last reset? The base condition is called_since_last_reset = 'N' with a dialed status in an active list. A lead called once stays out until the list is reset.
  7. Inside calling hours where the lead is? The check that catches the most people. See below.
  8. Does a lead filter remove them? If lead_filter_id is not NONE, its SQL is added. Count with and without it.
  9. Attempt caps. call_count_limit and drop_lockout_time act in the count. The daily and 24-hour limits act when a lead is inserted, so the count can look healthy while leads are refused.
  10. DNC. Internal and campaign matches are dropped at insert time too. If the dialable figure is high and the hopper stays thin, measure the overlap.
  11. Hopper against demand. "Ready" means READY, RHOLD or RQUEUE. The hopper refills toward hopper_level once a minute.
  12. Agents. A full hopper with nobody logged in dials nothing. If agents are present and lines do not go out, see lines per agent.

Set it up, step by step

On our test server, campaign SUNQ4 and list 4001.

In VICIdial's admin

VICIdial list page with Campaign, Active and Expiration Date highlighted
Check 3: the list screen, where an expired list hides
  1. Campaign: the list must be attached to the campaign you are checking.
  2. Active: must be Y.
  3. Expiration Date: a date before today removes the list, even when Active is Y.
VICIdial campaign page with Lead Filter, Drop Lockout Time, Call Count Limit and Minimum Hopper Level highlighted
Checks 8, 9 and 11: the campaign settings that thin the hopper
  1. Lead Filter: anything but NONE adds its SQL to the count.
  2. Drop Lockout Time: keeps leads that just dropped out of the hopper for a while.
  3. Call Count Limit: adds called_count < limit.
  4. Minimum Hopper Level: the size the hopper refills toward.

In the Trustane console

Trustane Why isn't it dialing page with the Fix to Lists and Fix to Hopper level links highlighted
Campaigns, then Why isn't it dialing?
  1. Fix → Lists: jumps to the lists when the active-lists check fails.
  2. Fix → Hopper level: jumps to the hopper setting when the hopper cannot keep up with demand. The page also shows the hopper's own last run for the campaign.

Calling hours, holidays and the clock

The hopper asks what time it is for a lead at each GMT offset, from +13.00 down to -12.75 in steps of 0.25. That is 104 values. A lead is in the window when start <= HHMM < stop: start inclusive, stop not. A weekday of 0/0 falls back to the default hours, and 2400 means closed.

  • Holidays narrow the day. They raise the start and lower the stop. A 2400/2400 holiday closes the day.

A box has three clocks: the OS zone, servers.local_gmt (which the hopper uses), and PHP's date.timezone. On the stock ViciBox 12 image we tested, the OS ran UTC while local_gmt said -5.00, so the hopper's local time was five hours out. On 9am to 9pm, the campaign would start and stop five hours wrong.

What we measured

One small server, read-only queries, single runs.

Bar chart of leads at each step: 959,579 in lists, 701,665 in a dial status, 662,847 not yet called, 631,940 after DNC
Each step is a place where having leads stops being true

The scans took 1.35 s, 1.38 s and 3.4 s, cheap enough for a live box. About 5% of eligible leads were on DNC. We could not confirm our final count against dialable_leads on a live list. Two independent scans agreeing is not the same thing.

Questions people ask

The list has 40,000 NEW leads. Why is the hopper empty?

Check 6: leads called since the last reset stay out until the list is reset, whatever their status.

Why is the hopper full but nothing dials?

Check 12: nobody is logged in, or lines are capped.

Next steps

Read the HOPPER row, work down the checks and stop at the first failure. For calling hours, compare the four clocks before touching the call time. On hosted servers the console runs these checks for every campaign: order a server, migrate one or see VICIdial hosting.

VICIdial is a trademark of its owner. Trustane is an independent hosting provider.

Sources

  1. Trustane hopper diagnostic report, read from AST_VDhopper.pl
  2. Trustane hopper diagnostic specification
  3. VICIdial Non-Agent API documentation, version function
  4. Cover photo by Yan Krukau on Pexels

Trustane

Managed VICIdial hosting

Run it on cores of your own

Managed VICIdial, billed by the hour against a balance you top up.

Or try one server free for 7 days, no top-up.