Script Builder: build a voice bot call flow

Your bots run on one of two engines. The VICIdial (SIP) engine takes the calls VICIdial sends to the bots. The built-in (Asterisk) engine takes the calls the built-in dialer places. To find out which one you have, see Which setup do I have?

Open Scripts in the sidebar. The page is titled Script Editor, and its Campaign Assignment column shows each script’s linked campaign or Unassigned. Team members with the SubManager role do not see it.

The VoiceOI team creates your campaigns. You link a script to one in Script Settings (the gear icon in the builder) under Assigned Campaign. The Simulator tests the linked script. A script linked to a live campaign can start taking calls at once, so read the warning under How do I test a script? first. On a VICIdial account whose bot route names a script ID, a live call runs that script, whichever script is linked. Copy Script ID in the row menu gives the ID, and the VoiceOI team adds it to the route with you; to move a campaign to another script, send the team its ID. Duplicate makes a script with a new ID and no campaign. See Always dial the script ID.

A script controls what the bot says and where a call goes. Which leads are dialed, and when, stays in VICIdial or the built-in dialer.

There are three ways to build a script, plus templates. Which ones you see depends on what the VoiceOI team has turned on for your account.

To share a script, use Publish to Marketplace in the row menu. The template carries your recordings and every node’s settings as saved, including a Transfer Call destination and any Google Sheets details, and other accounts can install it once it is listed. Remove or replace those first, and leave your customers’ details out. A community submission goes to review before it is listed.

1. 1

   Create the script

   You

   On Scripts, press New Script, type a Script Name and press Create & Open Editor. If you have no campaign yet, ask the VoiceOI team for one and link it later in Script Settings.

2. 2

   Add a node

   You

   Press Add Node at the top left of the canvas and pick a type, or drag a type onto the canvas. The Step Configuration panel opens on the right. Give the node a clear Step Name: the Google Sheets step lists earlier answers by step name.

3. 3

   Mark the start

   You

   Select the first node and turn on Set as Start Node. A script has one start node. It shows a START badge and has no input dot, so no line can lead back to it.

4. 4

   Connect the nodes

   You

   Drag from the dot on the right edge of a node to the dot on the left edge of the next one. Each output dot holds one line, so connecting it again moves the line. Select a line or a node and press Delete or Backspace to remove it.

5. 5

   Set the audio and the settings

   You

   Choose or upload a recording for each audio node and set the fields described in node types.

6. 6

   Save and test

   You

   Press Save Flow, then run the script in the Simulator.

This small flow asks one question, asks again when the caller says something else, sends yes to a transfer and ends the call on no.

1. 1

   Add the greeting

   You

   Add a Play Audio node with your greeting recording and turn on Set as Start Node.

2. 2

   Add the question

   You

   Add a Listen node and connect the greeting to it. Choose the question recording as Prompt Audio (Bot Speaks First), and under Expected Answers (Keywords) add one option with the keyword yes and one with no.

3. 3

   Draw the re-ask loop

   You

   Add a second Play Audio node with a short “sorry, I didn’t catch that” recording. Connect Any Other Input and No Answer / Silence to it, then connect it back to the Listen node. Set Max Retries on the Listen node to 2, so the call ends after two re-asks instead of looping.

4. 4

   Send yes to a transfer

   Both

   Add a Transfer Call node, connect the yes option to it and enter the destination the VoiceOI team gave you. See Transfer Call.

5. 5

   End the call on no

   You

   Add an End Call node, connect the no option to it and set its Vicidial Disposition to NI.

6. 6

   Handle opt-outs yourself

   You

   Callers who ask not to be called again may use words this script does not treat as an opt-out. The keyword no also matches “stop”, so “stop calling me” ends as NI, and “take me off your list” matches neither option and is asked again. Add the opt-out phrases you want honored as rules in the DNC Keywords (Profanity/Abuse) category on Immediate Hangups: an answer that matches one ends the call before the keyword options are checked and logs DNC. See do-not-call handling.

7. 7

   Save and test

   You

   Press Save Flow, then run the script in the Simulator. It has no disclosure line built in. If you need one, record it and put it at the start.

The controls every node shares are under settings every node has.

Settings every node has

The Vicidial Disposition list offers A Answering Machine, B Busy, CALLBK Call Back, DAIR Dead Air, DC Disconnected Number, DEC Declined Sale, DNC Do Not Call, N No Answer, NI Not Interested, NP No Pitch No Price, NQ Not Qualified, SALE Sale Made, XFER Call Transferred and CBHOLD Scheduled Callback. The list also shows OVERAGE (Overage / Insufficient Funds). Do not pick it: it has 7 characters, VICIdial statuses are 1 to 6 characters long, and VICIdial cannot store it.

• VICIdial drops statuses it does not know. A status that is not in your VICIdial campaign’s status list is dropped by VICIdial. The VoiceOI team checks the list during onboarding. Ask before you use NQ.
• Dead air depends on the transcript. On the VICIdial (SIP) engine, DAIR is written only when nothing was transcribed on the call. If the caller said anything, it is written as NA.
• Some codes are sticky. Once a call holds SALE, NI, CALLBK, DEC, DNC, CBHOLD or AM, a later node can replace it only with another code from that group.
• The code is set when the bot reaches the node, not when it leaves it.
• These are status labels only. On the built-in dialer, NQ and DC are recorded as N. CALLBK and CBHOLD log the label and nothing more: VoiceOI does not schedule a callback or redial the lead.

Nodes that appear only when enabled

These nodes appear in Add Node only when the VoiceOI team turns the matching feature on for your account.

A Listen node has one output dot for each answer option, plus No Answer / Silence (nothing was heard) and Any Other Input (something was heard that matches no option). With Smart Listen on, Any Other Input is renamed Not understood. Connect every dot: a path with no line ends the call when it is taken. Which engine reads which field is in the engine table.

Allow Interruption is a switch on Play Audio, Listen, Check Condition, Wait and AM Detect nodes. It lets the caller talk over a recording, and it adds an Interruption dot to the node. Only the built-in engine follows the line from that dot; see the engine table and, for Turbo answers while a question plays, recognition engines.

AM Detect separates a person from an answering machine. A machine ends the call and logs it as AM. A person continues to the next node. VoiceOI has no voicemail drop, and detection is not perfect, so review calls logged as AM. The node has an optional Greeting Audio (Played during detection) and four timing fields with these defaults: Greeting Threshold (sec) 2.5, Silence Threshold (sec) 1.2, Initial Silence (sec) 2.5 and Total Analysis Time (sec) 5. The boxes under Advanced AMD Parameters are not settings you tune. Leave them as they are.

• Engines. The built-in engine sends the four timing fields to Asterisk’s machine detection and ignores some low-confidence machine verdicts, such as an initial silence, so the call carries on. The VICIdial (SIP) engine does not use them: see the engine table.
• Both engines also check every answer a Listen node hears against your Immediate Hangups rules, whatever their category. A rule in Machines (Voicemail/Beeps) ends the call and logs AM. A rule in DNC Keywords (Profanity/Abuse) ends the call and logs DNC. It does not add the number to any list. See what happens at voicemail.

Play Audio, Listen, AM Detect and Age Extraction nodes share the same audio controls: Audio File to choose or upload a recording, Audio Takes to add other versions of a line, and Voices to manage voices. A call keeps one voice for the whole conversation, so record every audible step in that voice. The full guide is Voices, audio takes and the Simulator, with takes and rotation and adding audio files.

A Listen node, and an Age Extraction node, turns the caller’s answer into text with the engine you choose under Recognition Engine (ASR). The screen’s own guidance is: “Turbo for instant menus/yes-no, Turbo 2.0 for ages and numbers, Neural for conversational dialogue, Precision for names/addresses.”

The screen shows no price for any engine. Callers are understood in English only today.

A Check Condition node tests one or more rules and sends the call down True or False. It plays nothing.

• Use Last Answer, Lead Status and Lead Name with Is Exactly, Contains and Starts With. Text matching ignores capital letters.
• Higher Than and Lower Than do nothing: a rule that uses either is never true, whatever the variable. Call Length is not read, so no rule can test how long the call has run.
• Last Answer tests the caller’s most recent answer, so place the node after a Listen node.
• A node with no rules always takes True. A path with no line ends the call when it is taken.

The Transfer Call node hands the live call to the destination you enter, such as your closers, and the bot then ends its part of the call. Transfer modes, notes for the closer and the Closer Hub rules are covered in live transfers and notes for your closers. This section covers what to set in the builder.

The Integration node adds one row to a Google spreadsheet when a call reaches it. Integration Type has one choice, Google Sheets. VoiceOI has no public API and no native CRM sync. Connecting your Google account is covered in Monitoring and reports, and there is a product overview at Google Sheets with VoiceOI. In the builder you set the following.

• Integration Account. System Default (Latest Integration) or a named Google Sheets connection.
• Select Spreadsheet and Select Sheet (Tab), under Google Sheets Configuration.
• Column Mapping. One box for each header in the first row of the tab. Type a value, or press + for the helper menu: Full Call Transcript, Last User Response, Lead Name (from Dialer), Lead Phone (from Dialer), Call Timestamp, or the answer of an earlier Listen or Play Audio step. Refresh Headers rereads the headers after you rename a column.
• Variables. The screen’s own help says: “Use {{Node Name}} for user responses or {{lead.name}} for lead data.” If VoiceOI cannot read the lead’s name, Lead Name becomes “Valued Customer”.

The panel also shows an older group of fields above that block (Spreadsheet ID, Sheet Name, Column Mappings with Col (A,B..)). Leave it empty: once you use Google Sheets Configuration, the older mappings are ignored. Changing Integration Account clears the spreadsheet, the tab and the Column Mapping boxes. Changing Select Spreadsheet clears the tab and the mapping boxes. Changing Select Sheet (Tab) clears the mapping boxes. Choose these first and fill the mapping last. A column is matched by its header text, ignoring capital letters, spaces and punctuation, never by letter. If no box has a value, no row is added.

Open Simulator in the sidebar. Pick a campaign under Select Campaign to Test, choose Text Simulator (Dry Run) or Browser Mic (WebSpeech API - Dry Run), and press Start Simulation. It tests the script linked to that campaign, so a script marked Unassigned cannot be tested until you pick a campaign under Assigned Campaign in Script Settings. Simulator calls are left out of your Dashboard numbers. The full Simulator guide is Voices, audio takes and the Simulator.

The Simulator is a dry run:

• It places no call. No phone line, carrier or dialer is involved, so nothing is written to a lead or to VICIdial and no transfer happens. A Transfer Call node shows the notes a live call would write.
• It does not use your recognition engine. Text mode uses what you type. Browser Mic mode uses your browser’s own speech recognition (Chrome or Edge). Check engine choices, pauses and Allow Interruption on a real call to a phone you control.
• It does not run ZIP Resolver or Matrix Router, and it does run Check Condition, which the VICIdial engine does not run. See Check Condition.
• It does write a row to your real spreadsheet when the test reaches a Google Sheets step that has no line leaving it, and it then ends the test as SALE. It writes nothing if every mapped value is empty. Point the step at a test sheet while you test.

After the Simulator, run a test call to a phone you control and check it on Call Logs: see Monitoring and reports.

• It sends the change to your bots. If a bot does not pick up a change, press Force Bot Sync in the sidebar footer, or Force bot sync on Integrations, and read the result. See the bot sync entry.
• Nothing is saved until you press it. The browser warns you if you close or reload the tab with unsaved changes. Back to List does not warn you.