Listing logged-in agents with logged_in_agents

The logged_in_agents function is part of the Non-agent API and gives you one thing: a snapshot of every Agent currently logged in to the dialer. One HTTP request returns a row per agent with their Status (lead status), campaign, and session details. It is the call you reach for when you want a live roster on your own dashboard instead of staring at the VICIdial real-time screen. For the wider picture, start with the VICIdial API overview.

When you'd use it

Reach for this when an external tool needs to know who is on the floor right now: a wallboard, a workforce dashboard, or an automation that pages a supervisor when a campaign runs short of agents. Because it returns the live Session ID for each agent, you can also feed those values straight into Agent API calls to act on a specific agent's screen. It is read-only and cheap, so polling it every few seconds is fine.

How the call works

sequenceDiagram
  participant App
  participant API as non_agent_api.php
  participant V as VICIdial DB
  App->>API: logged_in_agents (source, user, pass)
  API->>V: check user_level and view reports
  API->>V: read live agent table
  V-->>API: rows of logged-in agents
  API-->>App: plain text, one line per agent

You POST or GET to non_agent_api.php. The dialer authenticates the API user, confirms it has permission, reads the live agent records, and prints the result as plain text. There is no JSON envelope unless you ask for it with the stage field.

Parameters

• source - required, a short description of what made the call (max 20 characters).
• campaigns - optional, a pipe-delimited list like TESTCAMP|INBOUND to filter to specific campaigns. Default is all campaigns.
• user_groups - optional, a pipe-delimited list like ADMIN|AGENTS to filter by user group. Default is all groups.
• show_sub_status - optional, YES or NO. YES adds the sub-status and pause_code columns but requires a log lookup, so it is slower. Default NO.
• stage - settings field for the output format: csv, tab, json, or pipe. Pipe is the default.
• header - settings field, YES to print a header row, NO to omit it. Default is no header.

An example call

http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=logged_in_agents&stage=csv&header=YES

A success response does not print the word SUCCESS. It just prints the rows. With a header and csv staging you get something like this:

user,campaign_id,session_id,status,lead_id,callerid,calls_today,full_name,user_group,user_level,pause_code,sub_status
6666,TESTCAMP,8600051,INCALL,1079409,M2260919190001079409,1,Admin,ADMIN,9,LOGIN,DEAD
4545,TESTCAMP,8600052,PAUSED,0,,0,4545,MIKESGROUP,8,LOGIN,

The default pipe format prints the same columns separated by | characters. The sub_status field can be DEAD, DISPO, 3-WAY, PARK, RING, PREVIEW, DIAL, or empty. If nobody is on the floor you get ERROR: logged_in_agents NO LOGGED IN AGENTS, which is a normal empty-set response, not a failure.

Permissions gotcha

The API user needs user_level set to 7 or higher and the view reports flag enabled. Miss either and you get ERROR: logged_in_agents USER DOES NOT HAVE PERMISSION TO GET AGENT INFO. Build a dedicated reporting user for this rather than reusing an agent login. If you want to act on the agents you just listed, the matching read on disposition counts lives in our sibling on the agent stats export API.

Every VICIfast box ships with the Non-Agent API enabled and a real Branded subdomain over HTTPS, so calls like this work the moment your server is provisioned. See our pricing to get a server you can point your dashboard at.