Ringing an agent's phone with the call_agent function

The call_agent function places a call from a logged-in Agent session to that agent's own phone, connecting the person to their session. It's a small piece of the VICIdial Agent API that matters most for setups where the agent's line isn't already glued open. For the full set of calls and how they fit together, see the VICIdial API overview.

When you'd use it

This is for the moment an agent has a live session in VICIdial but no audio path to it yet. A Remote agent working from a cell phone, or any agent whose phone you ring on demand rather than keeping a permanent line up, is the typical case. You trigger call_agent and VICIdial rings the agent's configured phone; when they answer, they're bridged into their session and ready to take calls. It's the programmatic version of the "call me" step some login flows do automatically.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Phone as Agent Phone
  App->>API: call_agent (agent_user, value=CALL)
  API->>V: place call from session to phone
  V->>Phone: phone rings
  Phone-->>V: agent answers
  V-->>App: SUCCESS call_agent function sent

The session has to exist first - call_agent connects an existing session to a phone, it doesn't create the session. If the session data isn't there, you get a clear error rather than a ring.

Parameters

• value - REQUIRED. CALL places a call from the agent session to the agent's phone. It is the only value this function takes.

Beyond user, pass, agent_user, and function, there's nothing else to pass. The phone that rings is whatever that Session ID is tied to, not a number you supply here.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=call_agent&value=CALL

A working call returns SUCCESS: call_agent function sent - 6666. The failure modes are specific: ERROR: call_agent error - no session data - 6666 when there's no session to call into, ERROR: call_agent error - entry is empty - 6666 when the phone entry to dial is missing, and ERROR: agent_user is not logged in - 6666 if the agent isn't logged in.

Gotchas to watch

The one rule to internalize: call_agent is not designed to work with on-hook agents. An on-hook agent already has their line bridged and held open, so there's no phone to ring - using call_agent there does nothing useful. It's built for the on-demand-call style of agent, the kind that uses a Softphone or cell that gets rung per shift rather than kept connected. Get the login mode wrong and you'll chase a "why won't it ring" ghost that's really just an on-hook agent. If you're scripting agent connectivity, the update remote agent function is a natural companion for managing those phones.

Running remote agents who get rung on demand is exactly what a managed VICIdial box handles cleanly. See how it's set up on our pricing page.