VICIdial API Guide Non-Agent API Agent API With Working Code Examples

VICIdial API Guide: Non-Agent API & Agent API With Working Code Examples

VICIdial has two APIs that most operators never touch. The Non-Agent API lets external systems inject leads, pull stats, control campaigns, and trigger calls without anyone logging into the admin GUI. The Agent API lets you build custom agent interfaces, programmatically disposition calls, and control screen behavior from outside the browser. Together, they turn VICIdial from a standalone dialer into a programmable call center engine that plugs into anything.

The documentation for these APIs exists — scattered across VICIdial's docs/ directory, forum posts from 2014, and tribal knowledge locked in the heads of a few senior developers. This guide consolidates all of it into a single working reference with real code examples.

VICIdial's API layer is HTTP-based. Every endpoint is a URL on your VICIdial web server that accepts GET or POST parameters and returns plain text, JSON, or pipe-delimited data. There are no WebSocket connections, no OAuth flows, no SDK libraries. You call a URL, pass credentials and parameters, and get a response. It's simple, which is both its greatest strength and most frustrating limitation.

This guide covers the Non-Agent API (for system-to-system automation), the Agent API (for controlling the agent interface programmatically), authentication and security, lead injection workflows, disposition webhooks, real-time stats pulling, click-to-call implementation, campaign control, rate limiting, error handling, and practical integration patterns you can deploy today.

Authentication and Security

Both APIs use HTTP basic authentication via URL parameters. Every request must include a valid username and password.

Non-Agent API Authentication

The Non-Agent API requires a user account with API access enabled:

1. Go to Admin -> Users -> [user] -> API Access
2. Set "API Access" to 1 (enabled)
3. Set "API Allowed Functions" to the specific functions this user can call (or leave blank for all)

# Basic authenticated request
curl "https://your-server/vicidial/non_agent_api.php?source=test&user=apiuser&pass=apipass&function=version"

Every request requires three base parameters:

• source — an identifier for the calling system (freeform text, used in logs)
• user — API username
• pass — API password

Agent API Authentication

The Agent API authenticates against the active agent session:

curl "https://your-server/agc/api.php?source=test&user=agent001&pass=agentpass&function=external_status&agent_user=agent001&value=SALE"

The agent_user parameter identifies which agent session to control. The user/pass must match the agent's credentials.

Security Hardening

VICIdial's API has no built-in rate limiting, no API keys, no OAuth, and no token-based authentication. Credentials are passed as URL parameters, which means they appear in web server access logs. Here's how to harden it:

1. HTTPS is mandatory. Without TLS, credentials travel in plaintext. Configure your Apache with a valid SSL certificate.

2. IP whitelisting via .htaccess:

# /var/www/html/vicidial/.htaccess
<Files "non_agent_api.php">
  Order Deny,Allow
  Deny from all
  Allow from 10.0.0.0/8
  Allow from 192.168.1.100
  Allow from 203.0.113.50
</Files>

3. Create dedicated API users with minimal permissions. Never use admin accounts for API access. Create a user with only the API functions it needs:

...

Read the full article

---

Read the full article: VICIdial API Guide: Non-Agent API & Agent API With Working Code Examples

More guides: ViciStack.com

Topics: VICIdial, Asterisk, Call Center, Predictive Dialer, VoIP