In VICIdial, the hopper is a critical component that controls how leads are queued for dialing in a campaign. The hopper_list API provides a way to retrieve and monitor leads currently loaded into the hopper, helping call center administrators track, analyze, and optimize dialing operations.
The hopper ensures that active leads are preloaded into the dialer, minimizing delays and ensuring a smooth and efficient outbound dialing process. Instead of manually checking the VICIdial admin panel, the hopper_list API enables real-time monitoring, external reporting, and seamless integration with CRM systems.
Why Use the hopper_list API?
✅ Retrieve a list of leads currently in the hopper
✅ Monitor lead priority and call order in real time
✅ Ensure campaigns have enough leads loaded for dialing
✅ Identify and troubleshoot leads that are stuck or not being dialed
✅ Integrate hopper data with CRM and analytics tools
In this tutorial, we’ll cover:
🔹 How the hopper_list API works
🔹 How to configure and authenticate API access
🔹 How to construct and send API requests
🔹 Examples using a browser, cURL, and Postman
🔹 How to interpret API responses and troubleshoot errors
🔹 Best practices for using the hopper_list API efficiently
Let’s get started! 🚀
Understanding the hopper_list API Function
The hopper_list API allows administrators and developers to view all leads currently preloaded into the VICIdial hopper for a specific campaign.
What Information Does the hopper_list API Provide?
✔ Lead ID – Unique identifier for the lead
✔ Phone Number – Contact number of the lead
✔ Campaign ID – The campaign the lead is assigned to
✔ Hopper Priority – Determines dialing priority (higher values get dialed first)
✔ Lead Rank – Additional ranking metric for dialing preference
✔ Call Count – The number of times the lead has been dialed
✔ Last Call Time – The most recent attempt to reach the lead
Common Use Cases for hopper_list API
🔹 Supervisors monitoring real-time lead availability
🔹 Ensuring campaigns have enough leads preloaded for dialing
🔹 Identifying leads stuck in the hopper without being dialed
🔹 Analyzing lead prioritization and call history
🔹 Automating reports on hopper lead movement and dialing frequency
Step 1: Prerequisites for Using the API
Before using the hopper_list API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid campaign ID to check the hopper for leads
✅ VICIdial server access credentials
How to Enable API Access in VICIdial
1️⃣ Log in to the VICIdial Admin Panel
2️⃣ Navigate to Admin > Users
3️⃣ Select the user who will access the API
4️⃣ Set API Access to 1 (Enabled)
5️⃣ Set User Level to 8 or higher** (Admin-level access) 6️⃣ Add hopper_listto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to retrieve hopper lead data dynamically using the API.
Step 2: Constructing the API Request
The VICIdial API uses HTTP GET requests, meaning you can access it via a browser, cURL, or API tools like Postman.
Base API URL
🔹 Replace your-vicidial-server with your actual VICIdial instance.
Required Parameters for hopper_list API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (hopper_list) |
hopper_list |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | HopperCheck |
campaign_id |
The campaign to retrieve hopper leads from | OUTBOUND_SALES |
Step 3: Sending the API Request
Method 1: Checking Hopper Leads via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should return a list of leads currently in the hopper.
Method 2: Checking Hopper Leads via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return a list of leads in the campaign hopper.
Method 3: Checking Hopper Leads via Postman
1️⃣ Open Postman
2️⃣ Set the request type to GET
3️⃣ Enter the API URL
4️⃣ Click Send
5️⃣ The response should display a list of leads currently in the hopper
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response listing all leads currently in the hopper:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
10001 |
Lead ID |
18005551234 |
Phone number |
OUTBOUND_SALES |
Campaign ID |
99 |
Hopper priority (higher values get dialed first) |
1 |
Lead rank |
2 |
Call count (number of times the lead has been called) |
2024-02-10 14:35:00 |
Last call attempt timestamp |
Step 5: Handling Errors & Troubleshooting
| Error Message | Cause | Solution |
|---|---|---|
ERROR: USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION |
Insufficient API permissions | Ensure user level is 8+ and API Access is enabled |
ERROR: INVALID USERNAME OR PASSWORD |
Wrong credentials | Verify API username and password |
ERROR: NO LEADS FOUND |
No leads currently in the hopper | Ensure campaign is active and leads are loaded |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=hopper_list is included |
Step 6: Best Practices for Using the hopper_list API
✅ Use this API to monitor hopper lead availability in real-time
✅ Integrate hopper data with CRM dashboards for tracking
✅ Ensure enough leads are preloaded to prevent dialing delays
✅ Restrict API access to authorized users
✅ Analyze lead movement in the hopper for performance optimization
Conclusion
The hopper_list API function is an essential tool for monitoring and managing the VICIdial campaign hopper. Whether you’re tracking leads, optimizing campaign efficiency, or integrating lead data with external tools, this API provides real-time access to crucial dialing information.
Feel free to contact us or simply start a live chat to get connected to one of our team members. Here is our contact information.
Calling from US: +1 954-990-0053
Email: office@callix.ai
