Reading the inbound queue depth with calls_in_queue_count

Knowing how many callers are waiting is useful for more than just the wallboard. External systems — workforce management tools, custom dashboards, and automation scripts — often need that number to make decisions. The calls_in_queue_count function in the Agent API returns a live count of the calls in the Call queue that could be sent to a specific Agent, scoped to what that agent is actually eligible to receive.

Unlike a global queue count that aggregates everything, this function is anchored to a named agent_user. The number it returns reflects only calls that could be routed to that agent based on their ingroup memberships and current status. That makes it directly actionable for per-agent logic rather than just a center-wide metric.

How the function retrieves the count

sequenceDiagram
  participant App as Your App
  participant API as agc/api.php
  participant Session as agent_session
  participant Queue as vicidial_inbound_queues
  App->>API: calls_in_queue_count agent_user value=DISPLAY
  API->>Session: verify agent is logged in
  Session-->>API: agent ingroup list
  API->>Queue: count calls matching agent ingroups
  Queue-->>API: integer count
  API-->>App: SUCCESS calls_in_queue_count - 4

The API authenticates the request, reads which ingroups the agent belongs to from their active Agent session, and counts the calls currently queued for those ingroups. If the agent is not logged in, the call fails with an error rather than returning zero, so your code can distinguish "no calls waiting" from "agent not available".

Parameters and example call

The only function-specific parameter is value, which must be set to DISPLAY. That is the only valid value, so there is nothing to configure beyond pointing the call at the right agent. The standard user, pass, source, and agent_user are required on every Agent API call.

curl "https://your-server/agc/api.php?source=monitor&user=6666&pass=1234&agent_user=1000&function=calls_in_queue_count&value=DISPLAY"

The response is a single line with the integer count after the dash:

SUCCESS: calls_in_queue_count - 0

To use the number, split the line on the dash and read the trailing value. Because the count reflects only the agent's own ingroups, two agents on the same campaign can return different numbers at the same instant if they are members of different ingroups — that is expected behaviour, not a bug.

Practical ways to use the count

The most direct use is a lightweight wallboard: poll this endpoint every few seconds for each logged-in agent and display the result. Because the count is per-agent rather than per-center, you can show each supervisor only the queue depth relevant to their team. Keep the polling interval sensible — a few seconds is plenty, and hammering the endpoint adds load without giving you a meaningfully fresher number.

Another use is gating agent behaviour. If you build a custom break-request flow, you can call this function first and refuse the break while the agent's queue is above a threshold, nudging staffing to follow demand. The same signal can drive an overflow decision: when one agent's queue is deep, route a notification to a backup team so they can log in before callers start abandoning.

A more automated use is pairing it with the pause_code function. If an agent is paused and the queue count crosses a threshold, your system can set a specific Pause code to flag the pause as happening during a high-volume period, which changes how a supervisor reads the workforce report later.

This function is part of the Non-agent API and Agent API ecosystem that VICIdial exposes for external integrations. For guidance on parsing the response lines these functions return, see how to read VICIdial API responses. The full function reference is in the VICIdial API and AGI overview. If you need a VICIdial server with all APIs ready on day one, every VICIfast plan provisions in under 40 seconds.