Setting a pause reason with the pause_code function

When an Agent pauses between calls, VICIdial records that pause in the agent log. Without a reason code attached, all that data tells you is how long the agent was idle — not whether they were on a scheduled break, doing post-call wrap-up, or waiting for a supervisor. The pause_code function in the Agent API lets your system stamp a Pause code on a currently paused agent's session programmatically, without the agent having to select it from the screen.

A pause code is a short label — six characters or fewer — that categorizes why an agent stopped taking calls. Common examples include BREAK, LUNCH, TRAIN, and WRAP. These codes feed directly into workforce management reports and help supervisors distinguish productive off-call time from unexplained idle time. Over a full shift across a large floor, that distinction is the difference between a report you can act on and a wall of undifferentiated idle minutes.

How pause_code sets the reason

sequenceDiagram
  participant App as Your App
  participant API as agc/api.php
  participant Session as agent_session
  participant Log as agent_log
  App->>API: pause_code agent_user value=BREAK
  API->>Session: check agent is paused
  Session-->>API: pause confirmed
  API->>Log: write pause_code=BREAK to agent log
  Log-->>API: updated
  API-->>App: SUCCESS pause_code function sent

The function only works when the agent is already paused. If you call it while the agent is on a call or in ready state, the API returns ERROR: pause_code error - agent is not paused and nothing is written to the log. Your application must check or sequence its calls accordingly — pause the agent first, then stamp the code.

The parameter and an example call

The only function-specific parameter is value, which holds the pause code string. It must be six characters or fewer, so plan your code naming around that limit before you wire anything up. The standard user, pass, source, and agent_user parameters are required on every Agent API call. The agent_user is the agent whose pause you are labelling, while user and pass are the API account making the request.

curl "https://your-server/agc/api.php?source=wfm&user=6666&pass=1234&agent_user=1000&function=pause_code&value=BREAK"

A successful response is short:

SUCCESS: pause_code function sent - 6666

Note that the code you pass must already exist in the VICIdial pause code list. If it does not, the API returns ERROR: pause_code not valid. The valid codes are defined in the VICIdial admin panel under the pause codes section, so coordinate with your VICIdial administrator before sending codes from an external system. Pause codes can be defined globally or per campaign, which means a code that works on one campaign may be rejected on another.

When to use this from an external system

The most common use case is a workforce management or scheduling system that knows when a break is scheduled and stamps the correct code automatically when the agent pauses. This removes the reliance on agents self-reporting their pause reason, which is often inconsistent across a large team. If half your agents pick the wrong code from the dropdown out of habit, your adherence numbers are quietly wrong; driving the code from the system that owns the schedule fixes that at the source.

A second use case is an Agent session monitoring tool that detects anomalous idle time and flags it by setting a code like REVIEW, alerting supervisors to check in. Combined with the calls_in_queue_count function, you can build logic that labels pauses differently depending on current Call queue depth — a pause during high queue volume deserves more scrutiny than one during a slow period.

For more on how the API reads live session data, see how to read VICIdial API responses. The complete list of Agent API functions is in the VICIdial API and AGI overview. To run a VICIdial server with pause codes pre-configured and the API ready to use, see VICIfast plans — each one provisions in under 40 seconds.