Reading an inbound group's live state with in_group_status

When you want the live pulse of an inbound queue - how many callers are holding, how many agents are logged in, how many are busy - the in_group_status function gives it to you in one line. It is a read-only call on the VICIdial Non-agent API, served from non_agent_api.php, that reports the real-time Status (lead status) of one or more inbound groups. An Ingroup is VICIdial's term for an inbound queue calls are routed into. For the bigger map of every endpoint, see the VICIdial API and AGI overview.

When you'd use it

This is the call behind a queue wallboard or a staffing alert. If SALESLINE has callers stacking up in the Call queue while only two agents are logged in, you want to know before your service level slips. Poll it on a short interval and you have a live read on calls waiting versus available staff, without scraping the admin reports screen.

How the call works

sequenceDiagram
  participant App
  participant API as non_agent_api.php
  participant V as VICIdial
  App->>API: in_group_status (in_groups, source)
  API->>V: read live queue counters
  V-->>API: waiting and agent counts
  API-->>App: one line per query
  App->>App: refresh queue board

You pass a pipe-delimited list of group names, the endpoint sums the live counters across those groups, and it returns a single aggregate line. There is no SUCCESS prefix - the data row is the success, a pattern explained in how to read VICIdial API responses. A PERMISSION or INVALID SEARCH PARAMETERS line means something is wrong with the request, not the queue.

Parameters

Required fields:

• source - a short description of what made the call, maximum 20 characters
• in_groups - a pipe-delimited list of inbound groups, e.g. SALESLINE|SUPPORT

Settings fields (optional):

• stage - output format: csv, tab, json or pipe (pipe is the default)
• header - YES to print a header row, otherwise no header

An example call

http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&stage=csv&function=in_group_status&in_groups=SALESLINE|SUPPORT&header=YES

The result is one row of columns: ingroups, total_calls, calls_waiting, agents_logged_in, agents_in_calls, agents_waiting, agents_paused, and agents_in_dispo. So a line such as SALESLINE SUPPORT,31,0,75,54,0,20,1 tells you 31 total calls, none currently waiting, 75 agents logged in, 54 on calls, 20 paused and 1 in [[wrap-up]]. Note the counts are summed across every group you named - they are not broken out per group - so query one group at a time when you need per-queue numbers.

Permissions and a gotcha

The api user needs user_level 7 or higher and the "view reports" permission, otherwise you get a PERMISSION error. The pipe character in in_groups must be URL-encoded as %7C when your client does not encode it for you, or the parameter list breaks apart. And keep in mind the aggregation behavior: if you feed it ten groups expecting ten lines, you will be surprised - you get one summed line. To watch a single rep inside one of these queues, pair this with the agent_status function.

A live queue read costs almost nothing and keeps your staffing decisions grounded in real numbers. If you would rather not maintain the box behind these endpoints, our managed VICIdial servers are ready in under 40 seconds - see our pricing - or read the agent-side companion, seeing an agent's inbound groups.