The VICIdial Non Agent API for AI Agents, Users, Calls and Errors
What the VICIdial non-agent API is, how to create a locked-down API user, the requests an AI agent needs to set a lead's status and comments and add DNC numbers, and how to fix errors.
Every outside system that needs to change something in VICIdial without sitting in an agent screen ends up at the same place: the VICIdial non agent API. CRMs use it to add leads, reporting tools use it to pull stats, and an AI voice agent uses it to do what a human agent does at the end of a call, which is set the lead's status, leave a note and honor a do-not-call request.
This guide covers what the non-agent API is, how to create an API user that can do only what it needs, the three requests an AI agent sends, and what to do when VICIdial answers with an error.
What the VICIdial non agent API is
The non-agent API is a single PHP script on your web server, normally at:
https://<your dialer>/vicidial/non_agent_api.php
You call it over HTTP with the parameters in the query string (or as a form post). Every request names a function, carries a user and pass for a VICIdial user, and includes a source, a short label of your choosing that VICIdial records so you can tell which system made the request. The answer is plain text. For most functions it is one line that starts with SUCCESS or ERROR, followed by details.
It is separate from the agent API (/agc/api.php), which drives a logged-in agent's session: pausing, dialing, hanging up on behalf of that agent. An AI agent that is not a VICIdial user has no agent session, so the non-agent API is the right tool. The full list of functions and parameters for your build is in NON-AGENT_API.txt in VICIdial's docs folder; read the copy that matches your version, because functions and options have been added over the years.
Create a secure API user
In Admin > Users, add a user that will never log in as an agent. Give it:
- User level 8 or higher. Lead updates through the API need it.
- Modify Leads = 1. Without it, status and comment updates are refused.
- API access. The user must be allowed to call
non_agent_api.php. - A long random password used nowhere else.
Then lock it down with whatever your version offers. Depending on the build, the user record has options to make the user API only (no admin screen login), to limit the API functions it may call, and to restrict the addresses it may connect from through IP lists. For an AI agent, the functions it needs are version, update_lead and add_dnc_phone. If your version supports an IP list for API use, allow only the AI service's address.
Two more habits matter because the credentials travel in the URL:
- Use HTTPS only. Plain HTTP exposes the user and password on the wire.
- Watch your web server logs. Query strings are written to access logs by default. Limit who can read them, or exclude
non_agent_api.phpfrom the log.
The three requests an AI agent needs
The examples use placeholders. Replace the host, user and password with your own, and URL-encode any value with spaces.
Check the connection with version
https://<dialer>/vicidial/non_agent_api.php?source=aitest&user=<api user>&pass=<api pass>&function=version
A working setup answers with the VICIdial version and build. This is what Bridgeside AI's Test API button on the Dialers page sends; if it fails, nothing else will work.
Set the status and comments with update_lead
By lead id, which is the reliable path for auto-dialed calls:
https://<dialer>/vicidial/non_agent_api.php?source=aiagent&user=<api user>&pass=<api pass>&function=update_lead&search_method=LEAD_ID&lead_id=12345&status=NI&comments=Caller%20said%20they%20already%20switched%20providers.&no_update=N
By phone number, when no lead id is known:
https://<dialer>/vicidial/non_agent_api.php?source=aiagent&user=<api user>&pass=<api pass>&function=update_lead&search_method=PHONE_NUMBER&phone_number=5551234567&search_location=SYSTEM&status=CALLBK&comments=Asked%20for%20a%20call%20after%205pm.&no_update=N
What the parameters do:
| Parameter | Meaning |
|---|---|
search_method | How to find the lead: LEAD_ID or PHONE_NUMBER |
search_location | Where to search by phone: SYSTEM searches every list |
status | The new status code; it must exist in VICIdial |
comments | Free text written to the lead's comments field |
no_update | N to apply the update; Y only checks that the lead exists |
Setting a status of CALLBK this way changes the status only. It does not schedule a callback for a date and time, so use your recycling rules or a lead filter to bring those leads back.
Add a number to DNC with add_dnc_phone
When a caller asks not to be called again, Bridgeside AI sends a request of this shape:
https://<dialer>/vicidial/non_agent_api.php?source=aiagent&user=<api user>&pass=<api pass>&function=add_dnc_phone&phone_number=5551234567&dnc_choice=SYSTEM
This adds the number to the system-wide internal DNC list. Campaigns only skip numbers on that list if they are set to use the internal DNC list, so check that setting on every campaign. Compare the parameters against the NON-AGENT_API.txt for your version before relying on it, and test it with a number you control.
How Bridgeside AI uses the API
After each call, Bridgeside sends the transcript to the language model once and asks it to pick the single disposition code that fits best from the campaign's list, write a summary of at most two sentences, and fill any typed answers the script collects. Then it:
- Calls
update_leadwith the chosen status and the summary as comments (at most 255 characters). It uses the lead id that VICIdial put in the caller ID name, and falls back to the phone number. - Calls
add_dnc_phoneif the chosen code is flagged as DNC on the campaign. - Shows the result on the call's page, either
sent:with VICIdial's answer orfailed:with the error, and offers Re-run & resend.
If the model returns no usable code, the campaign's fallback mapping applies: one code for a transfer, one for an agent hangup, one for an appointment and one for a caller hangup. The default codes are SALE, NI, APPT, CALLBK, DNC and DROP. The complete VICIdial AI integration guide shows where this step sits in the whole call. More on routing and pilots is in the VICIdial AI agent guide, and the compliance side of DNC handling is in VICIdial TCPA compliance.
Create the statuses first
A status the API sends must already exist in VICIdial, as a system status or a campaign status (Admin > Campaigns > your campaign > Statuses). Codes are six characters at most. Create them before you map them on the Bridgeside portal, and decide which ones count as human answers, sales or DNC in your reports.
Error messages and troubleshooting
VICIdial's error lines start with ERROR: and name the function and the reason. Read the full line; it usually tells you exactly what is wrong.
| Symptom | Likely cause and fix |
|---|---|
| HTTP 404 or an HTML page instead of a text line | Wrong URL. It must end in /vicidial/non_agent_api.php |
| Error about the user, password or permission | Wrong credentials, user level below 8, Modify Leads not set, API access not allowed, or the function is not in the user's allowed list |
| Error saying no lead was found | The lead id is wrong, or the phone search found no lead. Inbound callers who are not leads cannot be updated |
| Status missing or not what you expected | Check that the code exists in VICIdial and matches the mapping on the portal |
| Comments cut short | Bridgeside sends at most 255 characters of summary |
| Timeouts | The AI service cannot reach your web server on 443, or a firewall blocks it. Bridgeside waits 10 seconds per request |
| DNC added but the number is still dialed | The campaign is not set to use the internal DNC list |
To test by hand, paste a version URL into a browser from an allowed address, then an update_lead with no_update=Y against a known lead.
FAQ
What is the non agent API in VICIdial?
It is non_agent_api.php, a web endpoint that lets outside systems add and update leads, manage DNC numbers and read information without an agent session. Each request names a function and authenticates with a VICIdial user.
What permissions does the VICIdial non agent API user need?
For lead updates, user level 8 or higher, Modify Leads set to 1 and API access allowed. Restrict it further to the functions and addresses it needs.
Can the non agent API add a number to the DNC list?
Yes, with add_dnc_phone. Campaigns honor the internal list only when their DNC setting tells them to use it.
Is the non agent API the same as the agent API?
No. The agent API controls a logged-in agent's session. The non-agent API works without any agent and is the right choice for CRMs, reporting and AI agents.
Why does update_lead say no lead was found?
The lead id or phone number does not match a lead, or you searched by phone in a narrower location than the lead lives in. Try search_location=SYSTEM, or confirm the lead id in the lead search screen.
Ready to see it write back to your own leads? Read the VICIdial integration page, then start with 60 free minutes and no card at app.bridgeside.ai, or contact us for help with the API user.