Seeing an agent's inbound groups with agent_ingroup_info

When an agent is logged in and taking blended traffic, you sometimes need to see which inbound queues they are actually subscribed to and what their outbound auto-dial setting is. The agent_ingroup_info function on the VICIdial Non-agent API shows exactly that. It reports the in-group and outbound auto-dial info for one logged-in Agent, served from non_agent_api.php. An Ingroup is the inbound queue a call is routed into. For the wider picture see the VICIdial API and AGI overview.

When you'd use it

This shines on a supervisor tool that lets you confirm — or change — what a live rep is set to receive. Say a rep complains they are getting no inbound calls; this call tells you whether their in-groups are even selected. The function has two faces: an information-only view, and a view that surfaces the controls to change which queues the agent is taking, which is handy for a mid-shift queue reshuffle on a Blended dialing floor.

How the call works

sequenceDiagram
  participant App
  participant API as non_agent_api.php
  participant V as VICIdial
  App->>API: agent_ingroup_info (agent_user, stage)
  API->>V: look up live agent session
  V-->>API: in-groups and auto-dial info
  API-->>App: info or change view
  App->>App: render queue settings

You name the agent and pick a stage, the endpoint reads that agent's live session, and it returns either a plain information display or a set of change controls. If the agent id does not exist you get an INVALID USER ID error; if your api user lacks rights you get a PERMISSION error.

Parameters

Required fields:

• agent_user — the agent's login, 2 to 20 characters
• source — a short description of what made the call, maximum 20 characters

Settings field:

• stage — info (show information only), change (show options to change), or text (standard non-HTML output)

An example call

http://server/vicidial/non_agent_api.php?source=test&function=agent_ingroup_info&stage=change&user=6666&pass=1234&agent_user=1000

With stage set to change, the response includes the controls to adjust which in-groups the agent receives. With stage set to info you get a read-only display of the same data. Use the text stage when you are parsing the result in code rather than embedding it in a browser, because the default HTML-flavored output is built for a screen, not a script.

Permissions and a gotcha

The api user must have user_level 7 or higher, or the call returns a PERMISSION error — see VICIdial API user-level permissions for the full ladder. The biggest trip-up is that this reads a live, logged-in session — it is not a static lookup of what an agent is allowed to take. If the rep is not logged in there is nothing to show. For the broader "what campaigns and groups is this user permitted to use" question that works regardless of login state, that is a different function. And remember the output is built for a UI by default, so set stage to text before you try to parse it. To watch the live Status (lead status) of that same rep, pair this with the agent_status function.

Knowing which queues a live agent is wired into removes a lot of guesswork from a busy floor. If you would rather not run the VICIdial box behind these endpoints yourself, our managed servers spin up in under 40 seconds — see our pricing — or read the queue-level companion, reading an inbound group's live state.