DEV Community

Moisi Trungu
Moisi Trungu

Posted on Originally published at flixzone.icu

How to Configure ViciDial Script Tab — Agent Call Scripts

#devops #linux #sip #voip

How to Configure ViciDial Script Tab — Agent Call Scripts

Master the complete setup of ViciDial agent call scripts including database configuration, script creation, script-to-campaign linking, and agent-level script assignments for production call centers.

Prerequisites

Before configuring ViciDial agent call scripts, ensure you have:

  • A running ViciDial installation (version 2.9+ recommended)
  • Root or sudo access to the ViciDial server
  • MySQL/MariaDB access with credentials to the asterisk database
  • Understanding of ViciDial user roles (Admin, Manager, Agent)
  • A text editor (nano, vim, or IDE)
  • Access to the ViciDial web administration interface at /vicidial/admin.php
  • At least one active campaign already created in the system
  • Basic knowledge of HTML/plain text formatting

Understanding ViciDial Script Architecture

What Are Call Scripts?

Call scripts in ViciDial are configurable templates that agents see during active calls. They serve multiple purposes:

  • Visual guidance during customer interactions
  • Dynamic variable substitution pulling from lead records
  • Call flow logic with conditional branching
  • Integration with disposition codes and call outcomes
  • Customizable HTML/plain text rendering in the agent screen

Script Processing Flow

When an agent receives a call, ViciDial:

  1. Retrieves the assigned script from the database
  2. Parses special syntax tokens (e.g., [FIRSTNAME], [PHONE])
  3. Substitutes lead-specific variables from vicidial_list table
  4. Renders the script in the agent's browser in real-time
  5. Logs script interactions if configured

Database Structure for Scripts

Core Script Tables

ViciDial stores scripts in the asterisk database across several key tables:

-- View existing script table structure
DESCRIBE vicidial_scripts;
Enter fullscreen mode Exit fullscreen mode

Key columns in vicidial_scripts:

Column Type Purpose
script_id INT (Primary Key) Unique identifier
script_name VARCHAR(255) Display name for admin panel
script_text LONGTEXT Script content with variables
script_lang VARCHAR(10) Language code (default: en)
active ENUM('Y','N') Enable/disable script
user_group VARCHAR(20) Restrict to specific user groups
date_added TIMESTAMP Creation timestamp
date_modified TIMESTAMP Last modification timestamp

Script-Campaign Linking Table

The vicidial_campaigns table contains:

-- Relevant columns for script assignment
SELECT campaign_id, campaign_name, script_id, script_screen 
FROM vicidial_campaigns 
WHERE campaign_id = 'TESTCAMP';
Enter fullscreen mode Exit fullscreen mode
  • script_id — Links to vicidial_scripts.script_id
  • script_screen — Controls when script displays ('CALL_TIME', 'DIALER_PREVIEW', 'BOTH', 'NONE')

Creating Your First Agent Call Script

Step 1: Connect to the ViciDial Database 

mysql -u cron -p asterisk
Enter fullscreen mode Exit fullscreen mode

When prompted, enter your ViciDial database password (typically found in /etc/astguiclient.conf):

grep 'ASTERISK_PASSWD' /etc/astguiclient.conf
Enter fullscreen mode Exit fullscreen mode

Step 2: Insert a Basic Script

Create a simple inbound support script:

INSERT INTO vicidial_scripts 
(script_name, script_text, script_lang, active, user_group, date_added) 
VALUES (
  'Inbound Support - Basic',
  'Hello [FIRSTNAME], thank you for calling. What can I help you with today?

Account Info:
Customer: [FIRSTNAME] [LASTNAME]
Account: [ACCOUNTID]
Phone: [PHONE]
Email: [EMAIL]

[NOTES]

Type your notes above this line.',
  'en',
  'Y',
  'AGENTS'
);
Enter fullscreen mode Exit fullscreen mode

Verify insertion:

SELECT script_id, script_name FROM vicidial_scripts 
WHERE script_name = 'Inbound Support - Basic';
Enter fullscreen mode Exit fullscreen mode

Step 3: Create an Advanced Script with HTML Formatting

For more sophisticated formatting in the agent screen, use HTML:

INSERT INTO vicidial_scripts 
(script_name, script_text, script_lang, active, user_group) 
VALUES (
  'Outbound Sales - Advanced',
  '<div style="background-color: #f0f0f0; padding: 10px; font-family: Arial;">
    <h3>Sales Call Script</h3>

    <fieldset>
      <legend>Customer Information</legend>
      <p><strong>Name:</strong> [FIRSTNAME] [LASTNAME]</p>
      <p><strong>Phone:</strong> [PHONE]</p>
      <p><strong>Last Contact:</strong> [LASTCALLDATE]</p>
    </fieldset>

    <fieldset>
      <legend>Opening Statement</legend>
      <p>Hi [FIRSTNAME], this is [AGENTNAME] from TechCorp Solutions. 
      I''m calling because we have a special offer for valued customers like you.</p>
    </fieldset>

    <fieldset>
      <legend>Discovery Questions</legend>
      <ol>
        <li>Are you currently using a solution for [LEADTYPE]?</li>
        <li>What is your biggest pain point?</li>
        <li>When would be a good time to discuss options?</li>
      </ol>
    </fieldset>

    <fieldset style="background-color: #fff3cd; border: 1px solid #ffc107;">
      <legend>Agent Notes</legend>
      <textarea style="width: 100%; height: 80px;">
[NOTES]
      </textarea>
    </fieldset>
  </div>',
  'en',
  'Y',
  'AGENTS'
);
Enter fullscreen mode Exit fullscreen mode

ViciDial Script Variables Reference

Available Token Variables

These tokens are automatically replaced with lead data during call display:

Token Source Example
[FIRSTNAME] vicidial_list.first_name "John"
[LASTNAME] vicidial_list.last_name "Smith"
[PHONE] vicidial_list.phone_number "555-123-4567"
[EMAIL] vicidial_list.email "john@example.com"
[NOTES] vicidial_list.notes User-editable field
[LEADTYPE] vicidial_list.lead_source "Web Form"
[ACCOUNTID] vicidial_list.record_id "ACC-12345"
[AGENTNAME] vicidial_users.full_name "Sarah Johnson"
[LASTCALLDATE] vicidial_log.call_date "2024-01-15 14:32"
[LASTDISPO] vicidial_closer_log.status "CALLBACK"
[CUSTOM1] through [CUSTOM10] vicidial_list.alt_phone, field1-field10 Custom lead data

Conditional Variables (Advanced)

For conditional display based on lead data, use PHP-style logic in custom integrations. Standard ViciDial scripts use simple token replacement.

Linking Scripts to Campaigns

Via MySQL 

-- Assign script to campaign
UPDATE vicidial_campaigns 
SET script_id = (SELECT script_id FROM vicidial_scripts 
                 WHERE script_name = 'Outbound Sales - Advanced'),
    script_screen = 'CALL_TIME'
WHERE campaign_id = 'TESTCAMP';

-- Verify assignment
SELECT campaign_id, campaign_name, script_id 
FROM vicidial_campaigns 
WHERE campaign_id = 'TESTCAMP';
Enter fullscreen mode Exit fullscreen mode

Via Web Admin Interface

  1. Log into /vicidial/admin.php as admin user
  2. Navigate: Campaigns → Click campaign name
  3. Scroll to Script section
  4. Select script from dropdown: Outbound Sales - Advanced
  5. Set Script Screen option:
    • CALL_TIME — Show during active call only
    • DIALER_PREVIEW — Show in preview mode before dialing
    • BOTH — Show in both modes
    • NONE — Disable script display
  6. Click SUBMIT

Agent-Level Script Overrides

Override Script Per User

Some ViciDial configurations allow per-user script overrides. Store these in the vicidial_users table:

-- Check if user table has script_id column
SHOW COLUMNS FROM vicidial_users LIKE 'script%';

-- If column exists, assign script to specific user
UPDATE vicidial_users 
SET script_override = (SELECT script_id FROM vicidial_scripts 
                       WHERE script_name = 'Inbound Support - Basic')
WHERE user = 'agent1';
Enter fullscreen mode Exit fullscreen mode

If the column doesn't exist, this functionality may not be enabled in your version. Typically, scripts are assigned at the campaign level.

Script Management Operations

Backup Scripts

Export all scripts before modifications:

mysqldump -u cron -p asterisk vicidial_scripts > /backup/vicidial_scripts_$(date +%Y%m%d).sql
Enter fullscreen mode Exit fullscreen mode

Restore if needed:

mysql -u cron -p asterisk < /backup/vicidial_scripts_20240115.sql
Enter fullscreen mode Exit fullscreen mode

List All Active Scripts 

SELECT script_id, script_name, active, user_group, date_modified 
FROM vicidial_scripts 
WHERE active = 'Y' 
ORDER BY script_name;
Enter fullscreen mode Exit fullscreen mode

Bulk Update Scripts 

-- Deactivate all old scripts
UPDATE vicidial_scripts 
SET active = 'N' 
WHERE date_modified < DATE_SUB(NOW(), INTERVAL 90 DAY) 
AND script_name LIKE '%OLD%';

-- Check impact before committing
SELECT COUNT(*) FROM vicidial_scripts 
WHERE date_modified < DATE_SUB(NOW(), INTERVAL 90 DAY) 
AND script_name LIKE '%OLD%';
Enter fullscreen mode Exit fullscreen mode

Clone/Duplicate a Script 

-- Create new version of existing script
INSERT INTO vicidial_scripts (script_name, script_text, script_lang, active, user_group)
SELECT 
  CONCAT(script_name, ' - v2'), 
  script_text, 
  script_lang, 
  'Y', 
  user_group
FROM vicidial_scripts 
WHERE script_id = 5;
Enter fullscreen mode Exit fullscreen mode

Script Display Settings in Asterisk Configuration

Extension Configuration

ViciDial's Asterisk dial plan reads script display settings from extensions configuration:

; /etc/asterisk/extensions-vicidial.conf excerpt
; Script display controlled by campaign configuration, 
; but can be overridden in dial plan logic

exten => _9X.,1,AGI(agi://127.0.0.1:4573/?stagePROVIDED|${EXTEN})
exten => _9X.,n,Hangup()
Enter fullscreen mode Exit fullscreen mode

The AGI handler communicates script assignments to the web interface via WebSocket or AJAX polling.

Testing Scripts in Production

View Script as Agent Would See It

  1. Log into /agc/vicidial.php as test agent
  2. Place a test call to campaign with script assigned
  3. Script should display in right panel during call
  4. Verify variable substitution (names, phone numbers appear correctly)

Check Script Logs 

tail -f /var/log/asterisk/messages | grep -i script
Enter fullscreen mode Exit fullscreen mode

Test Variable Substitution

Create a test lead record:

INSERT INTO vicidial_list 
(campaign_id, phone_number, first_name, last_name, email, notes, status, date_added) 
VALUES (
  'TESTCAMP',
  '5551234567',
  'TestAgent',
  'Script',
  'test@example.com',
  'This is a test lead for script validation',
  'NEW',
  NOW()
);
Enter fullscreen mode Exit fullscreen mode

Call the number and verify all tokens show correctly in the script.

Performance Considerations

Script Size Optimization

Large scripts (>50 KB) may slow browser rendering. Optimize:

-- Check script sizes
SELECT script_id, script_name, LENGTH(script_text) as size_bytes 
FROM vicidial_scripts 
ORDER BY size_bytes DESC;
Enter fullscreen mode Exit fullscreen mode

If scripts exceed 50 KB:

  • Move verbose instructions to external documentation
  • Use collapsed HTML sections with toggle buttons
  • Limit CSS inline styling (use class references instead)

Database Query Efficiency

ViciDial caches script data. To force refresh:

# Restart ViciDial daemon to clear cache
systemctl restart vicidial
Enter fullscreen mode Exit fullscreen mode

Or clear specific cache entries:

# If Redis is enabled
redis-cli FLUSHDB  # WARNING: Clears all cache
Enter fullscreen mode Exit fullscreen mode

Integration with Disposition Codes

Scripts often reference disposition codes used after calls. Link them logically:

-- View available dispositions
SELECT disposition_id, disposition, active 
FROM vicidial_statuses 
WHERE campaign_id = 'TESTCAMP' 
AND active = 'Y';
Enter fullscreen mode Exit fullscreen mode

Create script sections matching dispositions:

INSERT INTO vicidial_scripts 
(script_name, script_text, script_lang, active, user_group) 
VALUES (
  'Inbound Routing',
  '<h2>Call Disposition Guide</h2>

  <p><strong>SALE:</strong> Customer agreed to purchase</p>
  <p><strong>CALLBACK:</strong> Customer wants follow-up call</p>
  <p><strong>NOTINTERESTED:</strong> Customer declined offer</p>
  <p><strong>DONOTCALL:</strong> Customer requested removal from list</p>

  <p><em>Select appropriate disposition after call ends.</em></p>',
  'en',
  'Y',
  'AGENTS'
);
Enter fullscreen mode Exit fullscreen mode

Multi-Language Script Support

Create Scripts in Multiple Languages 

-- English version
INSERT INTO vicidial_scripts (script_name, script_text, script_lang, active) 
VALUES ('Welcome Script', 'Hello [FIRSTNAME], welcome!', 'en', 'Y');

-- Spanish version
INSERT INTO vicidial_scripts (script_name, script_text, script_lang, active) 
VALUES ('Welcome Script', '¡Hola [FIRSTNAME], bienvenido!', 'es', 'Y');

-- French version
INSERT INTO vicidial_scripts (script_name, script_text, script_lang, active) 
VALUES ('Welcome Script', 'Bonjour [FIRSTNAME], bienvenue!', 'fr', 'Y');
Enter fullscreen mode Exit fullscreen mode

The campaign or user language setting determines which version displays.

Advanced: Custom Script Variables via AGI

For variables beyond standard tokens, modify the ViciDial AGI script:

# Locate AGI handler
find /usr -name 'agi*.agi' 2>/dev/null
Enter fullscreen mode Exit fullscreen mode

Edit /var/lib/asterisk/agi-bin/vicidial_custom.agi (or similar):

#!/usr/bin/perl
# Custom variable handler

# Standard input from Asterisk
while (<STDIN>) {
  chomp;
  last unless length($_);

  if (/^agi_request:\s+(.*)/) {
    $ENV{request} = $1;
  }
}

# Add custom variable processing
$lead_id = $ENV{agi_arg_1};

# Query additional data
my $query = "SELECT custom_field FROM vicidial_list WHERE list_id = $lead_id";
my $result = $dbh->selectrow_array($query);

# Send back to Asterisk
print "SET VARIABLE CUSTOMVAR $result\n";
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

Script Not Displaying During Calls

Symptom: Agent calls connect but script panel shows blank or error.

Diagnosis Steps:

  1. Verify script_id is correctly assigned: 
SELECT campaign_id, script_id FROM vicidial_campaigns 
WHERE campaign_id = 'TESTCAMP';
Enter fullscreen mode Exit fullscreen mode
  1. Confirm script exists and is active: 
SELECT script_id, script_name, active FROM vicidial_scripts 
WHERE script_id = (SELECT script_id FROM vicidial_campaigns 
                   WHERE campaign_id = 'TESTCAMP');
Enter fullscreen mode Exit fullscreen mode
  1. Check Asterisk logs for AGI errors: 
grep -i "agi\|script" /var/log/asterisk/messages | tail -20
Enter fullscreen mode Exit fullscreen mode

Solution:

  • Ensure script_id foreign key references valid script
  • Set script active = 'Y'
  • Verify campaign has script_screen != 'NONE'
  • Restart ViciDial service: systemctl restart vicidial

Variables Not Substituting

Symptom: Script shows literal tokens like [FIRSTNAME] instead of actual names.

Diagnosis:

-- Check if lead has data in those columns
SELECT first_name, last_name, email FROM vicidial_list 
WHERE phone_number = '5551234567' LIMIT 1;
Enter fullscreen mode Exit fullscreen mode

Solution:

  • Populate missing columns in vicidial_list before call
  • Use valid token names from the reference table above
  • Check for typos in token names (case-sensitive in some versions)
  • Verify lead_id is correctly passed to script parser

Script Rendering Issues (HTML Scripts)

Symptom: HTML script displays as raw markup or styling is broken.

Diagnosis:

  1. Test script in a text editor for syntax errors: 
# Escape single quotes in SQL when testing locally
mysql -u cron -p asterisk -e "SELECT script_text FROM vicidial_scripts WHERE script_id = 5\G"
Enter fullscreen mode Exit fullscreen mode
  1. Check browser console for JavaScript errors: Press F12 in agent screen

Solution:

  • Close all HTML tags properly
  • Escape single quotes in SQL as '' (double apostrophe)
  • Avoid inline event handlers (onclick, onload) — use CSS/JS in agent interface
  • Test with simple HTML first, then add complexity

Performance Degradation with Large Scripts

Symptom: Agent screen becomes slow when script loads.

Diagnosis:

# Monitor browser performance
# In agent screen, press F12 → Network tab → refresh
# Look for script load times > 2 seconds
Enter fullscreen mode Exit fullscreen mode

Solution:

  • Compress script text (remove extra whitespace)
  • Limit script size to <30 KB
  • Use lazy-loading for sections with JavaScript
  • Cache scripts on agent machine with Cache-Control headers

Scripts Reverting After Restart

Symptom: Script changes work temporarily but disappear after reboot.

Diagnosis:

# Check if changes were committed to database
mysql -u cron -p asterisk -e "SELECT script_id, date_modified FROM vicidial_scripts WHERE script_name = 'Test Script';"

# Check if backup/restore is running
ps aux | grep -i backup
Enter fullscreen mode Exit fullscreen mode

Solution:

  • Ensure MySQL is configured to persist data (not running in-memory)
  • Verify /var/lib/mysql is on persistent storage
  • Disable auto-restore scripts if they exist in cron jobs
  • Manually flush/commit database after changes: 
mysql -u cron -p asterisk -e "FLUSH TABLES WITH READ LOCK; UNLOCK TABLES;"
Enter fullscreen mode Exit fullscreen mode

Agent Sees Wrong Script

Symptom: Agent on campaign A sees script from campaign B.

Diagnosis:

-- Check what script is assigned to agent's current campaign
SELECT c.campaign_id, c.script_id, s.script_name 
FROM vicidial_users u
JOIN vicidial_user_campaigns uc ON u.user_id = uc.user_id
JOIN vicidial_campaigns c ON uc.campaign_id = c.campaign_id
JOIN vicidial_scripts s ON c.script_id = s.script_id
WHERE u.user = 'agent1';
Enter fullscreen mode Exit fullscreen mode

Solution:

  • Verify campaign assignment in admin panel
  • Clear browser cache: Ctrl+Shift+Delete
  • Reload agent screen: Ctrl+F5
  • Check for conflicting user-level script overrides: 
SELECT user, script_override FROM vicidial_users WHERE user = 'agent1';
Enter fullscreen mode Exit fullscreen mode

Summary

Configuring ViciDial agent call scripts involves:

  1. Database Design — Understanding the vicidial_scripts and campaign linking tables
  2. Script Creation — Writing scripts with token variables and HTML formatting
  3. Campaign Assignment — Linking scripts via MySQL or web admin interface
  4. Variable Substitution — Using tokens like [FIRSTNAME], [PHONE] to inject lead data
  5. Testing — Validating script display and variable substitution in live calls
  6. Optimization — Managing script size and performance for production environments
  7. Troubleshooting — Diagnosing common issues with display, variables, and persistence

Production best practices:

  • Always backup scripts before bulk updates using mysqldump
  • Version control by including version numbers in script names
  • Keep scripts under 30 KB for optimal browser performance
  • Test in staging before deploying to live campaigns
  • Monitor logs (/var/log/asterisk/messages) for AGI-related errors
  • Document token usage for your team to avoid confusion
  • Use HTML formatting sparingly — prioritize readability over aesthetics
  • Schedule reviews quarterly to archive outdated scripts and improve active ones

With scripts properly configured, your agents will have consistent, data-driven guidance during every customer interaction, improving call quality and compliance across your contact center operations.

Top comments (0)