How to call the VICIdial Agent API (agent_api.php)

The Agent API acts on a live, logged-in agent's screen. Here is the function, user, pass, source pattern and the plain-text responses you'll get back.

The Agent API is a different animal from the Non-Agent API. Instead of editing leads or pulling reports, it reaches into a live, logged-in Agent session and drives the agent screen: dial a number, set a status, pause, hang up, log out. It only works while that agent is actually sitting in the VICIdial agent interface. If you are choosing between the two interfaces, our Non-Agent vs Agent API comparison lays out the split, and the VICIdial API overview covers the whole surface.

The model: act on a live agent session

Every Agent API call targets one agent_user who already has a live Agent session open. The call does not start a session; it injects an action into one that already exists. The agent's browser polls VICIdial constantly, so when you queue an action the next poll picks it up and the screen reacts: a number gets dialed, a Disposition gets set, the agent pauses. If the agent is not logged in, the call fails immediately. That is why click-to-dial from a CRM works only while the agent is parked in the dialer interface.

The function, user, pass, source pattern

Every call goes to agc/api.php and carries the same core query parameters: function (the action), user and pass (the API account, not the agent), source (a short label for what made the call), and agent_user (the login of the agent whose screen you are driving). Most action functions also take a value. The API is happy over HTTPS if your webserver is configured for it, which on a VICIfast box it always is.

function — the action to run, like external_dial, external_status, external_pause, or logout.
user / pass — the API account credentials. This is the authorizing account, separate from the agent.
source — a short description of what originated the call.
agent_user — the login of the target agent whose screen the action lands on.
value — the per-function payload, such as a phone number for external_dial or a status code for external_status.

How the call works

sequenceDiagram
  participant App
  participant API as agent_api.php
  participant V as VICIdial
  participant Agent as Agent screen
  App->>API: function (user, pass, source, agent_user, value)
  API->>V: verify API user and agent session
  V->>Agent: queue action for next poll
  Agent-->>V: action applied
  V-->>App: SUCCESS or ERROR text

You send the request, VICIdial authenticates the API user and confirms the agent is logged in, then queues the action against that session. The agent's screen applies it on its next poll.

Reading the response

Responses are plain text, never JSON. A call either starts with SUCCESS: and an explanation, or ERROR: and a reason. A quick check tool is the version function, which needs no auth and confirms the endpoint is alive:

http://server/agc/api.php?function=version
VERSION: 2.0.5-2|BUILD: 90116-1229|DATE: 2009-01-15 14:59:33|EPOCH: 1222020803

A real action returns something like SUCCESS: external_status function set - 6666|A. The errors are blunt and worth handling explicitly:

ERROR: agent_user is not logged in - 6666
ERROR: no user found - 6666
ERROR: auth USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION - 6666|webserver|ADMIN

Because the body is plain text, your integration should parse the SUCCESS or ERROR prefix rather than expecting a structured object. The pipe-delimited tail after the dash echoes back the values you sent, which is useful for logging.

The functions worth knowing

From here, each Agent API action gets its own deep dive. The two you will reach for most are click-to-dial, covered in the external_dial guide, and setting a result from outside, covered in our external_status guide. There is also external_pause to pause or resume, external_hangup to drop the current customer, and logout to end the Agent session. Pause and logout both wait for any live call to be dispositioned before they take effect, which keeps you from cutting an agent off mid-conversation.

Every VICIfast server runs the Agent API over HTTPS on its own Branded subdomain from the moment it is provisioned, so your CRM integration has a stable endpoint to call. See our pricing to get started.