Bridgeside AI
← All posts
vicidialintegrationhow-todncNov 10, 20267 min read

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.php from 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:

ParameterMeaning
search_methodHow to find the lead: LEAD_ID or PHONE_NUMBER
search_locationWhere to search by phone: SYSTEM searches every list
statusThe new status code; it must exist in VICIdial
commentsFree text written to the lead's comments field
no_updateN 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:

  1. Calls update_lead with 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.
  2. Calls add_dnc_phone if the chosen code is flagged as DNC on the campaign.
  3. Shows the result on the call's page, either sent: with VICIdial's answer or failed: 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.

SymptomLikely cause and fix
HTTP 404 or an HTML page instead of a text lineWrong URL. It must end in /vicidial/non_agent_api.php
Error about the user, password or permissionWrong 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 foundThe 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 expectedCheck that the code exists in VICIdial and matches the mapping on the portal
Comments cut shortBridgeside sends at most 255 characters of summary
TimeoutsThe 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 dialedThe 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.

Put an AI agent on your dialer

60 free minutes, no card, one dialplan entry.