Pausing and resuming an agent with external_pause

external_pause is a VICIdial Agent API function that pauses or resumes a logged-in Agent from outside the agent screen. Instead of the agent clicking PAUSE or RESUME, your application sends one HTTP request and the agent's session changes state. It is the everyday tool for letting a wallboard, scheduler, or CRM control whether an agent is taking Predictive dialing calls without the agent needing to touch anything.

When you'd use it

The classic use is a CRM that knows an agent is filling out a long form and shouldn't be handed a new call yet. Another is a break-management tool: it pauses the agent at the scheduled break and resumes them when it's over. You can also use it for PCI handling, where an outside flow pauses the agent while card details are entered. In every case the goal is the same — change the agent's ready state without asking the agent to do it. If you want to attach a reason to the break instead, that's a Pause code concern handled elsewhere; external_pause itself just flips the session in or out of a paused Status (lead status).

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Agent
  App->>API: external_pause (agent_user, value=PAUSE)
  API->>V: find agent session
  alt agent on a live call
    V->>Agent: wait until call is dispositioned
  end
  V->>Agent: set session to PAUSED
  V-->>App: SUCCESS function set

There is one subtlety worth knowing up front. If you send PAUSE while the agent is on a live call, VICIdial does not yank them off the customer. It queues the pause, and the agent is paused only after they finish and disposition the current call. RESUME works the same way through the agent's Agent session.

Parameters

• agent_user — the login of the agent you want to pause or resume. Required.
• value — PAUSE to pause the session, or RESUME to bring the agent back to ready. Those are the only two values.

Plus the usual source, user, pass, and function fields that every Agent API request carries.

An example call

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

A success looks like SUCCESS: external_pause function set - PAUSE|1232020456|6666. The middle number is an epoch timestamp for when the change was set, which is handy for logging. To resume, send the same request with value=RESUME. Errors come back as plain text too: ERROR: agent_user is not logged in - 6666 if the agent has no session, ERROR: no user found - 6666 for bad API credentials, and ERROR: external_pause not valid - PAUSE|6666 if you sent something other than PAUSE or RESUME.

Gotchas

Don't assume PAUSE takes effect instantly during a call — it doesn't, it waits for the disposition. Build your logic around that delay or you'll think the call failed. Also remember the agent must be logged in; pausing a session that doesn't exist just returns the not-logged-in error. For the broader picture of how these session-control calls sit alongside the rest of the API, read the VICIdial API and AGI overview.

external_pause is one of those small functions that ends up wired into every serious VICIdial integration. If you'd rather run it on managed infrastructure that stands up a fresh dialer in under 40 seconds, check our pricing. For the difference between session calls like this and the data-side calls, see Non-Agent API vs Agent API.