For call centers managing high volumes of inbound calls, tracking the real-time status of inbound groups is crucial to ensure smooth call flow, optimize agent allocation, and prevent long wait times for customers. VICIdial, a leading open-source call center solution, provides the in_group_status API, which enables administrators to fetch live status information for inbound groups dynamically.
Instead of manually checking inbound call queues and agent availability through the VICIdial admin panel, this API allows businesses to monitor inbound group performance, integrate real-time analytics with external dashboards, and automate workload distribution.
Why Use the in_group_status API?
✅ Retrieve real-time status of inbound call groups
✅ Monitor waiting calls, active agents, and queue length dynamically
✅ Ensure balanced call distribution among available agents
✅ Improve customer service by tracking inbound call performance
✅ Integrate inbound call data into external reporting and CRM systems
In this tutorial, we will cover:
🔹 How the in_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 in_group_status API efficiently
Let’s get started! 🚀
Understanding the in_group_status API Function
The in_group_status API allows administrators to retrieve live statistics for a specific inbound group, helping them monitor queue status, track agent activity, and optimize call distribution.
What Information Does the in_group_status API Provide?
✔ Inbound Group ID – The unique identifier for the inbound group
✔ Total Calls in Queue – The number of customers currently waiting for an agent
✔ Longest Wait Time – The duration the longest waiting caller has been in the queue
✔ Total Agents Assigned – The number of agents assigned to the inbound group
✔ Agents on Calls – The number of agents currently engaged in a call
✔ Agents Waiting for Calls – Available agents ready to take the next call
✔ Drop Percentage – The percentage of calls abandoned before being answered
✔ Call Volume Statistics – Total inbound calls handled within a given period
Common Use Cases for in_group_status API
🔹 Supervisors monitoring real-time inbound call activity
🔹 Ensuring enough agents are available to handle customer inquiries
🔹 Preventing long wait times by adjusting agent availability dynamically
🔹 Integrating inbound queue data into external reporting dashboards
🔹 Automating workforce management based on inbound call trends
Step 1: Prerequisites for Using the API
Before using the in_group_status API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid inbound 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 in_group_statusto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to retrieve inbound group status 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 in_group_status API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (in_group_status) |
in_group_status |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | InboundMonitor |
group_id |
The inbound group to retrieve status for | CUSTOMER_SUPPORT |
Step 3: Sending the API Request
Method 1: Checking Inbound 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 the inbound group.
Method 2: Checking Inbound 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 inbound call queue statistics for the specified group.
Method 3: Checking Inbound 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 queue status for the inbound group
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response listing the real-time status of the inbound group:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
CUSTOMER_SUPPORT |
The inbound group being monitored |
Total Calls in Queue: 10 |
Number of calls currently waiting in the queue |
Longest Wait: 02:35 |
The longest a caller has been waiting |
Agents Available: 5 |
Number of agents ready to take calls |
Agents in Call: 3 |
Number of agents currently handling calls |
Drop Percentage: 2.5% |
Percentage of calls that 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: GROUP ID NOT FOUND |
The specified inbound group does not exist | Ensure group_id is correct |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=in_group_status is included |
Step 6: Best Practices for Using the in_group_status API
✅ Use this API to monitor inbound call queue activity in real-time
✅ Ensure enough agents are assigned to active inbound groups
✅ Integrate queue data into workforce management dashboards
✅ Restrict API access to authorized users
✅ Optimize call routing based on real-time inbound traffic
Conclusion
The in_group_status API function is an essential tool for monitoring inbound call queue activity dynamically in VICIdial. Whether you’re tracking queue performance, optimizing agent allocation, or integrating live call data with external tools, this API provides quick and accurate insights into inbound call handling.
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
