Reading the dial hopper with hopper_list

Before you trust a dialer to make calls, it helps to see exactly what is queued. The hopper_list function returns the live contents of a campaign's Hopper, the short queue of leads VICIdial is about to dial, one row per lead.

It is a read-only report in the Non-Agent API. Use it to confirm priority and order after you push leads in, or to monitor whether a campaign is running dry. The VICIdial API and AGI overview shows how it fits the rest.

What you send

Two required fields:

• source — a short label for what made the call, max 20 characters.
• campaign_id — 2 to 8 characters, the campaign whose hopper you want to read.

Settings and optional fields:

• stage — the output format: csv, tab, json, or pipe (the default).
• header — YES to include a header row, NO (default) to skip it.
• search_method — set to BLOCK for a faster but blocking SQL query. It can affect database performance, so leave it off unless you need it.

Permission requirement

The API user needs user_level 8 or higher and "view reports" enabled. This is a reporting call, so it reads but never changes the queue.

Example call

Read the hopper for TESTCAMP as CSV:

http://your-server/vicidial/non_agent_api.php?source=test&function=hopper_list&campaign_id=TESTCAMP&user=6666&pass=1234&stage=csv

What comes back

A success response does not print the word SUCCESS. It prints the rows directly, one per queued lead, with columns:

hopper_order,priority,lead_id,list_id,phone_number,phone_code,state,status,count,gmt_offset,rank,alt,hopper_source,vendor_lead_code,source_id,age_days,last_call_time

A sample line:

0,0,796292,107,9999001095,1,NY,PDROP,7,-4.00,0,,S,1001095,A321,2681,1 YEARS

The hopper_order and priority columns tell you dial order. The status column is each Lead record's Called status, and phone_code is the dialing Phone Number Prefix applied to the number. The count column shows how many times that lead has been attempted.

Where the data flows from

flowchart TD
  Campaign[campaign_id] --> Query[hopper_list call]
  Query --> Perm{user_level 8 and view reports}
  Perm -- no --> Deny[Permission error]
  Perm -- yes --> Read[Read hopper table]
  Read --> Format{stage csv json pipe}
  Format --> Output[Rows returned]
  Output --> Caller[Your script]

Common errors

ERROR: hopper_list USER DOES NOT HAVE PERMISSION TO GET CAMPAIGN INFO means the user level or report flag is wrong. ERROR: hopper_list THIS CAMPAIGN DOES NOT EXIST means your campaign_id is off. ERROR: hopper_list THERE ARE NO LEADS IN THE HOPPER FOR THIS CAMPAIGN is not really a failure, it just means the queue is empty and likely needs feeding.

When the hopper is empty, refill it with hopper_bulk_insert. On a VICIfast server the API answers from the moment your box provisions, in under 40 seconds. See our plans.