VICIdial is a feature-rich open-source call center solution, widely used for managing inbound, outbound, and blended campaigns. One of the essential tasks for call center managers, supervisors, and administrators is monitoring which agents are currently logged in.
The logged_in_agents API provides real-time data on active agents, helping businesses track agent availability, improve workforce management, and optimize campaign performance.
Why Use the logged_in_agents API?
✅ Monitor live agent activity to ensure optimal workforce efficiency
✅ Track which agents are currently logged in and available
✅ Improve call routing by identifying active agents
✅ Integrate real-time agent status into third-party dashboards
✅ Enhance reporting and workforce planning
In this guide, we will cover:
🔹 What the logged_in_agents API does
🔹 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 logged_in_agents API efficiently
Let’s dive in! 🚀
Understanding the logged_in_agents API Function
The logged_in_agents API retrieves a list of all currently logged-in agents along with key details, including:
✔ Agent User ID
✔ Full Name
✔ Current Session Status (On Call, Waiting, Paused, etc.)
✔ Assigned Campaign
✔ Agent’s IP Address
✔ Extension (Phone Login ID)
Common Use Cases for logged_in_agents API
🔹 Supervisors can monitor active agents in real-time
🔹 Call routing systems can use it to allocate calls efficiently
🔹 HR and management teams can track agent login trends
🔹 CRMs and dashboards can display real-time agent availability
Step 1: Prerequisites for Using the API
Before using the logged_in_agents API, ensure you have the following:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions
✅ Valid VICIdial server 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 logged_in_agentsto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to retrieve real-time logged-in agent details 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 logged_in_agents API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (logged_in_agents) |
logged_in_agents |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | LiveMonitoring |
Step 3: Sending the API Request
Method 1: Fetching Logged-In Agents via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API response should display all currently logged-in agents.
Method 2: Fetching Logged-In Agents via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return a real-time list of logged-in agents in the terminal.
Method 3: Fetching Logged-In Agents via Postman
1️⃣ Open Postman
2️⃣ Set the request type to GET
3️⃣ Enter the API URL
4️⃣ Click Send
5️⃣ View the API response in the output panel
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response listing all logged-in agents:
Breaking Down the Response
| Value | Meaning |
|---|---|
agent001 |
Agent’s User ID |
John Doe |
Full Name |
ONCALL |
Current Status (ONCALL, WAITING, PAUSED, etc.) |
Outbound Sales |
Assigned Campaign |
192.168.1.50 |
Agent’s IP Address |
8001 |
Phone Extension Used |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial will return an error message instead of agent data.
Common Errors & Fixes
| 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 FUNCTION SPECIFIED |
Missing function parameter | Ensure function=logged_in_agents is included |
ERROR: NO AGENTS CURRENTLY LOGGED IN |
No active agents found | Check if agents are logged in and available |
Step 6: Best Practices for Using the logged_in_agents API
✅ Use this API to monitor agent activity in real-time
✅ Integrate the API response with CRM dashboards for better reporting
✅ Log API calls to track agent login trends over time
✅ Automate API calls to refresh agent lists at set intervals
✅ Limit API access to authorized users only to prevent unauthorized monitoring
Conclusion
The logged_in_agents API function is an essential tool for tracking real-time agent activity in VICIdial. Whether you’re managing agent workloads, integrating real-time dashboards, or optimizing workforce planning, this API provides quick and accurate logged-in agent retrieval.
📌 Key Takeaways
✅ The logged_in_agents API retrieves all currently logged-in agents
✅ Requires an API-enabled user with appropriate permissions
✅ API requests can be made via browser, cURL, or Postman
✅ Common errors are permission and input-related and can be fixed in Admin settings
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
