Agent API catalog

Route: https://{host}/agc/api.php
Common required fields: function, user, pass, agent_user, source
Common output: plain-text SUCCESS: or ERROR: lines; version returns VERSION:.

user/pass identify an API-enabled VICidial account. agent_user identifies the logged-in session to affect. source is an origin label of at most 20 characters. version is the documented exception and can be called without the common fields.

Function selector

Function	Purpose
`version`	Show API version, build, and date/time.
`external_hangup`	Hang up the target agent’s current customer call.
`external_status`	Set disposition and advance the target agent.
`external_pause`	Pause/resume now, or pause after the active call.
`external_dial`	Place a manual dial from the agent screen.
`preview_dial_action`	Apply `SKIP`, `DIALONLY`, `ALTDIAL`, `ADR3DIAL`, or `FINISH` during preview/manual alt dial.
`external_add_lead`	Add a lead to the logged-in agent campaign’s manual-dial list.
`change_ingroups`	Change selected in-groups for a logged-in agent.
`update_fields`	Change selected lead fields shown in the agent interface.
`set_timer_action`	Set a timer action for the agent’s current call.
`st_login_log`	Read `vicidial_users.custom_three` and log a CRM event.
`st_get_agent_active_lead`	Return active lead information for an agent.
`ra_call_control`	Hang up or transfer a call handled by a remote agent.
`send_dtmf`	Send a DTMF string to the agent session.
`transfer_conference`	Run transfer/conference frame commands.
`park_call`	Park a customer or retrieve one from park/IVR.
`logout`	Log the agent out of the agent interface.
`recording`	Start, stop, or query agent recording.
`stereo_recording`	Start or stop stereo agent recording.
`webserver`	Return web-server information for diagnostics/load balancing.
`webphone_url`	Return the current agent session’s webphone URL.
`call_agent`	Call an agent to connect them to their session.
`pause_code`	Set a pause code for a paused agent.
`audio_playback`	Play, pause, resume, stop, or restart audio in the agent session.
`switch_lead`	Switch the active lead ID for a live inbound call.
`calls_in_queue_count`	Return calls waiting in queues available to the agent.
`force_fronter_leave_3way`	Force the fronter agent to leave the current three-way call.
`force_fronter_audio_stop`	Stop audio playback in the fronter agent session.
`send_notification`	Send text alerts and/or confetti to the agent interface.
`vm_message`	Set the voicemail message used by the agent screen VM button.
`refresh_panel`	Refresh script, callbacks, form, or other agent-screen panels.

Request pattern

curl --fail-with-body --get "${VICIDIAL_URL}/agc/api.php" \
  --data-urlencode "source=dialdozer-cli" \
  --data-urlencode "user=${VICIDIAL_API_USER}" \
  --data-urlencode "pass=${VICIDIAL_API_PASS}" \
  --data-urlencode "agent_user=1000" \
  --data-urlencode "function=external_pause" \
  --data-urlencode "value=PAUSE"

Possible bodies include:

SUCCESS: external_pause function set - PAUSE|1232020456|6666
ERROR: agent_user is not logged in - 6666
ERROR: auth USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION - 6666|external_pause|ADMIN

Treat the response as a line protocol. Match the prefix, retain the full unmodified body for diagnostics, and redact credentials from request logs.

High-risk sequences

Agent operations are order-sensitive. For the source-documented “pause, hang up, disposition” flow, call:

external_pause with value=PAUSE
external_hangup with value=1
external_status with the intended disposition code

Stop if any step returns ERROR:. Retrying the entire sequence blindly can act on a later call. See task recipes.

Field-level reference

Function-specific values, required campaign settings, side effects, and exact error variants remain in docs/AGENT_API.txt. Use that file as canonical reference before invoking transfer, recording, remote-agent, timer, or lead-changing commands.