Legacy API task recipes

Check connectivity

No agent session is needed for version.

curl --fail-with-body --get "${VICIDIAL_URL}/agc/api.php" \
  --data-urlencode "function=version"

Expected prefix: VERSION:. This proves the script is reachable, not that an API account has permission for other functions.

Read one agent’s live status

Use Non-Agent agent_status for observation. Do not use Agent API screen controls for a read-only status task.

curl --fail-with-body --get "${VICIDIAL_URL}/vicidial/non_agent_api.php" \
  --data-urlencode "source=dialdozer-mcp" \
  --data-urlencode "user=${VICIDIAL_API_USER}" \
  --data-urlencode "pass=${VICIDIAL_API_PASS}" \
  --data-urlencode "function=agent_status" \
  --data-urlencode "agent_user=1000" \
  --data-urlencode "stage=json" \
  --data-urlencode "header=YES"

Permission baseline in the source: API user level 7+ with report access. Handle ERROR: agent_status AGENT NOT LOGGED IN as a valid state, not a transport failure.

Pause or resume an agent

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"

Replace PAUSE with RESUME to resume. If the agent is on a call, pause may take effect after the call. Require SUCCESS: external_pause function set.

Pause, hang up, and disposition an agent

The canonical Agent API specifies this order:

external_pause with value=PAUSE
external_hangup with value=1
external_status with the intended disposition code, such as A

Send each as a separate request and inspect its body before continuing. Do not run steps in parallel. Record current call identity before step 1; after a retry or delay, verify the same call is still active.

Find a lead before changing it

curl --fail-with-body --get "${VICIDIAL_URL}/vicidial/non_agent_api.php" \
  --data-urlencode "source=dialdozer-mcp" \
  --data-urlencode "user=${VICIDIAL_API_USER}" \
  --data-urlencode "pass=${VICIDIAL_API_PASS}" \
  --data-urlencode "function=lead_all_info" \
  --data-urlencode "lead_id=1079425" \
  --data-urlencode "header=YES" \
  --data-urlencode "custom_fields=Y" \
  --data-urlencode "stage=json"

Use returned lead_id, list_id, and current values as a precondition for a later update_lead. The source also allows phone-number lookup, but IDs are safer mutation targets.

Add numbers to DNC

Use Non-Agent add_dnc_phone; DNC scope and required fields depend on whether the target is a system or campaign DNC list. Resolve the exact documented fields in the source before sending. Verify with the appropriate read/search workflow in your deployment, then require SUCCESS: from the mutation.

For reversal, use the separate delete_dnc_phone function. Never infer that an empty value passed to add_dnc_phone deletes an entry.

Add leads to a hopper in bulk

curl --fail-with-body --get "${VICIDIAL_URL}/vicidial/non_agent_api.php" \
  --data-urlencode "source=dialdozer-cli" \
  --data-urlencode "user=${VICIDIAL_API_USER}" \
  --data-urlencode "pass=${VICIDIAL_API_PASS}" \
  --data-urlencode "function=hopper_bulk_insert" \
  --data-urlencode "lead_ids=193715,1677922" \
  --data-urlencode "hopper_priority=97" \
  --data-urlencode "hopper_local_call_time_check=Y"

Parse all lines. NOTICE: reports each accepted or rejected lead; final SUCCESS: summarizes the batch. A successful summary does not imply every lead was inserted.

Parser rules for agents

if body starts with "ERROR:": stop and return error
else if body starts with "VERSION:": connectivity succeeded
else if any line starts with "NOTICE:": retain per-item results
else if expected mutation and no line starts with "SUCCESS:": return unexpected-format error
else parse only the delimiter or JSON format documented for that function

Never parse human explanation text to infer identifiers when a delimited field is documented. Keep raw response alongside structured output for audit and troubleshooting.