The VICIdial API and AGI guide: every way to integrate VICIdial with outside systems

Why you would connect VICIdial to anything else

You run a dialer, but the dialer is never the only system in the building. Your sales reps live in a CRM. Your accounting team has its own database. Your website collects leads through a form. Sooner or later you want all of those to talk to VICIdial without somebody copy-pasting phone numbers by hand.

That is what integration means here. When a deal closes in your CRM, you want that record to stop dialing. When a web visitor fills out a form, you want them in the dialer within seconds. When a call ends, you want the outcome pushed back out to your reporting tool. None of that needs a human in the middle.

VICIdial gives you three doors to do this, and people mix them up constantly. This guide draws the map. Read it once, then jump to the deep guide for whatever you actually need to build.

API versus AGI: the one distinction to get right

An Application Programming Interface (API (application programming interface)) is a way for one program to ask another program to do something. In VICIdial it is a web address you call over HTTP. Your code sends a request like "add this lead" and gets back a one-line answer that says SUCCESS or ERROR. Your app starts the conversation; VICIdial answers.

The Asterisk Gateway Interface (AGI (Asterisk Gateway Interface)) is the opposite direction. AGI is a small script that the phone engine itself runs in the middle of a live call. The call hits a point in the Dialplan — the rulebook Asterisk follows to decide where a call goes — and that rule says "run this script now." The script looks something up, makes a decision, and tells the call where to go next. VICIdial starts that conversation; your script answers.

Hold onto that. The API is for data and control from the outside. AGI is for routing decisions from the inside, while a call is ringing. One more thing newcomers stumble on: the API and AGI are not rivals. You will often use both in the same project, each for the part it is good at. If you want a fuller side-by-side, read the non-agent API versus agent API breakdown and what AGI actually is in VICIdial.

The three doors, in one picture

VICIdial splits its web API into two halves, and then there is AGI on the phone side. So three doors total. Each one touches a different part of the system.

flowchart LR
  App[Your app or CRM] --> NA[Non-Agent API]
  App --> AG[Agent API]
  Dial[Asterisk dialplan] --> AGI[AGI scripts]
  NA --> Data[Leads, users, lists, DIDs]
  AG --> Live[Live agent session]
  AGI --> Route[Call routing and lookups]

The non-agent API manages data: leads, users, lists, DIDs, the dialing queue. The agent API drives one live agent at a time: dial, hang up, pause, transfer. AGI runs inside calls and steers them. Let us take each door in turn.

Door one: the non-agent API (server-side data)

The non-agent API (Non-agent API) handles everything that is not the live agent screen. It lives at one URL (in VICIdial), usually something like non_agent_api.php, and you pick what it does with a function parameter. You always send a user and password for a VICIdial account that has API access turned on, plus a short source label so you can tell later which app made the call.

Here is a plain add_lead call. It drops one new lead into list 999 and checks the system for duplicates first:

curl 'https://your-server/vicidial/non_agent_api.php?source=mycrm&user=6666&pass=1234&function=add_lead&phone_number=7275551212&phone_code=1&list_id=999&duplicate_check=DUPSYS'

The answer comes back as a single line. A good result starts with SUCCESS or NOTICE; a problem starts with ERROR and tells you what went wrong, like a duplicate phone number or a missing permission. Once you can read those lines, the rest of the API feels the same. Start with how to call the non-agent API and how to read VICIdial API responses.

What can this door do? Quite a lot, and it keeps growing. The common jobs split into a few buckets.

• Leads. Add a single Lead with add_lead, change one with update_lead, or change many at once with batch_update_lead.
• Lists and the queue. Build a list with add_list, and push leads into the dialing queue, the Hopper, with the hopper insert call.
• Compliance. Add a number to your do-not-call list, the DNC (do not call), straight from another system with the DNC API.
• Inbound numbers and users. Add a DID (direct inward dialing) (an inbound phone number) with the DID API, or create a login with add_user.
• Reporting exports. Pull agent activity numbers out on a schedule with the agent stats export, or look up recordings with recording_lookup.

That permission model deserves its own read: VICIdial API user-level permissions walks through which level each function needs.

Locking this door down matters more than any single function. Read how to secure the VICIdial API before you point anything real at it. On VICIfast you get HTTPS on a branded subdomain from the first minute, so this part is handled. See the plans.

Door two: the agent API (one live session)

The agent API (Agent API) is a separate web address, usually api.php under the agent screen folder, and it does one thing the data API cannot: it reaches into a live agent session and pushes buttons. Think of it as a remote control for an agent who is already logged in.

This is the door behind a "click to dial" button. Your CRM shows a contact, the agent clicks call, and your code fires an agent API request that tells VICIdial to dial that number from the agent's session. The agent never types the number.

Same shape as the other door: a function parameter, plus a credentialed account, plus the agent's user ID so VICIdial knows whose session to drive. The replies are the same one-line SUCCESS or ERROR. Begin with how to call the agent API.

The everyday calls cover the buttons an agent presses all day:

• Dial a number from the session with external_dial, and hang up with external_hangup.
• Pause or resume the agent with external_pause, and set the call outcome, the Disposition, with external_status.
• Transfer or conference a live call with the transfer-conference call, or move the agent between inbound queues with change_ingroups.
• Drive a remote agent's call with ra_call_control, the function behind ra_call_control.

Because this door controls a real session in real time, it is the heart of any custom dialing tool. If a click-to-dial button is your goal, the click-to-dial guide ties the pieces together end to end.

Door three: AGI scripts (decisions inside the call)

The first two doors are things your software pokes from outside. AGI is different. An AGI script runs while a call is up, called by Asterisk at an exact step in the dialplan. It can look at the caller's number, query the database, then decide where the call goes — all in the half-second before the phone rings. Nothing outside the server triggers it. The call itself does, by reaching the line in the dialplan that names the script. That timing is the whole point: AGI is your chance to change a call's path based on who is calling, before a human ever picks up.

VICIdial ships with a stack of these scripts and uses them for its own plumbing. A few of the heavy hitters:

• Inbound routing. The script that reads the dialed DID (direct inward dialing) and sends the call to its DID route is covered in the DID-route AGI guide.
• Answering machine detection. After AMD (answering machine detection) decides whether a human or a machine picked up, an AGI script sends the call onward; see the AMD AGI guide.
• Outbound and inbound transfer scripts move auto-dialed calls to agents; see the all-inbound transfer AGI and the all-outbound transfer AGI.
• Recording. Turn call recording on from inside the dialplan with the recording AGI.

A big family of AGI scripts is built for the Call menu — the phone-tree, or IVR (interactive voice response), that greets inbound callers and offers options. These are the scripts that look something up about the caller and then route based on the answer. One searches the caller's number against your lead database and forwards the call to the matching campaign's queue. Another reads the area code and routes by region. To wire one into a menu, read how to add an AGI to a call menu, then the lookup-specific guides like the phone-search call-menu AGI and the send-URL call-menu AGI.

When the shipped scripts run out, you can write your own. How to write a custom AGI shows the pattern. Just remember the trade: AGI gives you control inside the call, but a slow or broken script slows or breaks the call. Keep it fast and keep it simple.

Which door for which job

A quick rule of thumb so you stop second-guessing:

1. Moving data in or out — leads, lists, DNC, DIDs, reports? Non-agent API.
2. Pressing buttons for a logged-in agent — dial, pause, transfer? Agent API.
3. Deciding where a live call goes, based on a lookup? AGI in the dialplan.

Real projects mix them. A clean CRM integration usually pushes new leads in with the non-agent API, lets agents click to dial through the agent API, and pushes call results back out with a call-menu URL script. Walk the whole flow in how to push leads from a CRM and how to sync dispositions out of VICIdial.

Where to start tomorrow

Pick the smallest thing that saves real time. For most teams that is one add_lead call from the web form, so leads land in the dialer the instant someone submits. You can build that in an afternoon in whatever language you already use; calling the API from your app's language has the snippets.

Whatever you build, the integration is only as reliable as the server under it. The API and AGI both assume HTTPS, a stable box, and a database that does not fall over under load. On VICIfast you get a dedicated, secured server on a branded subdomain in under a minute, so you can spend your time on the integration instead of the plumbing. Check the pricing and start wiring VICIdial into the rest of your stack.