How to feed the dial hopper with hopper_bulk_insert

The Hopper is the short queue of leads VICIdial pulls from when it dials. Normally a background process keeps it filled, but sometimes you want to force a specific set of leads to the front, say a fresh callback list or numbers from an external system. The hopper_bulk_insert function drops a batch of lead ids straight into that queue.

It is part of the Non-Agent API, so you call it over HTTP with no agent logged in. Each lead lands in the hopper of whatever campaign owns its list, so you do not pass a campaign id at all. The VICIdial API and AGI overview maps out where this call sits.

What you send

Two required fields:

• lead_ids — all numbers and commas, each 1 to 9 digits, separated by commas, up to 1000 lead ids in one call.
• source — a short label for what made the call, max 20 characters.

Two optional settings tune the behavior:

• hopper_priority — a number from 99 down to -99. Higher means the lead gets dialed sooner. Default is 0.
• hopper_local_call_time_check — Y or N (default N). Set Y to validate the lead's local call time and state call time before it goes in, so you never queue a number that is outside its permitted hours.

A Lead is a single contact record. Each one carries a Called status that decides whether it is eligible to dial again, which is also why Lead recycling can pull older leads back into reach before you insert them.

Permission requirement

The API user needs modify_campaigns set to 1 and user_level of 8 or higher. Without both you get a permission error and nothing moves.

Example call

Insert two leads at high priority with a local-time check:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=hopper_bulk_insert&lead_ids=193715,1677922&hopper_priority=97&hopper_local_call_time_check=Y

From lead to ringing phone

flowchart TD
  Leads[lead_ids batch] --> Insert[hopper_bulk_insert]
  Insert --> TimeCheck{local time check}
  TimeCheck -- outside hours --> Skip[Lead skipped]
  TimeCheck -- ok --> Hopper[Dial hopper]
  Hopper --> Priority[Sorted by priority]
  Priority --> Dialer[Dialer picks lead]
  Dialer --> Agent[Connected to agent]

Reading the response

You get one notice per lead plus a final summary. A lead that lands shows NOTICE: hopper_bulk_insert LEAD ADDED TO HOPPER. Leads that bounce tell you why, for example NOTICE: hopper_bulk_insert NOT ADDED TO HOPPER, OUTSIDE OF LOCAL TIME, or LEAD IS ALREADY IN THE HOPPER, or LEAD NOT FOUND. The run ends with SUCCESS: hopper_bulk_insert LEADS HAVE BEEN INSERTED INTO THE HOPPER if any made it, or ERROR: hopper_bulk_insert NO LEADS HAVE BEEN INSERTED INTO THE HOPPER if none did. A flat ERROR: hopper_bulk_insert USER DOES NOT HAVE PERMISSION TO ADD LEADS TO THE HOPPER means the permission gate above is not met.

Once leads are in, check on them with hopper_list to confirm order and priority before the dialer reaches them. On a VICIfast box this all works the moment your server is up, in under 40 seconds. See our plans.