Call centers require real-time visibility into their agent performance, availability, and workload distribution to maintain efficiency and optimize call routing. VICIdial, a leading open-source call center solution, provides an API function called user_group_status API, which allows administrators to fetch live status information for user groups dynamically.
With the user_group_status API, supervisors and developers can monitor agent availability, track login activity, and analyze group-wide performance in real time. Instead of manually checking the VICIdial admin panel, this API enables automated monitoring, CRM integration, and live workforce analytics.
Why Use the user_group_status API?
✅ Retrieve live status of agents in a specific user group
✅ Monitor the number of agents who are active, paused, or waiting for calls
✅ Ensure even workload distribution among teams
✅ Optimize call routing by analyzing real-time agent availability
✅ Automate user group status tracking for CRM and reporting systems
In this tutorial, we’ll cover:
🔹 How the user_group_status 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 user_group_status API efficiently
Let’s get started! 🚀
Understanding the user_group_status API Function
The user_group_status API allows administrators to retrieve real-time statistics for a specific user group, including the number of logged-in agents, their current statuses, and activity levels.
What Information Does the user_group_status API Provide?
✔ User Group ID – The identifier of the user group being queried
✔ Total Logged-in Agents – The number of agents currently logged in
✔ Agents in Calls – The number of agents actively handling calls
✔ Agents Waiting for Calls – Agents available but not on calls
✔ Paused Agents – The number of agents currently paused
✔ Dead Calls – Calls that ended abruptly or were abandoned
✔ Inbound and Outbound Call Counts – Number of active calls by type
Common Use Cases for user_group_status API
🔹 Supervisors monitoring real-time user group performance
🔹 Ensuring adequate agent availability before launching campaigns
🔹 Balancing agent workloads by tracking live status metrics
🔹 CRM integration for real-time workforce analytics
🔹 Automating reporting dashboards for agent group activity
Step 1: Prerequisites for Using the API
Before using the user_group_status API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid user group ID to fetch status data for
✅ 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 user_group_statusto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to fetch live status data for user groups 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 user_group_status API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (user_group_status) |
user_group_status |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | UserGroupMonitor |
user_group |
The user group to retrieve status for | SALES_TEAM |
Step 3: Sending the API Request
Method 1: Checking User Group Status via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should return the live status of agents in the user group.
Method 2: Checking User Group Status 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 agent statuses for the specified user group.
Method 3: Checking User Group Status 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 the real-time agent status in the user group
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response listing the real-time status of agents in the specified user group:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
SALES_TEAM |
The user group being monitored |
Total: 15 |
Total number of agents logged into the group |
In Call: 7 |
Number of agents currently handling calls |
Waiting: 5 |
Number of agents available but not on a call |
Paused: 3 |
Number of agents on break or paused |
Dead Calls: 1 |
Calls that ended abruptly or were abandoned |
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: USER GROUP NOT FOUND |
The specified user group does not exist | Ensure user_group is correct |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=user_group_status is included |
Step 6: Best Practices for Using the user_group_status API
✅ Use this API to monitor agent availability in real-time
✅ Integrate status data with workforce management dashboards
✅ Ensure enough agents are available for inbound/outbound campaigns
✅ Restrict API access to authorized users
✅ Analyze agent activity patterns to optimize staffing levels
Conclusion
The user_group_status API function is an essential tool for monitoring agent group activity and availability dynamically in VICIdial. Whether you’re tracking agent performance, optimizing call routing, or integrating real-time workforce data into CRMs, this API provides quick and accurate insights into user group activity.
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
