How to call the VICIdial Non-Agent API over HTTP

A plain walkthrough of building your first VICIdial Non-Agent API call: the URL, the required parameters, and a working example you can paste into a browser.

You have a brand-new VICIdial server and a job to do from outside the agent screen. Maybe a script needs to push leads, list your campaigns, or grab a list of audio files. The tool for that is the Non-agent API — the part of the Application Programming Interface (API) that handles everything not tied to a live agent. This post shows you how to make your first call.

It is just a URL

The Non-Agent API lives at one PHP file: non_agent_api.php. You call it by hitting a web address — a Uniform Resource Locator, or URL (in VICIdial) — and passing your instructions as query parameters. The simplest call asks for the API version:

curl "http://server/vicidial/non_agent_api.php?function=version"

Swap server for your server's hostname. The reply tells you the version, build, current date, time zone, and daylight-saving offset — a quick way to confirm the API answers at all before you wire up anything bigger. The version check is the one call that needs no login, which makes it the perfect smoke test when you are setting up a new integration.

A typical version reply looks like this:

VERSION: 2.4-34|BUILD: 110424-0854|DATE: 2011-05-29 12:19:22|EPOCH: 1306685962|DST: 1|TZ: -5|TZNOW: -4|

The four parameters every real call needs

Anything beyond the version check needs you to identify yourself. Four parameters carry the load:

function — which action you want, such as campaigns_list or add_lead.
user and pass — the login and password of an API-enabled VICIdial user account.
source — a short label (up to 20 characters) describing what made the call, so you can trace it later in the logs.

Here is a complete call that lists every Campaign on the system:

curl "http://server/vicidial/non_agent_api.php?source=myapp&function=campaigns_list&user=6666&pass=1234"

What happens after you hit send

sequenceDiagram
    participant App as Your app
    participant API as non_agent_api.php
    participant DB as VICIdial database
    App->>API: HTTP GET with user, pass, function
    API->>API: Check user is API enabled
    API->>DB: Run the requested action
    DB-->>API: Rows or status
    API-->>App: SUCCESS or ERROR text

The API checks that your user exists and is allowed to run that function, talks to the database, and replies in plain text. You read the result the same way you would read any HTTP response. There is no session to open and no token to refresh — every call carries its own credentials, so a one-line curl or a single request from your own code is all it takes. That statelessness is what makes the API easy to script from cron jobs, web forms, or a back-end service.

Two mistakes catch most newcomers. The first is forgetting the function parameter, which gets you a blunt ERROR: NO FUNCTION SPECIFIED back. The second is using an account that has not been enabled for API access, which returns a permission error even when the login itself is valid.

Your user and password ride in the URL. Anyone watching plaintext traffic can read them. Always call the API over HTTPS, not plain HTTP — see how to secure the VICIdial API.

That is the whole pattern: one PHP file, a function parameter, your credentials, and a source label. For the bigger picture of how this fits with the Asterisk Gateway Interface and the rest of the stack, read the VICIdial API and AGI overview.

Running on managed hosting means HTTPS and an API-enabled user are set up for you on day one, so your first API (application programming interface) call works without touching a config file. See what is included on our pricing page.