Legacy VICIdial APIs

Legacy compatibility surface

These endpoints predate modern REST conventions. They accept credentials and commands as request parameters and often return delimited plain text. Use them only when a supported DialDozer API, CLI, or MCP tool does not cover the task. Test against a non-production VICIdial instance first.

VICIdial provides two independent PHP entry points. Pick by what the call affects, not by preferred output format.

Agent API — 31 functions

Controls a currently logged-in agent session: pause, dial, transfer, record, refresh, and related screen actions. See Agent API catalog.

Non-Agent API — 58 functions

Manages and reports on leads, users, phones, lists, campaigns, DIDs, DNC entries, recordings, and system state. See Non-Agent API catalog.

Connection contract

Surface	Base route	Session required
Agent API	https://{host}/agc/api.php	Target agent_user must normally be logged in
Non-Agent API	https://{host}/vicidial/non_agent_api.php	No agent-screen session; permissions vary by function

Common request fields:

• function: exact function name from a catalog.
• user and pass: credentials for an API-enabled vicidial_users account. These are API operator credentials, not necessarily the affected agent.
• source: short caller identifier, maximum 20 characters where documented. Give each integration a stable value such as dialdozer-mcp.
• agent_user: target VICIdial user where required.

Minimal connectivity checks

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

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

Security and transport

• Use HTTPS. HTTP support depends on server configuration and exposes query credentials in transit.
• Prefer curl --get --data-urlencode over hand-built URLs. Names, comments, dates, and + characters require correct encoding.
• Query strings may appear in reverse-proxy, web-server, browser-history, and observability logs. Redact pass, restrict log access, and use a dedicated least-privilege API user.
• Each function has separate VICidial permission and user-level checks. An authenticated request may still return ERROR: auth USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION.

Output contract

Do not infer success from HTTP status alone. Inspect the response body:

Prefix	Meaning	Agent action
SUCCESS:	Command accepted or mutation completed	Parse remaining text only if task needs returned identifiers
ERROR:	Validation, auth, permission, state, or lookup failure	Stop; surface complete line without secrets
NOTICE:	Per-item or informational result	Continue or aggregate according to task
VERSION:	Version probe result	Treat as successful connectivity check

Many report-style Non-Agent calls accept stage=pipe, csv, tab, or json; support is function-specific. pipe is commonly the default. Request stage=json only where the source reference lists it, and never assume every function returns JSON.

Agent execution checklist

1. Select one surface and exact function name.
2. Read its entry in the Agent catalog or Non-Agent catalog.
3. Verify the API account’s user level and function permission.
4. Encode every value; send a read-only lookup first when available.
5. Classify every response line by prefix. Never report success from exit code alone.
6. For multi-step operations, stop on first ERROR: and record completed steps for safe retry.

See task recipes for executable patterns.

Canonical source

These pages are a navigation layer, not a replacement for field-level documentation. Consult the repository sources before production use:

• docs/AGENT_API.txt — updated 2025-08-30 in the checked-in document.
• docs/NON-AGENT_API.txt — updated 2026-05-19 in the checked-in document.