Reading one agent's live status with agent_status

If you run a wallboard or a custom CRM panel, you eventually want to know exactly what one person is doing right now: are they on a call, paused, or sitting idle? The agent_status function on the VICIdial Non-agent API answers that in a single line. It is a read-only call over non_agent_api.php that returns the live Status (lead status) of one Agent, along with the call they are handling and a more granular sub-status. For the wider picture see the VICIdial API and AGI overview.

When you'd use it

Reach for it when you need the live picture of a single agent rather than a whole queue. A floor-supervisor dashboard polling each rep every few seconds, a CRM screen-pop that wants to confirm the rep is actually INCALL before it fires, or an alert that pages you when someone has been PAUSED too long — all of these are a tight fit. Because it reports one Agent session at a time, it is cheap to call and easy to reason about.

How the call works

sequenceDiagram
  participant App
  participant API as non_agent_api.php
  participant V as VICIdial
  App->>API: agent_status (agent_user, source)
  API->>V: check live agent record
  V-->>API: status, call_id, sub_status
  API-->>App: one CSV line
  App->>App: update wallboard

You send an HTTP GET, the endpoint looks up that agent's current live record, and it streams back one line of fields. There is no SUCCESS prefix — the data itself is the success. If the agent is not logged in, or the user id does not exist, you get a plain ERROR line instead, which makes parsing simple: an ERROR string means no live data.

Parameters

Required fields:

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

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
• include_ip — YES to append the last computer_ip the agent logged in from

An example call

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

A live agent comes back as a single CSV line of: status, call_id, lead_id, campaign_id, calls_today, full_name, user_group, user_level, pause_code, real_time_sub_status, phone_number, vendor_lead_code, session_id and (when you asked) computer_ip. For example a busy agent returns INCALL with a populated call_id and a Lead id, while a paused one returns PAUSED with a pause_code. The real_time_sub_status column is the useful nuance: it can be DEAD, DISPO, 3-WAY, PARK, RING, PREVIEW, DIAL, or empty — so an INCALL with a 3-WAY sub-status tells you the rep is mid Three-way call, and DISPO tells you they are in Wrap-up.

Permissions and a gotcha

The api user must have user_level 7 or higher and the "view reports" permission, or you get a PERMISSION error rather than data — the same bar covered in VICIdial API user-level permissions. Watch the distinction between AGENT NOT FOUND and AGENT NOT LOGGED IN — the first means the user id is wrong, the second is a normal idle state your code should treat as "nothing live", not an outage. Also remember the session_id in the output is the same value the blind_monitor function needs, so agent_status is often the first hop before you silently listen in.

Polling one agent at a time keeps a wallboard honest and your queries small. If you would rather not babysit the VICIdial box that serves these endpoints, our managed servers come provisioned and ready in under 40 seconds — see our pricing — or read the queue-level companion, reading an inbound group's live state.