AI Voice Agent editor

On Scripts, press New Script. On an empty script the page asks What are you building? Choose AI Voice Agent (or Classic Call Flow for a pre-recorded bot, see Script Builder). It says “Pick once”: after the first save the script always reopens here, because each save rebuilds the call flow and hand wiring would be lost.

The AI model behind the agent

The agent thinks with the model on the LLM provider tile on Integrations. If nobody saved that tile, calls use what the VoiceOI team deployed, and In effect now shows which. Saving your own Base URL, API key or Model changes every AI script in your organization, so ask the team first and retest in the Simulator. See Integrations and carriers.

Use Build from script, which opens by itself on a new agent and later sits in the tab bar. Paste the script your human agents read (at least 40 characters; text beyond 12,000 is cut off) and press Apply to the form. Fields it could not find, listed under Not in the script, keep their values. Nothing is saved until you press Save AI Agent, so check every tab.

• It never touches the transfer target, the voice, the timing settings or the transfer outcome’s “when” sentence, but it rewrites the other outcomes’ “when” sentences, so reread Do not call and Not interested.
• It keeps at most 12 questions, 12 knowledge answers, 10 guardrails and 5 alternative openings. The disclosure wording it finds may not be an AI disclosure. An AI service reads the pasted text, so paste no personal data about callers.

Use placeholders instead of typed names

Placeholders are filled in at call time. With rotation on, the agent’s name follows the voice, and a name typed into the opening line is swapped only where it matches Agent name exactly, so use {{agent_name}}. The Insert buttons also add {{company_name}}, {{lead name}}, {{lead phone}} and {{date}} (UTC, for example 10/18/2026). {{last user response}} is filled in once, before the caller speaks, so it does not follow the conversation.

What the fallback disposition does

It is used only when a call ends with no outcome and the bot cannot tell why, after the detected rows on the Outcomes tab. A hang-up is logged by the Caller hung up row, not by this field.

Reason for the call is one sentence the prompt asks the agent to give once, early, in its own words. That is an instruction to a model, not a spoken line, so test whether your agent says it, and use the Opening line if every caller must hear it.

Qualification is the list the agent asks, in order; you need one question to save. The prompt says to ask only these, once each, and to lean towards qualifying, so write questions that can fail clearly.

Each row has a code that VoiceOI sends to the dialer, a “when” sentence that tells the model when to pick it, and a closing line, spoken only if the model said nothing itself. A call that ends with no outcome gets a code set from how it ended, or the fallback code.

• The last row is detected from how the call ended. The agent is never offered those outcomes.
• The transfer row cannot be removed. A row added with Add outcome needs a code and a clear “when” sentence: with no code it writes none, and the model never sees the label.
• VICIdial drops a status that is not on the campaign’s status list, so check each code against it in VICIdial, or ask the VoiceOI team to check it with you. See status codes.

Knowledge is a list of question and answer pairs (Add answer). There is no document upload, website import or search over files: the agent gets only your persona, questions, these pairs and what the caller says. The pairs are in the prompt before every reply, so keep them short and factual. The screen lists five questions callers often ask, such as how did you get my number and am I talking to a robot. Write a true answer to each: you are responsible for what callers hear.

Fallback line is required. The agent says it when the model times out, errors or answers with nothing, then keeps listening; nothing is transferred. If the caller keeps talking while the model keeps failing, it can repeat until the turn limit. The grey example in the empty field promises a transfer, so do not write that.

Guardrails are rules added to the prompt, one line each. A model usually follows them but is not forced to, so test each in the Simulator. The AI disclosure switch is also on this tab.

No. A new agent starts with AI disclosure reading Not disclosed. When on, it reads Disclosed on every call and the line plays at the start of the AI conversation, before the opening line. It plays only on calls that run on the VoiceOI SIP bot servers (the VICIdial® path): not on built-in dialer calls and not in the Simulator. You write the wording.

Where qualified leads go

Transfer target and method

Transfer target is required in transfer mode, and the VoiceOI team confirms what to enter. Transfer method starts on ViciDial Native API (instant release), which asks VICIdial through its API to move the call, or sends a SIP REFER if it cannot work out the bot’s line or the lead. SIP blind transfer (REFER) sends the REFER directly. Use one of those two. On the servers that run AI agents, Direct extension transfer and Carrier bridge (compatible) send the same SIP REFER as SIP blind transfer (REFER), so they add nothing. See Live transfers and notes for your closers.

Comments for the closer

Comments is an instruction, not a template. The agent writes the note from the conversation, up to 255 characters, and VoiceOI tries to write it into the lead’s Comments in VICIdial just before the transfer. With no lead ID, or if VICIdial refuses, the transfer still goes ahead and the closer may see no note or an older one. See The closer sees no notes.

Writing details to a Google Sheet

With No transfer, choose a Spreadsheet and Tab from the Google account connected on Integrations. The editor lists “The agent will fill these columns” from the first row of the tab. Phone, Phone Number, Caller ID, Date, Time and Lead ID come from the call (Date and Time use the Primary Timezone on Settings, so check it there), and a Transcript column holds the caller’s side only. An AI model fills the other columns from the caller’s words alone, so “Homeowner” can come back wrong when the caller only said “yes”. Columns named notes, summary, outcome, comments, disposition or result get a one-sentence summary the model writes.

The row is built in the background as the call ends. With no Google account, an expired sign-in, no header row or every column empty, the agent still reports SALE and nothing is written, and a “row queued” timeline entry does not prove the row arrived, so check the sheet after test calls. See Google Sheets.

When the agent gives up

Max turns (default 10) counts every round of listening and replying, silent turns included. Silence limit in seconds (default 6) is how long the agent waits for the caller to speak: after one silent turn it says “Are you still there?” and a second in a row ends the call. A filler such as “uh” counts as silence, and a call ended by the turn limit (NP) or a repeated reply gets no closing line.

How the agent hears the caller

Recognition engine turns speech into text. The default, Turbo Realtime Engine (Ultra-Fast), mishears short words more than Deep Precision Engine (High Accuracy), which adds a delay. See recognition engines.

Interruptions and reply delay

Interruptions is off by default, so the agent finishes its sentence. Reply delay (300 to 1500 ms, default 700 ms) is the wait after the caller stops. See interruptions.

This tab shows the instructions built from the other tabs, plus a short fixed block of speaking guidance that VoiceOI adds and you cannot see. The badge reads Auto generated. If you edit the text it changes to Overridden and the other tabs stop changing the prompt; Revert to generated undoes that. Keep the generated ending list that links each “when” sentence to an outcome name.

Your settings are instructions to a language model, and a model can ignore or misread one, so no setting is a certainty. VoiceOI adds the rules below around the model. Test in the Simulator and review real calls in Call Logs.

What happens when a voicemail answers?

On a VICIdial account no machine-detection step runs in front of an AI agent, so the agent treats a recorded greeting as a caller, and the “Voicemail hangs up” strip at the bottom of the editor does not describe a live call. Only phrases in your Machines (Voicemail/Beeps) rules on Immediate Hangups end it, as AM. Add the phrases your greetings use, because speech recognition can mishear. Otherwise the agent can talk to a voicemail until the turn limit or silence ends the call. See answering machines.

1. 1

   Save and link a campaign

   Both

   Press Save AI Agent. The Simulator tests the script linked to a campaign. The VoiceOI team creates campaigns; you link the script under Assigned Campaign in Script Settings (the gear icon in the editor).

2. 2

   Run the Simulator

   You

   Choose the campaign under Select Campaign to Test, pick Text Simulator (Dry Run) or Browser Mic (WebSpeech API - Dry Run) in Chrome or Edge, and press Start Simulation. Try qualifying, refusing, a callback, a removal request, each Knowledge question and an Immediate Hangups phrase.

3. 3

   Test on a real call

   Both

   Put a lead with a number you control in a test list in VICIdial and let the campaign dial only that list (see How do I check that it works?). Check the disclosure, closing lines, transfer, the lead’s Comments, the code in VICIdial and the sheet row.

The Simulator is not a phone call. It skips the first-reply and question rules, speaks no closing lines, plays no disclosure and tests no transfers, status write-back or sheet rows. In No transfer mode its sheet step writes no row for an AI agent, yet it still ends the test with SALE and the message “Data synced to Google Sheets. Simulation ended.” Do not read that message as proof that the sheet works: test the sheet with a real call. See what the Simulator does not test. In Call Logs (titled Interaction Logs), Show System Nodes reveals AI Exit Decision, the outcome the agent chose.

• It does not make the sale, book appointments or schedule callbacks. CALLBK is only a code.
• It speaks English only and looks nothing up in your CRM or the web.
• It does not stay on the line after a transfer or introduce the caller.
• It hears no keypad presses, adds no one to a do-not-call list and sets no calling hours.
• It can be wrong: a model can pick the wrong outcome or misread a caller. Review real calls in Call Logs.

Consent, do-not-call lists, calling hours and caller ID stay with you. See Compliance and your responsibilities.