DEV Community: Moisi Trungu

How to Use ViciDial Admin Utilities — Archive, Cleanup & Maintenance

Moisi Trungu — Tue, 18 Aug 2026 03:30:02 +0000

How to Use ViciDial Admin Utilities — Archive, Cleanup & Maintenance

Master production ViciDial database maintenance, call log archival, and system cleanup to optimize performance and prevent disk space exhaustion.

Introduction

ViciDial deployments accumulate data quickly. A moderately active call center logs millions of records monthly across vicidial_log, vicidial_closer_log, vicidial_carrier_log, and related tables. Without systematic archival and cleanup, your MySQL database bloats, queries slow, backups consume excessive storage, and the web interface becomes unresponsive.

This tutorial covers the actual administrative utilities shipped with ViciDial, real-world maintenance strategies, and the exact commands your production environment needs. Whether you're running a 10-agent shop or a 500-seat operation, improper maintenance will eventually force an emergency cleanup window that disrupts service.

Prerequisites

Before proceeding, you need:

ViciDial installed and running on Linux (Debian/CentOS tested)
Root or sudo access to the server
MySQL/MariaDB admin credentials with access to the asterisk database
Cron capability to schedule regular maintenance tasks
Backup strategy already in place (test your backups before archiving)
Shell access to /usr/share/astguiclient/ (standard ViciDial CLI location)
Understanding of your data retention policy (how long to keep records on-disk vs. archived)

Understanding ViciDial Data Architecture

ViciDial stores call records in distinct tables, each serving different purposes:

Table	Purpose	Growth Rate	Typical Retention
`vicidial_log`	Core call records	Highest (1M+/month)	180-365 days
`vicidial_closer_log`	Agent disposition/notes	High (1M+/month)	180-365 days
`vicidial_carrier_log`	SIP carrier statistics	Medium (100K+/month)	90-180 days
`vicidial_campaign_log`	Campaign events	Low-Medium	365+ days
`vicidial_list_log`	List/lead tracking	Medium	90-365 days
`vicidial_statistic_log`	Hourly statistics	Low	365+ days
`vicidial_api_log`	API calls	Medium	90 days

Understand your call volume before designing a maintenance schedule. A 500-seat operation might generate 500K calls/day; a 10-seat operation 10K/day.

Section 1: Built-In Archive Utilities

Using ARCHIVE_MANAGER.pl

ViciDial ships with ARCHIVE_MANAGER.pl, a Perl script designed to move old call records to archive tables. This is the official, supported method for archival.

Location: /usr/share/astguiclient/ARCHIVE_MANAGER.pl

What it does:

Copies records older than a configurable threshold to _archive tables
Optionally deletes original records after verification
Generates detailed logs of what was archived
Respects foreign key constraints and referential integrity

Basic syntax:

/usr/share/astguiclient/ARCHIVE_MANAGER.pl \
  --archiveolderthandays 180 \
  --deletearchived 1 \
  --logfile /var/log/vicidial/archive.log

Parameters explained:

--archiveolderthandays N: Archive records older than N days (required)
--deletearchived 1|0: Delete original records after archiving (1=yes, 0=no)
--logfile PATH: Write operation log here (creates directory if needed)
--database asterisk: Specify database name (default: asterisk)
--host localhost: Database host (default: localhost)
--user vicidialuser: Database user (required for auth)
--pass PASSWORD: Database password (security risk; prefer .my.cnf)

Real-world example with .my.cnf:

Create /root/.my.cnf with restricted permissions:

[client]
user=vicidialuser
password=your_secure_password
host=localhost

Set permissions:

chmod 600 /root/.my.cnf

Then run without exposing password:

/usr/share/astguiclient/ARCHIVE_MANAGER.pl \
  --archiveolderthandays 180 \
  --deletearchived 1 \
  --logfile /var/log/vicidial/archive.log

Understanding Archive Table Creation

When you first run ARCHIVE_MANAGER.pl, it creates _archive tables automatically:

CREATE TABLE vicidial_log_archive LIKE vicidial_log;
CREATE TABLE vicidial_closer_log_archive LIKE vicidial_closer_log;

Verify archive tables exist:

mysql -u vicidialuser -p asterisk -e "SHOW TABLES LIKE '%archive%';"

Expected output:

+--------------------------------------+
| Tables_in_asterisk (%archive%)       |
+--------------------------------------+
| vicidial_carrier_log_archive         |
| vicidial_closer_log_archive          |
| vicidial_list_log_archive            |
| vicidial_log_archive                 |
+--------------------------------------+

Archival Monitoring & Verification

After running archival, check the log file:

tail -100 /var/log/vicidial/archive.log

Look for:

2024-01-15 02:30:45 - Starting ARCHIVE_MANAGER
2024-01-15 02:31:12 - vicidial_log: Copying 1,245,000 records dated before 2023-08-17
2024-01-15 02:32:40 - vicidial_log: Deleting 1,245,000 archived records
2024-01-15 02:33:01 - vicidial_closer_log: Copying 987,000 records dated before 2023-08-17
2024-01-15 02:34:15 - vicidial_closer_log: Deleting 987,000 archived records
2024-01-15 02:35:00 - Archive complete: 3.2M records archived

Verify archive count matches original deletion:

mysql -u vicidialuser -p asterisk -e \
  "SELECT COUNT(*) as 'vicidial_log_archive' FROM vicidial_log_archive;"

Section 2: Database Cleanup Operations

Truncating Inactive Campaign Logs

Campaign logs can accumulate quickly with many short-duration campaigns. Archive first, then truncate if safe:

# Archive 90-day-old campaign logs
/usr/share/astguiclient/ARCHIVE_MANAGER.pl \
  --archiveolderthandays 90 \
  --deletearchived 1

# Then safely truncate extremely old archived logs (optional backup first)
mysqldump -u vicidialuser -p asterisk vicidial_campaign_log_archive > \
  /backup/campaign_archive_$(date +%Y%m%d).sql

Clearing Temporary & Log Tables

ViciDial creates temporary tables during operation. These don't need long-term retention:

mysql -u vicidialuser -p asterisk << 'EOF'
-- Delete old queue logs (safe to clear, not critical)
DELETE FROM vicidial_api_log WHERE call_date < DATE_SUB(NOW(), INTERVAL 30 DAY);

-- Optimize tables after large deletions
OPTIMIZE TABLE vicidial_log;
OPTIMIZE TABLE vicidial_closer_log;
OPTIMIZE TABLE vicidial_carrier_log;
EOF

Removing Orphaned Records

Sometimes records remain after campaigns end. Find and remove them safely:

-- Find vicidial_log entries without matching campaigns (read-only check first)
SELECT COUNT(*) FROM vicidial_log vl
WHERE NOT EXISTS (
  SELECT 1 FROM vicidial_campaigns vc 
  WHERE vc.campaign_id = vl.campaign_id
) AND vl.call_date < DATE_SUB(NOW(), INTERVAL 180 DAY);

-- If count is acceptable, delete (with caution!)
DELETE FROM vicidial_log WHERE NOT EXISTS (
  SELECT 1 FROM vicidial_campaigns vc 
  WHERE vc.campaign_id = vicidial_log.campaign_id
) AND vicidial_log.call_date < DATE_SUB(NOW(), INTERVAL 180 DAY);

Removing Test Records

Development testing leaves junk records. Clean them with:

mysql -u vicidialuser -p asterisk << 'EOF'
-- Remove test campaigns and their logs
DELETE vl FROM vicidial_log vl
INNER JOIN vicidial_campaigns vc ON vl.campaign_id = vc.campaign_id
WHERE vc.campaign_name LIKE 'TEST_%'
  AND vl.call_date < DATE_SUB(NOW(), INTERVAL 30 DAY);

DELETE vcl FROM vicidial_closer_log vcl
INNER JOIN vicidial_campaigns vc ON vcl.campaign_id = vc.campaign_id
WHERE vc.campaign_name LIKE 'TEST_%'
  AND vcl.call_date < DATE_SUB(NOW(), INTERVAL 30 DAY);

-- Delete orphaned test campaigns
DELETE FROM vicidial_campaigns WHERE campaign_name LIKE 'TEST_%';
EOF

Section 3: Performance Optimization After Cleanup

After major deletions or archival, optimize the database structure:

Table Optimization

mysql -u vicidialuser -p asterisk << 'EOF'
-- Optimize all main tables after archival
OPTIMIZE TABLE vicidial_log;
OPTIMIZE TABLE vicidial_closer_log;
OPTIMIZE TABLE vicidial_carrier_log;
OPTIMIZE TABLE vicidial_campaign_log;
OPTIMIZE TABLE vicidial_list_log;
OPTIMIZE TABLE vicidial_statistic_log;

-- Check table integrity
CHECK TABLE vicidial_log;
CHECK TABLE vicidial_closer_log;
EOF

Note: OPTIMIZE TABLE locks the table briefly. Schedule during maintenance windows or use OPTIMIZE TABLE ... LOCK=NONE (MySQL 8.0+).

Rebuilding Indexes

After major deletes, indexes may become fragmented:

# Rebuild primary indexes on key tables
mysql -u vicidialuser -p asterisk << 'EOF'
-- Recreate indexes for faster queries post-cleanup
ALTER TABLE vicidial_log ENGINE=InnoDB;
ALTER TABLE vicidial_closer_log ENGINE=InnoDB;
ALTER TABLE vicidial_carrier_log ENGINE=InnoDB;
EOF

Verifying Table Status

# Check how much space you reclaimed
mysql -u vicidialuser -p asterisk << 'EOF'
SELECT 
  TABLE_NAME,
  ROUND(((DATA_LENGTH + INDEX_LENGTH) / 1024 / 1024 / 1024), 2) as size_gb
FROM information_schema.TABLES
WHERE TABLE_SCHEMA = 'asterisk'
  AND TABLE_NAME IN ('vicidial_log', 'vicidial_closer_log', 'vicidial_carrier_log')
ORDER BY (DATA_LENGTH + INDEX_LENGTH) DESC;
EOF

Sample output:

+---------------------+---------+
| TABLE_NAME          | size_gb |
+---------------------+---------+
| vicidial_log        | 45.23   |
| vicidial_closer_log | 38.91   |
| vicidial_carrier_log| 12.34   |
+---------------------+---------+

Section 4: Scheduling Automated Maintenance

Creating a Maintenance Cron Job

Create /usr/local/bin/vicidial-maintenance.sh:

#!/bin/bash

# ViciDial Automated Maintenance Script
# Run daily at 2 AM via cron

LOG_DIR="/var/log/vicidial"
ARCHIVE_LOG="$LOG_DIR/archive_$(date +%Y%m%d_%H%M%S).log"
MAINT_LOG="$LOG_DIR/maintenance_$(date +%Y%m%d_%H%M%S).log"

mkdir -p "$LOG_DIR"

# Function to log messages
log_message() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$MAINT_LOG"
}

log_message "=== ViciDial Maintenance Started ==="

# Step 1: Archive old records (older than 180 days)
log_message "Starting archival of records older than 180 days..."
/usr/share/astguiclient/ARCHIVE_MANAGER.pl \
  --archiveolderthandays 180 \
  --deletearchived 1 \
  --logfile "$ARCHIVE_LOG" >> "$MAINT_LOG" 2>&1

if [ $? -eq 0 ]; then
    log_message "Archival completed successfully"
else
    log_message "WARNING: Archival returned non-zero exit code"
fi

# Step 2: Clean up API logs older than 30 days
log_message "Cleaning API logs older than 30 days..."
mysql -u vicidialuser -p"$(cat /root/.mysql_pass)" asterisk << 'SQLEOF' >> "$MAINT_LOG" 2>&1
DELETE FROM vicidial_api_log WHERE call_date < DATE_SUB(NOW(), INTERVAL 30 DAY);
DELETE FROM vicidial_log_archive WHERE call_date < DATE_SUB(NOW(), INTERVAL 365 DAY);
SQLEOF

log_message "API log cleanup completed"

# Step 3: Optimize tables
log_message "Optimizing tables..."
mysql -u vicidialuser -p"$(cat /root/.mysql_pass)" asterisk << 'SQLEOF' >> "$MAINT_LOG" 2>&1
OPTIMIZE TABLE vicidial_log;
OPTIMIZE TABLE vicidial_closer_log;
OPTIMIZE TABLE vicidial_carrier_log;
SQLEOF

log_message "Table optimization completed"

# Step 4: Check database integrity
log_message "Running database integrity check..."
mysql -u vicidialuser -p"$(cat /root/.mysql_pass)" asterisk << 'SQLEOF' >> "$MAINT_LOG" 2>&1
CHECK TABLE vicidial_log;
CHECK TABLE vicidial_closer_log;
SQLEOF

log_message "=== ViciDial Maintenance Completed ==="

Make it executable:

chmod 755 /usr/local/bin/vicidial-maintenance.sh

Add to Crontab

# Edit root crontab
crontab -e

Add:

# Run ViciDial maintenance daily at 2 AM (off-hours)
0 2 * * * /usr/local/bin/vicidial-maintenance.sh

Alternative: Weekly schedule:

# Run weekly on Sunday at 2 AM for larger operations
0 2 * * 0 /usr/local/bin/vicidial-maintenance.sh

Monitoring Cron Execution

Check if cron job ran successfully:

grep vicidial-maintenance /var/log/syslog
# or
grep vicidial-maintenance /var/log/cron

Review maintenance logs:

ls -lh /var/log/vicidial/maintenance_*.log
tail -50 /var/log/vicidial/maintenance_*.log | less

Section 5: Manual Admin Utilities Reference

Using astguiclient Command-Line Tools

ViciDial ships with several command-line utilities in /usr/share/astguiclient/:

get_asterisk_status.pl

Check overall Asterisk health:

/usr/share/astguiclient/get_asterisk_status.pl

Output:

Asterisk Version: 18.15.0
Uptime: 45 days, 12:34:56
Active Calls: 23
Channels: 156

get_call_records.pl

Export call records for external analysis:

/usr/share/astguiclient/get_call_records.pl \
  --start-date "2024-01-01" \
  --end-date "2024-01-31" \
  --campaign "CAMPAIGN_001" \
  --output-file /tmp/jan_records.csv

Database Backup & Restore

Backup the entire asterisk database:

mysqldump -u vicidialuser -p asterisk > \
  /backup/asterisk_$(date +%Y%m%d_%H%M%S).sql

Backup only vicidial_log:

mysqldump -u vicidialuser -p asterisk vicidial_log > \
  /backup/vicidial_log_$(date +%Y%m%d).sql.gz

Restore from backup:

mysql -u vicidialuser -p asterisk < /backup/asterisk_20240115_020000.sql

Section 6: Performance Monitoring & Capacity Planning

Monitor Disk Space

# Check MySQL data directory
du -sh /var/lib/mysql/asterisk/

# Check overall filesystem
df -h /var/lib/mysql/

Expected output:

Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1       500G  450G   50G  90% /

Alert threshold: When database exceeds 85% of available space, schedule immediate archival.

Query Performance Baseline

Before and after maintenance, establish performance metrics:

mysql -u vicidialuser -p asterisk << 'EOF'
-- Query latency check
SELECT 
  DATE_FORMAT(call_date, '%Y-%m-%d') as date,
  COUNT(*) as record_count
FROM vicidial_log
GROUP BY DATE_FORMAT(call_date, '%Y-%m-%d')
ORDER BY call_date DESC
LIMIT 30;
EOF

Compare query execution time before/after archival using:

mysql -u vicidialuser -p asterisk -v -v << 'EOF'
SELECT COUNT(*) FROM vicidial_log WHERE call_date > DATE_SUB(NOW(), INTERVAL 30 DAY);
EOF

Database Size Trend

Create a monitoring script that tracks growth:

#!/bin/bash

MONITOR_LOG="/var/log/vicidial/db_size_trend.log"

{
    echo "$(date '+%Y-%m-%d %H:%M:%S')"
    mysql -u vicidialuser -p asterisk -N << 'EOF'
SELECT 
    TABLE_NAME,
    ROUND(((DATA_LENGTH + INDEX_LENGTH) / 1024 / 1024), 2) as size_mb
FROM information_schema.TABLES
WHERE TABLE_SCHEMA = 'asterisk'
ORDER BY (DATA_LENGTH + INDEX_LENGTH) DESC;
EOF
    echo "---"
} >> "$MONITOR_LOG"

Add to crontab to run weekly:

0 3 * * 0 /usr/local/bin/monitor_db_size.sh

Section 7: Common Maintenance Scenarios

Scenario 1: Database Bloat (90% Disk Full)

Situation: Your 500GB drive is 90% full, ViciDial is slow, users complaining.

Action plan:

# 1. Check current size
du -sh /var/lib/mysql/asterisk/

# 2. Archive aggressively
/usr/share/astguiclient/ARCHIVE_MANAGER.pl \
  --archiveolderthandays 90 \
  --deletearchived 1

# 3. Clean orphaned records
mysql -u vicidialuser -p asterisk << 'EOF'
DELETE FROM vicidial_log WHERE call_date < DATE_SUB(NOW(), INTERVAL 120 DAY);
DELETE FROM vicidial_closer_log WHERE call_date < DATE_SUB(NOW(), INTERVAL 120 DAY);
OPTIMIZE TABLE vicidial_log;
OPTIMIZE TABLE vicidial_closer_log;
EOF

# 4. Verify space reclaimed
du -sh /var/lib/mysql/asterisk/

Expected result: 200-300GB freed, database responsive again.

Scenario 2: Query Timeouts

Situation: Agent screen takes 5+ seconds to load, database CPU at 100%.

Action:

# 1. Identify slow queries
mysql -u vicidialuser -p asterisk << 'EOF'
SELECT * FROM vicidial_log LIMIT 5;
EOF
# Time this—if > 2 seconds, table is too large

# 2. Archive older records
/usr/share/astguiclient/ARCHIVE_MANAGER.pl \
  --archiveolderthandays 180 \
  --deletearchived 1

# 3. Rebuild indexes
ALTER TABLE vicidial_log ENGINE=InnoDB;
ALTER TABLE vicidial_closer_log ENGINE=InnoDB;

# 4. Check again
SELECT * FROM vicidial_log LIMIT 5;
# Should be < 1 second now
EOF

Scenario 3: Unexpected Disk Full

Situation: Cron job failed, disk suddenly 100% full, MySQL won't start.

Emergency recovery:

# 1. Check what's consuming space
du -sh /var/lib/mysql/* | sort -rh | head -10

# 2. Manually archive highest-priority tables
# STOP ViciDial first to avoid conflicts
systemctl stop asterisk
systemctl stop php-fpm  # or apache2

# 3. Run archive with delete
/usr/share/astguiclient/ARCHIVE_MANAGER.pl \
  --archiveolderthandays 30 \
  --deletearchived 1

# 4. Restart services
systemctl start asterisk
systemctl start php-fpm

Section 8: Troubleshooting

ARCHIVE_MANAGER.pl Fails with "Permission Denied"

Symptom:

Error: Cannot access database (Permission denied)

Solution:

# 1. Check MySQL credentials
mysql -u vicidialuser -p asterisk -e "SELECT 1;"

# 2. Verify .my.cnf exists and is readable
ls -l /root/.my.cnf

# 3. Ensure file permissions
chmod 600 /root/.my.cnf

# 4. Test script directly
perl -e 'use DBI; print "Perl DBI installed\n";'

# 5. Run with explicit credentials
/usr/share/astguiclient/ARCHIVE_MANAGER.pl \
  --archiveolderthandays 180 \
  --deletearchived 1 \
  --user vicidialuser \
  --pass 'your_password'

Archive Tables Not Created

Symptom:

CREATE TABLE vicidial_log_archive... ERROR 1050: Table already exists

Solution:

# Check if archive tables exist
mysql -u vicidialuser -p asterisk -e \
  "SHOW TABLES LIKE '%archive%';"

# If not present, create manually
mysql -u vicidialuser -p asterisk << 'EOF'
CREATE TABLE vicidial_log_archive LIKE vicidial_log;
CREATE TABLE vicidial_closer_log_archive LIKE vicidial_closer_log;
EOF

MySQL Runs Out of Disk Space During Optimization

Symptom:

OPTIMIZE TABLE completed: Disk quota exceeded

Solution:

# OPTIMIZE TABLE requires free space equal to table size
# If table is 100GB, need 100GB free

# Option 1: Archive more records first
/usr/share/astguiclient/ARCHIVE_MANAGER.pl \
  --archiveolderthandays 60 \
  --deletearchived 1

# Option 2: Use OPTIMIZE with LOCK=NONE (MySQL 8.0+)
mysql -u vicidialuser -p asterisk << 'EOF'
ALTER TABLE vicidial_log ENGINE=InnoDB ALGORITHM=INPLACE, LOCK=NONE;
EOF

# Option 3: Extend MySQL partition
# This requires disk admin work, expand /var/lib/mysql mount
lvextend -L +200G /dev/mapper/vg-mysql
resize2fs /dev/mapper/vg-mysql

Cron Job Not Executing

Symptom: Maintenance log doesn't exist, files not archived.

Diagnosis:

# Check if cron is running
systemctl status cron
# or
systemctl status crond

# Check cron logs
tail -20 /var/log/syslog | grep CRON

# Verify crontab syntax
crontab -l
# Should show your job

# Test cron environment
env -i HOME=$HOME /bin/sh -c 'cd ~ && /usr/local/bin/vicidial-maintenance.sh'

# Check if cron user has permissions
sudo -u root crontab -l

Archive Inconsistency (Archive Count < Original Count)

Symptom:

vicidial_log: Supposed to copy 1,245,000 records
vicidial_log_archive: Only contains 1,200,000 records

Diagnosis:

# Check for foreign key constraint failures
mysql -u vicidialuser -p asterisk << 'EOF'
-- Look for records missing from related tables
SELECT COUNT(*) as orphaned_count FROM vicidial_log vl
WHERE NOT EXISTS (
  SELECT 1 FROM vicidial_campaigns vc WHERE vc.campaign_id = vl.campaign_id
);
EOF

# Solution: Run with --deletearchived 0 first (no delete)
/usr/share/astguiclient/ARCHIVE_MANAGER.pl \
  --archiveolderthandays 180 \
  --deletearchived 0

# Then investigate, fix orphaned records, try again

Section 9: Best Practices & Recommendations

Retention Policy Template

Define your retention policy upfront:

Record Type	Production Retention	Archive Retention	Delete After
vicidial_log	180 days	365 days	545 days
vicidial_closer_log	180 days	365 days	545 days
vicidial_carrier_log	90 days	180 days	270 days
vicidial_api_log	30 days	None	30 days
vicidial_campaign_log	365 days	2 years	Never

Document this in your runbook.

Backup Before Archival

Never skip backups:

# Before any major cleanup, backup
mysqldump -u vicidialuser -p asterisk > \
  /backup/pre-archive-$(date +%Y%m%d_%H%M%S).sql

# Verify backup integrity
mysql -u vicidialuser -p asterisk < \
  /backup/pre-archive-20240115_020000.sql 2>&1 | grep -i error

Monitor Active Calls During Maintenance

Never archive during peak hours:

# Check current active calls
asterisk -rx "core show channels"

# Example safe window output:
# Channel          Bridge              Exten   Pri   State (ms)     Since
# SIP/107-0000     (None)              s       1     Up    (5)       2024-01-15 14:23:14

Wait until < 10 active calls before starting maintenance.

Document Your Maintenance Schedule

Create /etc/vicidial/MAINTENANCE_SCHEDULE.md:

# ViciDial Maintenance Schedule

## Daily (2 AM)
- Archive records older than 180 days
- Delete archived API logs older than 30 days
- Optimize main tables
- Check database integrity

## Weekly (Sunday 3 AM)
- Full database backup
- Verify backup integrity
- Monitor database growth trend

## Monthly (1st of month, 4 AM)
- Archive records older than 90 days  
- Clean orphaned/test records
- Rebuild indexes
- Generate capacity report

## Quarterly
- Review retention policy
- Plan capacity expansion if needed

Summary

ViciDial's built-in admin utilities—primarily ARCHIVE_MANAGER.pl—provide a reliable path to production-grade database maintenance. Implementing systematic archival, cleanup, and optimization prevents the performance degradation and storage emergencies that plague unmaintained ViciDial deployments.

Key takeaways:

Archive regularly using ARCHIVE_MANAGER.pl with a 180-day threshold
Automate via cron to ensure consistent execution; don't rely on manual intervention
Monitor database size monthly and establish growth baselines
Test backups before every major archival operation
Schedule maintenance windows during off-hours when call volume is low
Optimize tables after large deletions to reclaim disk space
Document your policy so future admins understand your retention strategy
Plan for growth and extend storage before hitting 85% capacity

With disciplined maintenance, your ViciDial system will remain responsive, your backups manageable, and your infrastructure stable for years of reliable call center operations.

How to Configure ViciDial Answering Machine Detection (AMD)

Moisi Trungu — Mon, 17 Aug 2026 03:30:03 +0000

How to Configure ViciDial Answering Machine Detection (AMD)

Master Asterisk's built-in AMD engine and implement production-grade answering machine detection in ViciDial to increase agent productivity, reduce wasted call time, and improve contact rates on outbound campaigns.

Prerequisites

Before configuring AMD in ViciDial, ensure you have:

ViciDial 2.12 or higher installed and running
Asterisk 11+ (16+ recommended for better AMD performance)
Root or sudo access to your ViciDial server
Database access to the asterisk database
Understanding of ViciDial dialplan basics
Active outbound campaign configured
At least one carrier/trunk configured for outbound calling
SSH access to modify /etc/asterisk/ configuration files
Familiarity with basic Asterisk CLI commands

Verify your current installation:

sudo asterisk -v
sudo mysql -u root -p -e "SELECT VERSION();"
grep -i "version" /usr/share/astguiclient/vicidial.conf | head -5

Understanding AMD (Answering Machine Detection)

What Is AMD?

Answering Machine Detection is an Asterisk application that analyzes audio patterns during the first few seconds of a call to determine whether a human answered or a voicemail/answering machine picked up. This allows ViciDial to:

Route human-answered calls directly to agents
Send machine-answered calls to voicemail drop, callback queue, or hangup
Reduce agent talk time on dead-end calls
Improve first-call resolution rates
Gather more callbacks from live prospects

How Asterisk AMD Works

Asterisk's AMD application listens to the initial audio after answer for:

Silence - Machines typically have silence before greeting
Voice patterns - Frequency analysis to distinguish human speech from recorded messages
Speech/silence ratio - Humans vary speech patterns; machines are monotone
Duration thresholds - Machines usually have longer initial silence periods

The engine compares these against configurable thresholds and returns a detection result: HUMAN, MACHINE, or NOTSURE.

ViciDial AMD Configuration Architecture

Configuration Layers

AMD in ViciDial operates across multiple layers:

Asterisk dialplan level - /etc/asterisk/extensions-vicidial.conf
ViciDial campaign settings - Web admin panel and vicidial_campaigns table
Carrier/trunk configuration - /etc/asterisk/sip-vicidial.conf
Application logic - /usr/share/astguiclient/ scripts and vicidial_log recording

Key ViciDial Tables for AMD

-- View campaign AMD settings
SELECT campaign_id, campaign_name, answering_machine_detect, 
       amd_machine_action, amd_human_action 
FROM vicidial_campaigns LIMIT 5;

-- Check call logs with AMD results
SELECT lead_id, caller_id_number, call_date, amd_result, 
       status, call_length 
FROM vicidial_log 
WHERE amd_result IS NOT NULL 
ORDER BY call_date DESC LIMIT 20;

-- View carrier AMD configuration
SELECT carrier_id, carrier_name, call_quality, sip_account 
FROM vicidial_carrier_log LIMIT 10;

Step 1: Enable AMD in Your Campaign

Access Campaign Settings

Log into ViciDial admin panel:

https://your-vicidial-ip/vicidial/admin.php

Navigate: Campaigns → Select Your Campaign → Edit Campaign → Call Parameters

Database Method (Recommended for Bulk Changes)

Connect to the asterisk database:

mysql -u root -p asterisk

Enable AMD for a specific campaign:

UPDATE vicidial_campaigns 
SET answering_machine_detect = 'Y',
    amd_machine_action = 'VOICEMAIL',
    amd_human_action = 'AGENT',
    amd_sensitivity = '2'
WHERE campaign_id = 'TESTCAMP';

-- Verify the change
SELECT campaign_id, answering_machine_detect, amd_machine_action, 
       amd_human_action, amd_sensitivity 
FROM vicidial_campaigns 
WHERE campaign_id = 'TESTCAMP';

Field Explanations:

answering_machine_detect - Enable AMD ('Y'/'N')
amd_machine_action - What to do when machine detected: VOICEMAIL, HANGUP, CALLBACK
amd_human_action - What to do when human detected: AGENT, VOICEMAIL
amd_sensitivity - Detection sensitivity level (1-5, default 2)

Exit MySQL:

quit

Step 2: Configure Asterisk Dialplan

Locate the Dialplan File

sudo nano /etc/asterisk/extensions-vicidial.conf

Standard AMD Application Syntax

Add or modify the AMD application call in your outbound dialplan. Find the section for outbound calls (typically context from-internal):

[from-internal]
exten => _X.,1,NoOp(Starting outbound call for ${EXTEN})
exten => _X.,n,Set(TIMEOUT(absolute)=3600)
exten => _X.,n,GotoIf($["${answering_machine_detect}" = "Y"]?amd:noamd)
exten => _X.,n(amd),AMD(initial_silence=1500,greeting=1500,after_greeting_silence=800,total_analysis_time=5000,min_word_length=100,between_words_silence=50,silence_threshold=256)
exten => _X.,n,GotoIf($["${AMDSTATUS}" = "HUMAN"]?human:machine)
exten => _X.,n(human),Dial(SIP/${EXTEN}@carrier,45,m)
exten => _X.,n(machine),VoiceMail(u${EXTEN})
exten => _X.,n(noamd),Dial(SIP/${EXTEN}@carrier,45,m)

AMD Parameter Breakdown

AMD(
  initial_silence=1500,        # Silence before greeting starts (ms) - 1500ms = 1.5s
  greeting=1500,               # Max time to listen for greeting (ms)
  after_greeting_silence=800,  # Silence after greeting ends (ms)
  total_analysis_time=5000,    # Maximum time to run detection (ms)
  min_word_length=100,         # Min milliseconds for word (filter for noise)
  between_words_silence=50,    # Expected silence between words (ms)
  silence_threshold=256        # Audio level threshold for silence detection (0-32768)
)

Recommended Settings for Different Scenarios:

For aggressive detection (more false positives as human):

AMD(initial_silence=800,greeting=1200,after_greeting_silence=500,total_analysis_time=3000,min_word_length=80,between_words_silence=40,silence_threshold=256)

For conservative detection (more false negatives as machine):

AMD(initial_silence=2000,greeting=2000,after_greeting_silence=1000,total_analysis_time=6000,min_word_length=120,between_words_silence=60,silence_threshold=256)

For international calls (longer greeting times):

AMD(initial_silence=2500,greeting=2500,after_greeting_silence=1200,total_analysis_time=7000,min_word_length=100,between_words_silence=50,silence_threshold=256)

ViciDial's AMD Integration in Dialplan

ViciDial typically handles AMD through the vicidial_dial context. Find this section:

grep -n "vicidial_dial" /etc/asterisk/extensions-vicidial.conf | head -20

Locate and update the AMD section (usually around line 800-1200):

[vicidial_dial]
exten => 1,1,NoOp(ViciDial Dial Context - AMD Enabled)
exten => 1,n,Set(DIALGROUP=${CUT(DIALSTRING,^,1)})
exten => 1,n,Set(EXTENSION=${CUT(DIALSTRING,^,2)})
exten => 1,n,Set(answering_machine_detect=${amd_setting})

exten => 1,n,GotoIf($["${answering_machine_detect}" = "Y"]?doamd:nocheckamd)

exten => 1,n(doamd),NoOp(Running AMD with sensitivity: ${amd_sensitivity})
exten => 1,n,AMD(initial_silence=1500,greeting=1500,after_greeting_silence=800,total_analysis_time=5000,min_word_length=100,between_words_silence=50,silence_threshold=256)
exten => 1,n,Set(amd_result=${AMDSTATUS})
exten => 1,n,NoOp(AMD Result: ${amd_result})

exten => 1,n(nocheckamd),GotoIf($["${amd_result}" = "HUMAN"]?routehuman)
exten => 1,n,GotoIf($["${amd_result}" = "MACHINE"]?routemachine)
exten => 1,n(routehuman),NoOp(Routing to agent)
exten => 1,n,Dial(SIP/${EXTENSION}@${CARRIER},45,m)
exten => 1,n(routemachine),NoOp(Machine detected - applying action: ${amd_machine_action})
exten => 1,n,VoiceMail(u${EXTENSION})

Reload Asterisk After Changes

sudo asterisk -rx "dialplan reload"
sudo asterisk -rx "module reload app_amd"

Verify the reload was successful:

sudo asterisk -rx "dialplan show vicidial_dial@from-internal" | grep -i amd

Step 3: Configure Carrier/Trunk Settings

Edit SIP Configuration

sudo nano /etc/asterisk/sip-vicidial.conf

Ensure your carrier/trunk has appropriate settings for AMD:

[carrier_siptrunk]
type=peer
host=carrier.example.com
secret=yoursecret
username=youruser
fromuser=youruser
fromdomain=carrier.example.com
context=from-internal
disallow=all
allow=ulaw
allow=alaw
nat=yes
rtptimeout=600
rtpholdtimeout=3600
insecure=port,invite
reinvite=nodata

; AMD-specific settings
; Ensure codec matches to avoid audio quality issues
directmedia=no
; Important: Keep connection open for AMD audio analysis
dtmfmode=rfc2833

Reload SIP configuration:

sudo asterisk -rx "sip reload"

Step 4: Configure Machine Detection Actions

Understanding Machine Actions

When AMD detects a machine, you have three primary actions:

Option 1: VOICEMAIL (Drop Message)

UPDATE vicidial_campaigns 
SET amd_machine_action = 'VOICEMAIL' 
WHERE campaign_id = 'TESTCAMP';

Configure your voicemail drop message:

sudo nano /etc/asterisk/voicemail.conf

Add a context for ViciDial voicemail drops:

[vicidial]
; Voicemail drop box for machine-detected calls
1000 => 1234,ViciDial Machine Drop,machine@vicidial.com,,|attach=yes|saycid=yes|sendvoicemail=yes|delete=no

Create the voicemail drop message file:

sudo mkdir -p /var/spool/asterisk/voicemail/vicidial/1000/INBOX
sudo chown -R asterisk:asterisk /var/spool/asterisk/voicemail/

Record and upload a custom message, or use this command to create via TTS:

echo "Your company name. Press 1 to schedule a callback or hang up." | \
  text2wave -o /var/spool/asterisk/voicemail/vicidial/1000/INBOX/msg0000.wav

Option 2: HANGUP (Disconnect Call)

UPDATE vicidial_campaigns 
SET amd_machine_action = 'HANGUP' 
WHERE campaign_id = 'TESTCAMP';

Useful for high-volume campaigns where you don't want to spend credits on machine messages.

Option 3: CALLBACK (Queue for Callback)

UPDATE vicidial_campaigns 
SET amd_machine_action = 'CALLBACK' 
WHERE campaign_id = 'TESTCAMP';

Requires callback queue configuration in ViciDial admin panel.

Configure Human Actions

When a human is detected, route to agent:

UPDATE vicidial_campaigns 
SET amd_human_action = 'AGENT' 
WHERE campaign_id = 'TESTCAMP';

Or send to voicemail if agent unavailable:

UPDATE vicidial_campaigns 
SET amd_human_action = 'VOICEMAIL' 
WHERE campaign_id = 'TESTCAMP';

Step 5: Adjust AMD Sensitivity

Sensitivity Levels

ViciDial uses 5 sensitivity levels (1-5):

Level 1 - Most aggressive (detects more as HUMAN)
Level 2 - Default, balanced
Level 3 - Moderate
Level 4 - Conservative
Level 5 - Most conservative (detects more as MACHINE)

Adjust via Database

UPDATE vicidial_campaigns 
SET amd_sensitivity = '2' 
WHERE campaign_id = 'TESTCAMP';

Fine-Tune with Asterisk Parameters

Modify the threshold values in your dialplan:

For higher sensitivity (fewer machines detected as human):

AMD(initial_silence=2000,greeting=1800,after_greeting_silence=1000,total_analysis_time=6000,min_word_length=120,between_words_silence=60,silence_threshold=256)

For lower sensitivity (more lenient):

AMD(initial_silence=1000,greeting=1200,after_greeting_silence=600,total_analysis_time=4000,min_word_length=80,between_words_silence=40,silence_threshold=256)

Step 6: Monitor AMD Performance

Real-Time Monitoring

Check AMD statistics in real-time:

sudo asterisk -rx "core show calls"

Monitor Asterisk logs specifically for AMD:

tail -f /var/log/asterisk/messages | grep AMD

Example output:

[2024-01-15 14:23:45] -- AMD: Detected HUMAN on channel SIP/1001-00001234
[2024-01-15 14:24:12] -- AMD: Detected MACHINE on channel SIP/1002-00001235
[2024-01-15 14:24:45] -- AMD: NOTSURE on channel SIP/1003-00001236

Query AMD Results from Database

Check detection accuracy for a date range:

SELECT 
  amd_result,
  COUNT(*) as call_count,
  ROUND(COUNT(*)*100.0/(SELECT COUNT(*) FROM vicidial_log 
    WHERE call_date >= DATE_SUB(NOW(), INTERVAL 7 DAY) 
    AND amd_result IS NOT NULL),2) as percentage
FROM vicidial_log 
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 7 DAY) 
  AND amd_result IS NOT NULL
GROUP BY amd_result;

Expected output:

+----------+------------+------------+
| amd_result | call_count | percentage |
+----------+------------+------------+
| HUMAN    |       1245 |      68.50 |
| MACHINE  |        456 |      25.10 |
| NOTSURE  |        119 |       6.40 |
+----------+------------+------------+

Campaign-Specific AMD Analytics

SELECT 
  campaign_id,
  COUNT(*) as total_calls,
  SUM(CASE WHEN amd_result = 'HUMAN' THEN 1 ELSE 0 END) as humans,
  SUM(CASE WHEN amd_result = 'MACHINE' THEN 1 ELSE 0 END) as machines,
  SUM(CASE WHEN amd_result = 'NOTSURE' THEN 1 ELSE 0 END) as notsure,
  ROUND(AVG(call_length),2) as avg_call_length
FROM vicidial_log 
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 1 DAY)
  AND amd_result IS NOT NULL
GROUP BY campaign_id
ORDER BY total_calls DESC;

Create AMD Performance Report View

CREATE VIEW amd_performance_daily AS
SELECT 
  DATE(call_date) as call_date,
  campaign_id,
  COUNT(*) as total_calls,
  ROUND(SUM(CASE WHEN amd_result = 'HUMAN' THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) as human_percentage,
  ROUND(SUM(CASE WHEN amd_result = 'MACHINE' THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) as machine_percentage,
  ROUND(SUM(CASE WHEN amd_result = 'NOTSURE' THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) as notsure_percentage,
  ROUND(AVG(call_length), 2) as avg_call_length_seconds
FROM vicidial_log 
WHERE amd_result IS NOT NULL
GROUP BY DATE(call_date), campaign_id;

SELECT * FROM amd_performance_daily WHERE call_date >= DATE_SUB(NOW(), INTERVAL 7 DAY);

Step 7: Optimize Performance

CPU Impact

AMD analysis requires CPU resources. For high-volume systems:

# Check current load
top -b -n 1 | head -3

# Monitor Asterisk process
ps aux | grep asterisk | grep -v grep

Database Performance

AMD logging can increase database I/O. Optimize:

-- Add index on amd_result for faster queries
ALTER TABLE vicidial_log ADD INDEX idx_amd_result (amd_result);

-- Archive old AMD data
INSERT INTO vicidial_log_archive SELECT * FROM vicidial_log 
WHERE call_date < DATE_SUB(NOW(), INTERVAL 90 DAY);

DELETE FROM vicidial_log 
WHERE call_date < DATE_SUB(NOW(), INTERVAL 90 DAY);

-- Optimize table
OPTIMIZE TABLE vicidial_log;

Audio Codec Selection

For best AMD performance, use:

; In your sip-vicidial.conf carrier config
disallow=all
allow=ulaw
allow=alaw
; Avoid GSM or other compressed codecs

Adjust Analysis Time

If AMD is consuming too much CPU, reduce analysis time:

AMD(initial_silence=1500,greeting=1500,after_greeting_silence=800,total_analysis_time=3500,min_word_length=100,between_words_silence=50,silence_threshold=256)

This reduces from 5000ms to 3500ms maximum analysis time.

Troubleshooting

Issue 1: AMD Not Detecting Anything (All NOTSURE)

Symptoms: AMD runs but all results are NOTSURE

Diagnosis:

tail -f /var/log/asterisk/messages | grep -i notsure

Solutions:

Verify AMD module is loaded:

sudo asterisk -rx "module show like amd"

Output should show:

Module                         Description                      Use Count
app_amd.so                     Answering Machine Detection      0

Check if AMD settings match campaign config:

SELECT campaign_id, answering_machine_detect, amd_sensitivity, 
       amd_machine_action, amd_human_action 
FROM vicidial_campaigns 
WHERE campaign_id = 'TESTCAMP';

Lower sensitivity level:

UPDATE vicidial_campaigns 
SET amd_sensitivity = '1' 
WHERE campaign_id = 'TESTCAMP';

Increase analysis time in dialplan:

AMD(initial_silence=2500,greeting=2500,after_greeting_silence=1200,total_analysis_time=7000,min_word_length=100,between_words_silence=50,silence_threshold=256)

Issue 2: Too Many False Positives (Machines Detected as Human)

Symptoms: AMD marks voicemail boxes as HUMAN, agents connect to machines

Solutions:

Increase sensitivity:

UPDATE vicidial_campaigns 
SET amd_sensitivity = '4' 
WHERE campaign_id = 'TESTCAMP';

Adjust dialplan parameters to be more conservative:

AMD(initial_silence=2000,greeting=2000,after_greeting_silence=1000,total_analysis_time=6000,min_word_length=120,between_words_silence=60,silence_threshold=256)

Increase initial silence detection:

AMD(initial_silence=2500,greeting=2000,after_greeting_silence=1000,total_analysis_time=5500,min_word_length=100,between_words_silence=50,silence_threshold=256)

Issue 3: Too Many False Negatives (Humans Detected as Machine)

Symptoms: Real people being treated as machines, agents missing live calls

Solutions:

Decrease sensitivity:

UPDATE vicidial_campaigns 
SET amd_sensitivity = '1' 
WHERE campaign_id = 'TESTCAMP';

Adjust to more aggressive detection:

AMD(initial_silence=1200,greeting=1200,after_greeting_silence=600,total_analysis_time=4000,min_word_length=80,between_words_silence=40,silence_threshold=256)

Reduce min_word_length to catch softer human voices:

AMD(initial_silence=1500,greeting=1500,after_greeting_silence=800,total_analysis_time=5000,min_word_length=70,between_words_silence=50,silence_threshold=256)

Issue 4: AMD Not Running at All

Symptoms: Campaign has AMD enabled but amd_result column is always NULL

Check the dialplan context is correct:

grep -A 20 "answering_machine_detect" /etc/asterisk/extensions-vicidial.conf

Verify campaign setting:

SELECT campaign_id, answering_machine_detect 
FROM vicidial_campaigns 
WHERE campaign_id = 'TESTCAMP';

Reload dialplan:

sudo asterisk -rx "dialplan reload"
sudo asterisk -rx "module reload app_amd"
sudo service asterisk restart

Check for errors in logs:

grep -i "error\|warning" /var/log/asterisk/messages | tail -20

Issue 5: AMD Causing Call Delays

Symptoms: Noticeable delay before agent answer or ringback

Solutions:

Reduce total_analysis_time:

AMD(initial_silence=1200,greeting=1200,after_greeting_silence=600,total_analysis_time=3000,min_word_length=100,between_words_silence=50,silence_threshold=256)

Reduce greeting time:

AMD(initial_silence=1000,greeting=1000,after_greeting_silence=500,total_analysis_time=3500,min_word_length=100,between_words_silence=50,silence_threshold=256)

Check Asterisk CPU - if high, enable AMD on fewer campaigns:

top -p $(pgrep -f "asterisk -f")

Issue 6: Database Filling Up with AMD Logs

Symptoms: /var partition nearly full, slow database queries

Solution - Archive and purge old AMD data:

# First, create backup
mysqldump -u root -p asterisk vicidial_log > /backup/vicidial_log_backup_$(date +%Y%m%d).sql

# Then, in MySQL
mysql -u root -p asterisk

-- Archive calls older than 90 days
INSERT INTO vicidial_log_archive 
SELECT * FROM vicidial_log 
WHERE call_date < DATE_SUB(NOW(), INTERVAL 90 DAY);

-- Delete archived records
DELETE FROM vicidial_log 
WHERE call_date < DATE_SUB(NOW(), INTERVAL 90 DAY);

-- Optimize table
OPTIMIZE TABLE vicidial_log;

-- Check size reduction
SELECT 
  ROUND(((data_length + index_length) / 1024 / 1024), 2) as size_mb
FROM information_schema.tables 
WHERE table_schema = 'asterisk' 
  AND table_name = 'vicidial_log';

Step 8: A/B Testing AMD Performance

Set Up Two Campaigns for Testing

Campaign 1 (Control - AMD Disabled):

UPDATE vicidial_campaigns 
SET answering_machine_detect = 'N' 
WHERE campaign_id = 'TESTCAMP_CONTROL';

Campaign 2 (Test - AMD Enabled):

UPDATE vicidial_campaigns 
SET answering_machine_detect = 'Y',
    amd_machine_action = 'VOICEMAIL',
    amd_human_action = 'AGENT',
    amd_sensitivity = '2'
WHERE campaign_id = 'TESTCAMP_AMD';

Compare Results

SELECT 
  campaign_id,
  COUNT(*) as total_calls,
  ROUND(AVG(call_length), 2) as avg_talk_time,
  ROUND(SUM(CASE WHEN status = 'SALE' THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) as conversion_rate,
  ROUND(SUM(CASE WHEN status IN ('SALE','CALLACK') THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) as success_rate
FROM vicidial_log 
WHERE campaign_id IN ('TESTCAMP_CONTROL', 'TESTCAMP_AMD')
  AND call_date >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY campaign_id;

Expected results with AMD enabled:

Lower average talk time (avoid machine messages)
Higher conversion rate (agent time on real prospects)
Reduced call volume needed for same results

Best Practices and Recommendations

1. Start Conservative

Begin with AMD enabled on one campaign at lower sensitivity (3-4) to validate detection accuracy before rolling out widely.

2. Monitor Accuracy Rates

Aim for 85-95% overall accuracy. Review NOTSURE results weekly:

SELECT call_id, phone_number, amd_result, status, call_length 
FROM vicidial_log 
WHERE amd_result = 'NOTSURE' 
  AND call_date >= DATE_SUB(NOW(), INTERVAL 7 DAY) 
ORDER BY call_date DESC 
LIMIT 50;

3. Combine AMD with Other Strategies

Use AMD with voicemail drop campaigns for best ROI
Combine with callback mechanisms for better contact rates
Monitor agent feedback on detection accuracy

4. Regular Parameter Tuning

Adjust AMD parameters quarterly based on:

Carrier quality changes
Dialable list characteristics
Agent feedback
Conversion metrics

5. Failover Strategy

Ensure AMD failures don't break the call:

exten => 1,n,GotoIf($["${AMDSTATUS}" = "HUMAN"]?human)
exten => 1,n,GotoIf($["${AMDSTATUS}" = "MACHINE"]?machine)
exten => 1,n(human),Dial(SIP/${EXTENSION}@${CARRIER},45,m)
exten => 1,n(machine),VoiceMail(u${EXTENSION})

Always have a default action if AMD fails.

6. Logging and Auditing

Enable detailed logging:

[general]
verbose=3
debug=3

This generates more logs but aids troubleshooting.

Summary

Answering Machine Detection in ViciDial significantly improves outbound campaign efficiency by automatically filtering machine-answered calls from human-answered calls. The configuration spans three areas:

Campaign Settings - Enable AMD and set machine/human actions via vicidial_campaigns table
Asterisk Dialplan - Configure AMD application with appropriate parameters in extensions-vicidial.conf
Monitoring & Optimization - Query vicidial_log table for AMD results and continuously tune parameters

Key takeaways:

Start with default settings (sensitivity 2, 5000ms analysis time) and adjust based on results
Monitor detection accuracy weekly to catch false positives/negatives early
Use appropriate machine actions (VOICEMAIL for leads to keep, HANGUP for high-volume, CALLBACK for follow-ups)
Archive AMD data regularly to maintain database performance
Test A/B campaigns to validate ROI before full rollout

With proper AMD configuration, expect:

20-40% reduction in agent talk time
15-25% improvement in conversion rates
30-50% lower cost per conversion
Significantly improved agent morale

Regularly review your AMD performance metrics, gather agent feedback, and adjust parameters quarterly. AMD is not a "set and forget" feature—continuous optimization yields the best results for your specific calling profile and contact list characteristics.

How to Set Up ViciDial DID Routing — Inbound Number Configuration

Moisi Trungu — Sun, 16 Aug 2026 03:30:03 +0000

How to Set Up ViciDial DID Routing — Inbound Number Configuration

Master complete inbound DID routing configuration in ViciDial, from carrier integration through call distribution to agents, with production-ready examples and troubleshooting strategies.

Prerequisites

Before you begin this tutorial, ensure you have:

ViciDial installation: Running 2.14+ (tested on 2.14.0.1 and later)
Asterisk server: Version 13+ with chan_sip or PJSIP installed
Database access: MySQL/MariaDB with vicidial user credentials
Root or sudo access: Required for Asterisk configuration modifications
SIP carrier account: Active account with inbound call capability
ViciDial admin panel access: Web interface at http://your-server/vicidial/admin.php
SSH/terminal access: To the ViciDial server for CLI operations
Basic ViciDial knowledge: Familiarity with campaigns, user accounts, and call disposition codes

Understanding ViciDial DID Routing Architecture

DID (Direct Inward Dialing) routing in ViciDial connects incoming calls from your carrier through Asterisk dialplan logic, into ViciDial's inbound call queue system, and finally to available agents or IVR systems.

The routing chain flows like this:

SIP Carrier → Asterisk (sip-vicidial.conf) → 
Extensions Dialplan (extensions-vicidial.conf) → 
ViciDial Inbound Groups → Call Queue → Agent

Each DID number must be mapped to:

An Asterisk context for initial routing
A ViciDial inbound group
Queue settings (agents, call recording, etc.)
Agent assignment strategy (round-robin, longest-idle, etc.)

Prerequisites Continued: Database Tables

The following ViciDial database tables are critical for DID routing:

Table	Purpose
`vicidial_inbound_groups`	Defines inbound call groups (queues)
`vicidial_users`	Agent accounts and inbound group assignments
`vicidial_phone_codes`	DID to inbound group mapping
`vicidial_carrier_log`	Inbound call detail records
`vicidial_log`	Agent interaction logs

Step 1: Configure Your SIP Carrier Connection

1.1 Add Carrier to ViciDial Database

First, register your SIP carrier in the carrier configuration. Log into MySQL:

mysql -u root -p asterisk

Query existing carriers:

SELECT carrier_id, carrier_name, active FROM vicidial_carriers LIMIT 10;

Insert a new carrier (e.g., VoIP.ms):

INSERT INTO vicidial_carriers 
(carrier_id, carrier_name, active, carrier_type, max_inbound, max_outbound, 
 inbound_cid, description)
VALUES 
('VOIPMS', 'VoIP.ms', 'Y', 'SIP', 50, 100, 'Y', 'Primary SIP carrier');

Exit MySQL:

EXIT;

1.2 Configure SIP Trunk in sip-vicidial.conf

Edit the SIP configuration file:

sudo nano /etc/asterisk/sip-vicidial.conf

Add or modify your carrier SIP peer configuration. Example for VoIP.ms:

; VoIP.ms SIP Trunk Configuration
[voipms]
type=peer
host=toronto1.voip.ms
username=account_number
password=your_sip_password
secret=your_sip_password
fromuser=account_number
fromdomain=toronto1.voip.ms
context=from-voipms
insecure=port,invite
dtmfmode=rfc2833
canreinvite=no
nat=yes
qualify=yes
qualifyfreq=60
maxcallbitrate=128000
disallow=all
allow=ulaw,alaw
description=VoIP.ms Inbound Trunk

For a local SIP PBX or test environment:

[localsip]
type=peer
host=192.168.1.100
username=vicidial
password=your_password
secret=your_password
context=from-local-pbx
insecure=port,invite
nat=no
qualify=yes

1.3 Test Carrier Connection

Reload Asterisk SIP configuration:

sudo asterisk -rx "sip reload"

Verify the peer is registered:

sudo asterisk -rx "sip show peers"

You should see your carrier peer listed with status "OK (x ms)".

Check registration if using registration:

sudo asterisk -rx "sip show registry"

Step 2: Create Inbound Groups in ViciDial

Inbound groups are the core container for call distribution in ViciDial. Every inbound DID must belong to an inbound group.

2.1 Access the Admin Panel

Navigate to:

http://your-vicidial-server/vicidial/admin.php

2.2 Create Inbound Group via Admin

Click Inbound → Inbound Groups
Click ADD NEW INBOUND GROUP
Fill in the following fields:

Field	Example Value	Notes
Inbound Group Name	Sales_Queue_001	Unique identifier
Inbound Group ID	sales_001	System-wide unique ID
Active	Y	Enable the group
Calls in Queue Limit	100	Max queued calls before rejection
Greeting Recording	sales_greeting.wav	IVR greeting file
Hold Recording	hold_music.wav	Music on hold file
Voicemail Recording	voicemail.wav	Voicemail greeting
CID Group	EXTERNAL	Caller ID group for ANI capture
Call Recording	Y	Record all inbound calls
Web Form Recording	N	Skip web form integration
Default Group	Y	Primary routing group

Click SUBMIT.

2.3 Create via Direct Database Insertion

Alternatively, insert directly into the database:

INSERT INTO vicidial_inbound_groups
(inbound_group_id, inbound_group_name, active, calls_in_queue_limit, 
 greeting_id, hold_id, voicemail_id, cid_group_id, call_recording, 
 web_form_address, web_form_recording, default_group, park_extension, 
 park_timeout)
VALUES
('sales_001', 'Sales_Queue_001', 'Y', 100, 1, 1, 1, 'EXTERNAL', 'Y', 
 '', 'N', 'Y', '6900', 1800);

Verify creation:

SELECT inbound_group_id, inbound_group_name, active FROM vicidial_inbound_groups 
WHERE inbound_group_id = 'sales_001';

Step 3: Assign Agents to Inbound Groups

Agents must be explicitly assigned to inbound groups before they can receive inbound calls.

3.1 Assign via Admin Panel

Navigate to Admin → Users
Click on an agent's username
Under Inbound Settings, select the inbound group from the dropdown
Set Agent Type to "INBOUND" or "BOTH"
Click SUBMIT

3.2 Assign via Database

UPDATE vicidial_users 
SET inbound_group = 'sales_001',
    user_level = 1,
    active = 'Y'
WHERE user = 'agent001';

Verify assignment:

SELECT user, inbound_group, user_level, active 
FROM vicidial_users 
WHERE user = 'agent001';

3.3 Set Agent Availability

Agents must be logged in and in "READY" state to receive calls. This is handled via the agent interface at /agc/vicidial.php, but you can verify availability:

sudo asterisk -rx "queue show sales_001"

This command shows all agents in the queue and their status.

Step 4: Map DIDs to Inbound Groups

DIDs are mapped to inbound groups using the vicidial_phone_codes table. Each DID number can route to a specific inbound group.

4.1 Insert DID-to-Group Mapping

Map a DID number to your inbound group:

INSERT INTO vicidial_phone_codes
(phone_code, phone_code_name, inbound_group, call_type, active, 
 description)
VALUES
('2015550123', 'Sales DID Main', 'sales_001', 'INGROUP', 'Y', 
 'Primary sales inbound DID');

For multiple DIDs to the same group:

INSERT INTO vicidial_phone_codes
(phone_code, phone_code_name, inbound_group, call_type, active, description)
VALUES
('2015550123', 'Sales DID 1', 'sales_001', 'INGROUP', 'Y', 'Sales line'),
('2015550124', 'Sales DID 2', 'sales_001', 'INGROUP', 'Y', 'Sales line'),
('2015550125', 'Sales DID 3', 'sales_001', 'INGROUP', 'Y', 'Sales line');

Verify mapping:

SELECT phone_code, inbound_group, call_type, active 
FROM vicidial_phone_codes 
WHERE inbound_group = 'sales_001' ORDER BY phone_code;

4.2 Configure via Admin Panel (Optional)

Navigate to Inbound → Phone Codes
Click ADD NEW PHONE CODE
Enter your DID number in Phone Code
Select your inbound group from the dropdown
Set Call Type to "INGROUP"
Click SUBMIT

Step 5: Configure Asterisk Dialplan Extensions

The Asterisk dialplan bridges the gap between the SIP carrier context and ViciDial's inbound group system.

5.1 Create Carrier Context in extensions-vicidial.conf

Edit the main extensions file:

sudo nano /etc/asterisk/extensions-vicidial.conf

Add a context for your carrier. This example routes from VoIP.ms:

[from-voipms]
exten => _.,1,NoOp(Inbound DID: ${EXTEN} from ${CALLERID(num)})
exten => _.,n,Set(CALLERID(num)=${CALLERID(num)})
exten => _.,n,Set(CALLERID(name)=${CALLERID(name)})
exten => _.,n,Set(TO_VICIDIAL=${EXTEN})
exten => _.,n,Gosub(route-vicidial,${EXTEN},1)
exten => _.,n,Hangup()

include => parked-calls

5.2 Create ViciDial Routing Subroutine

Add the main ViciDial routing subroutine in the same file:

[route-vicidial]
exten => _.,1,NoOp(=== ViciDial Routing Subroutine ===)
exten => _.,n,NoOp(Received DID: ${ARG1})
exten => _.,n,Set(DID_NUMBER=${ARG1})

; Query database for inbound group
exten => _.,n,ODBC_Query(vicidial,SELECT inbound_group FROM vicidial_phone_codes WHERE phone_code='${DID_NUMBER}',result)
exten => _.,n,Set(INBOUND_GROUP=${result})

; Route based on inbound group
exten => _.,n,GotoIf($[${LEN(${INBOUND_GROUP})} > 0]?found:notfound)

exten => _.,n(found),NoOp(Found inbound group: ${INBOUND_GROUP})
exten => _.,n,Set(CHANNEL(language)=en)
exten => _.,n,Gosub(queue-call,${INBOUND_GROUP},1)
exten => _.,n,Return()

exten => _.,n(notfound),NoOp(No inbound group found for DID: ${DID_NUMBER})
exten => _.,n,Playback(sorry-youve-dialed-a-wrong-number)
exten => _.,n,Hangup()

[queue-call]
exten => _.,1,NoOp(=== Entering Queue: ${ARG1} ===)
exten => _.,n,Set(VICIDIAL_INBOUND_GROUP=${ARG1})
exten => _.,n,Set(CALL_RECORDING=Y)
exten => _.,n,Set(UNIQUEID=${UNIQUEID()})
exten => _.,n,Queue(${ARG1},t,,180)
exten => _.,n,Hangup()

5.3 Alternative: Direct Queue Entry (Simplified)

For simpler configurations without database lookups:

[from-voipms]
; Route specific DIDs directly to queues
exten => 2015550123,1,NoOp(Sales DID received)
exten => 2015550123,n,Set(VICIDIAL_INBOUND_GROUP=sales_001)
exten => 2015550123,n,Queue(sales_001,t,,180)
exten => 2015550123,n,Hangup()

exten => 2015550124,1,NoOp(Support DID received)
exten => 2015550124,n,Set(VICIDIAL_INBOUND_GROUP=support_001)
exten => 2015550124,n,Queue(support_001,t,,180)
exten => 2015550124,n,Hangup()

exten => 2015550125,1,NoOp(Billing DID received)
exten => 2015550125,n,Set(VICIDIAL_INBOUND_GROUP=billing_001)
exten => 2015550125,n,Queue(billing_001,t,,180)
exten => 2015550125,n,Hangup()

5.4 Reload Dialplan

Apply the changes:

sudo asterisk -rx "dialplan reload"

Verify the dialplan loaded correctly:

sudo asterisk -rx "dialplan show from-voipms"

Step 6: Configure Queue Parameters in ViciDial

Queue settings control call distribution behavior in your inbound groups.

6.1 Queue Strategy Settings

Edit /etc/asterisk/queues.conf or add to extensions context:

[sales_001]
music = default
strategy = rrmemory
timeout = 180
announce = queue-announce
announce-frequency = 0
announce-holdtime = no
joinempty = yes
leavewhenempty = no
ringall = no
maxlen = 50

Queue Strategy Explanations:

rrmemory: Round-robin with memory (preferred for balanced distribution)
linear: Sequential agent order
fewest: Route to agent with fewest calls
leastrecent: Route to agent idle longest

6.2 Create Queue via ViciDial Admin

Navigate to Queues or queue settings in Inbound Groups
Set:
- Ring Strategy: Round-robin with memory
- Ring All Agents: No (ring one at a time)
- Max Queue Size: 100
- Wait Timeout: 180 seconds
- Agent Ring Timeout: 20 seconds (time before moving to next agent)

6.3 Verify Queue Configuration

sudo asterisk -rx "queue show sales_001"

Output should show:

sales_001
      Members:
         Local/agent001@from-internal (dynamic)
         Local/agent002@from-internal (dynamic)
      Callers:
         1. <Anonymous> (wait: 45:23, pos: 1)

Step 7: Configure ViciDial Logging and Recording

7.1 Enable Call Recording

Ensure recordings are enabled at both group and system level.

In vicidial_inbound_groups:

UPDATE vicidial_inbound_groups 
SET call_recording = 'Y',
    record_calls = 'Y'
WHERE inbound_group_id = 'sales_001';

7.2 Configure Recording Storage

Edit /etc/asterisk/modules.conf:

[modules]
autoload=yes
require=res_odbc.so
require=chan_sip.so
require=app_queue.so
require=app_mixmonitor.so

Recordings are typically stored in:

/var/spool/asterisk/monitor/

7.3 Verify Recording Directories

sudo ls -la /var/spool/asterisk/monitor/ | head -20

Ensure ViciDial daemon has write permissions:

sudo chown -R asterisk:asterisk /var/spool/asterisk/monitor/
sudo chmod 755 /var/spool/asterisk/monitor/

Step 8: Test the Complete DID Routing

8.1 Prepare Test Environment

Ensure:

At least one agent is logged into /agc/vicidial.php in READY state
Agent is assigned to sales_001 inbound group
Your DID carrier is sending calls properly

8.2 Perform Inbound Test Call

Call your DID number from an external phone.

Monitor call in Asterisk:

sudo asterisk -rx "core show channels"

You should see:

Channel              State   App      Data
SIP/voipms-xxxxx     Up      Queue    (sales_001,t,,180)
Local/agent001@xxx   Up      AppQueue ()

8.3 Check ViciDial Agent Screen

The agent's screen at /agc/vicidial.php should show the incoming call.

8.4 Verify Call Logging

Check the call was logged to database:

SELECT call_date, caller_id_number, caller_id_name, called_number, 
       duration, agent, dispo FROM vicidial_carrier_log 
WHERE called_number = '2015550123' 
ORDER BY call_date DESC LIMIT 5;

Also check ViciDial logs:

SELECT call_date, caller_id_number, user, dispo, talk_time, hold_time 
FROM vicidial_log 
WHERE inbound_group = 'sales_001' 
ORDER BY call_date DESC LIMIT 5;

Step 9: Implement Advanced Routing Scenarios

9.1 Time-Based Routing (Business Hours)

Route to different groups based on time of day:

[from-voipms]
exten => 2015550123,1,NoOp(DID received: ${EXTEN})

; Check if business hours (9 AM - 5 PM, Mon-Fri)
exten => 2015550123,n,GotoIf($[${IF($[${EPOCH} > ${STRFTIME(${EPOCH},2024-01-01 17:00:00,%s)}]?1:0)} = 1]?afterhours:business)

exten => 2015550123,n(business),NoOp(Routing to business hours group)
exten => 2015550123,n,Queue(sales_001,t,,180)
exten => 2015550123,n,Hangup()

exten => 2015550123,n(afterhours),NoOp(Routing to voicemail)
exten => 2015550123,n,VoiceMail(${EXTEN}@sales_voicemail)
exten => 2015550123,n,Hangup()

9.2 Skill-Based Routing

Route to different groups based on call type/IVR selection:

[from-voipms]
exten => 2015550123,1,NoOp(Sales main line)
exten => 2015550123,n,Set(SKILL_GROUP=sales_general)
exten => 2015550123,n,IVR(select-department)
exten => 2015550123,n,Queue(${SKILL_GROUP},t,,180)
exten => 2015550123,n,Hangup()

; IVR for department selection
[select-department]
exten => 1,1,NoOp(Selected: Billing)
exten => 1,n,Set(SKILL_GROUP=billing_001)
exten => 1,n,Return()

exten => 2,1,NoOp(Selected: Technical Support)
exten => 2,n,Set(SKILL_GROUP=support_001)
exten => 2,n,Return()

exten => 3,1,NoOp(Selected: Sales)
exten => 3,n,Set(SKILL_GROUP=sales_001)
exten => 3,n,Return()

9.3 Load Balancing Across Multiple Groups

Distribute calls across multiple similar groups:

[from-voipms]
exten => 2015550123,1,NoOp(Load balanced sales line)
exten => 2015550123,n,Set(LB_GROUP=${RAND(1,3)})
exten => 2015550123,n,Queue(sales_00${LB_GROUP},t,,180)
exten => 2015550123,n,Hangup()

This requires creating sales_001, sales_002, and sales_003 groups.

Step 10: Performance Tuning and Optimization

10.1 Optimize Queue Performance

Reduce database queries with caching:

sudo vi /etc/asterisk/res_odbc.conf

[asterisk]
dsn = asterisk
username = vicidial
password = your_password
pooling = yes
limit = 5
idleTimeout = 3600

10.2 Monitor Active Calls

Create a monitoring script:

#!/bin/bash
# check_vicidial_calls.sh
while true; do
  ACTIVE_CALLS=$(asterisk -rx "core show channels" | grep -c "SIP/")
  QUEUED_CALLS=$(asterisk -rx "queue show sales_001" | grep -c "wait:")

  echo "$(date): Active Calls: $ACTIVE_CALLS | Queued: $QUEUED_CALLS"

  sleep 5
done

Run it:

chmod +x check_vicidial_calls.sh
./check_vicidial_calls.sh

10.3 Database Query Optimization

Add indexes for faster lookups:

ALTER TABLE vicidial_phone_codes ADD INDEX idx_phone_code (phone_code);
ALTER TABLE vicidial_phone_codes ADD INDEX idx_inbound_group (inbound_group);
ALTER TABLE vicidial_users ADD INDEX idx_inbound_group (inbound_group);

Troubleshooting

Issue: Calls Not Reaching Agents

Symptoms: Incoming calls drop or go to voicemail instead of ringing agents.

Solutions:

Verify agent is logged in and READY:

sudo asterisk -rx "queue show sales_001"

Check agent assignment to inbound group:

SELECT user, inbound_group FROM vicidial_users WHERE user = 'agent001';

Verify queue context includes the inbound group:

sudo asterisk -rx "dialplan show sales_001"

Check Asterisk error logs:

sudo tail -f /var/log/asterisk/messages | grep -i queue

Issue: Calls Drop Immediately After Answer

Symptoms: Agent answers but call immediately disconnects.

Solutions:

Check SIP peer context matches dialplan context:

grep -A 5 "context=" /etc/asterisk/sip-vicidial.conf

Verify extensions exist in that context:

sudo asterisk -rx "dialplan show from-voipms" | head -20

Check for codec mismatch:

sudo asterisk -rx "sip show peer voipms"

Review logs for SIP errors:

sudo tail -f /var/log/asterisk/messages | grep -i sip

Issue: DID Not Found / Wrong Routing

Symptoms: Calls route to wrong queue or default handler.

Solutions:

Verify DID is in phone_codes table:

SELECT * FROM vicidial_phone_codes WHERE phone_code = '2015550123';

Check phone code format matches (leading zeros, country codes, etc.):

SELECT DISTINCT phone_code FROM vicidial_phone_codes LIMIT 10;

Test database query directly:

sudo asterisk -rx "database show vicidial"

Add debug logging to dialplan:

exten => _.,n,NoOp(DEBUG: DID=${DID_NUMBER} Group=${INBOUND_GROUP})

Then check:

sudo asterisk -rx "set verbose 4"

Issue: No Call Recordings

Symptoms: Calls complete but no recordings appear.

Solutions:

Verify recording is enabled:

SELECT inbound_group_id, call_recording FROM vicidial_inbound_groups 
WHERE inbound_group_id = 'sales_001';

Check recording directory exists and has proper permissions:

ls -la /var/spool/asterisk/monitor/ | head
sudo chown -R asterisk:asterisk /var/spool/asterisk/monitor/

Verify MixMonitor is loaded:

sudo asterisk -rx "module show like app_mixmonitor"

Check for disk space issues:

df -h /var/spool/asterisk/monitor/

Review ViciDial call logs for recording path:

SELECT call_date, recording_id, call_recording FROM vicidial_carrier_log 
WHERE inbound_group = 'sales_001' LIMIT 5;

Issue: Queue Timeout - Calls Hanging or Looping

Symptoms: Calls stay in queue too long or loop back to queue.

Solutions:

Verify queue timeout settings:

sudo asterisk -rx "queue show sales_001"

Adjust timeout in extensions-vicidial.conf:

exten => _.,n,Queue(sales_001,t,,120)  ; Reduced to 120 seconds

Check Asterisk queue settings in queues.conf:

grep -A 10 "\[sales_001\]" /etc/asterisk/queues.conf

Verify agent ring timeout:

[sales_001]
timeout = 20  ; Ring timeout per agent

Issue: High Call Abandonment Rate

Symptoms: Callers hanging up while waiting in queue.

Solutions:

Increase number of agents in group:

SELECT COUNT(*) as agent_count FROM vicidial_users 
WHERE inbound_group = 'sales_001' AND active = 'Y';

Monitor queue depth:

sudo asterisk -rx "queue show sales_001" | grep "Callers:"

Enable hold time announcements:

UPDATE vicidial_inbound_groups 
SET announce_holdtime = 'Y' 
WHERE inbound_group_id = 'sales_001';

Implement callback system for high queue depths:

exten => _.,n,GotoIf($[${QUEUE_MEMBER_COUNT(sales_001)} > 5]?callback:queue)
exten => _.,n(callback),VoiceMail(${EXTEN}@sales_callback)
exten => _.,n,Hangup()

Issue: Caller ID Not Displaying Correctly

Symptoms: Agent sees "Unknown" or generic CID instead of actual caller.

Solutions:

Enable CID preservation in dialplan:

exten => _.,1,Set(CALLERID(num)=${CALLERID(num)})
exten => _.,n,Set(CALLERID(name)=${CALLERID(name)})

Verify carrier sends ANI information:

sudo asterisk -rx "sip show channels" | grep voipms

Check CID Group settings:

SELECT * FROM vicidial_inbound_groups 
WHERE inbound_group_id = 'sales_001'\G

Review actual call logs:

SELECT caller_id_number, caller_id_name, agent 
FROM vicidial_carrier_log LIMIT 5;

Summary

You now have a complete, production-ready DID routing configuration in ViciDial. Here's what you've implemented:

Key Components Configured:

✅ SIP carrier connection with proper peer configuration
✅ Inbound groups created and configured in ViciDial
✅ DID-to-group mapping via phone codes table
✅ Asterisk dialplan with routing logic (from-voipms context)
✅ Queue management and agent assignment
✅ Call recording and logging infrastructure
✅ Advanced routing scenarios (time-based, skill-based, load-balanced)
✅ Comprehensive troubleshooting procedures

Critical Configuration Files:

/etc/asterisk/sip-vicidial.conf — Carrier SIP peer definitions
/etc/asterisk/extensions-vicidial.conf — Dialplan routing logic
/etc/asterisk/queues.conf — Queue parameters (optional)

Critical Database Tables:

vicidial_carriers — Carrier registration
vicidial_inbound_groups — Queue definitions
vicidial_phone_codes — DID mapping
vicidial_users — Agent assignments
vicidial_carrier_log — Inbound call records

Next Steps:

Test with real inbound calls from your carrier
Monitor performance using queue show and database queries
Implement failover routing for redundancy
Set up alerts for queue depth and agent availability
Document your specific DID/extension mappings
Schedule regular backup of extensions and queue configs

Best Practices:

Always test configuration changes with test calls before production traffic
Monitor /var/log/asterisk/messages during testing and troubleshooting
Keep detailed notes of all DID numbers, their purposes, and target inbound groups
Regularly review call logs and agent metrics to optimize routing
Implement proper access controls for admin panel and database
Test failover scenarios and call handling during agent unavailability

Your ViciDial DID routing is now ready for production use with proper logging, recording, and agent distribution.

How to Create Custom ViciDial Reports with SQL Queries

Moisi Trungu — Sat, 15 Aug 2026 03:30:03 +0000

How to Create Custom ViciDial Reports with SQL Queries

Master the art of building production-grade custom reports in ViciDial by writing optimized SQL queries against the asterisk database, complete with real examples, performance tuning, and troubleshooting strategies.

Prerequisites

Before diving into custom ViciDial reports, ensure you have:

A running ViciDial installation (v2.14 or later recommended)
SSH access to your ViciDial server with sudo privileges
MySQL/MariaDB client installed locally or access to the database server
Basic SQL knowledge (SELECT, WHERE, JOIN, GROUP BY)
Understanding of ViciDial's call flow and database structure
Database credentials for the asterisk database
Text editor or IDE with SQL syntax highlighting (optional but recommended)
Read access to /var/log/asterisk/messages for debugging

Verify your ViciDial installation:

mysql -u root -p -e "USE asterisk; SHOW TABLES LIKE 'vicidial%';" | head -20

Understanding ViciDial Database Structure

Critical Tables for Reporting

ViciDial stores call data across multiple interconnected tables. Understanding their relationships is fundamental to writing effective reports.

vicidial_log — The primary call record table. Every inbound/outbound call creates an entry here.

DESCRIBE asterisk.vicidial_log\G

Key columns:

uniqueid — Unique call identifier (varchar 32)
caller_id_number — Calling party number
caller_id_name — Calling party name
phone_number — Called party number
call_date — Call start timestamp
call_length — Duration in seconds
status — Final call status (SALE, NO ANSWER, BAD NUMBER, etc.)
campaign_id — Associated campaign
user — Agent username
list_id — DNC/contact list

vicidial_closer_log — Bridge logs for calls transferred to agents.

DESCRIBE asterisk.vicidial_closer_log\G

Key columns:

uniqueid — Links to vicidial_log
user — Agent who answered
closer_called_number — Number dialed by agent
status — Agent-assigned disposition
talk_time — Seconds agent spent talking
call_date — When agent answered

vicidial_users — Agent/user information.

DESCRIBE asterisk.vicidial_users\G

vicidial_campaigns — Campaign definitions and settings.

DESCRIBE asterisk.vicidial_campaigns\G

vicidial_list — Contact records.

DESCRIBE asterisk.vicidial_list\G

Database Connection String

Create a MySQL credentials file for secure, repeatable access:

cat > ~/.my.cnf << 'EOF'
[client]
user=root
password=your_password
host=localhost
database=asterisk
EOF

chmod 600 ~/.my.cnf

Verify connection:

mysql -e "SELECT COUNT(*) as total_calls FROM vicidial_log WHERE call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR);"

Setting Up Your Reporting Environment

Create a Dedicated Reporting Database User

For production security, create a read-only user:

CREATE USER 'vicidial_reports'@'localhost' IDENTIFIED BY 'secure_password_here';
GRANT SELECT ON asterisk.* TO 'vicidial_reports'@'localhost';
FLUSH PRIVILEGES;

Test the new user:

mysql -u vicidial_reports -p -e "SELECT VERSION();"

Organize Your Queries

Create a directory structure for managing report queries:

mkdir -p /home/vicidial_admin/reports/{daily,weekly,monthly,custom}
mkdir -p /home/vicidial_admin/reports/outputs
chmod 755 /home/vicidial_admin/reports

Common Report Queries

Daily Call Volume by Campaign

This query aggregates all calls for the past 24 hours, grouped by campaign.

SELECT 
    c.campaign_name,
    c.campaign_id,
    COUNT(vl.uniqueid) as total_calls,
    SUM(CASE WHEN vl.status = 'SALE' THEN 1 ELSE 0 END) as sales,
    SUM(CASE WHEN vl.status = 'SALE' THEN 1 ELSE 0 END) / COUNT(vl.uniqueid) * 100 as conversion_rate,
    ROUND(AVG(vl.call_length), 2) as avg_call_length,
    SUM(vl.call_length) as total_talk_time,
    MIN(vl.call_date) as first_call,
    MAX(vl.call_date) as last_call
FROM 
    vicidial_log vl
    LEFT JOIN vicidial_campaigns c ON vl.campaign_id = c.campaign_id
WHERE 
    vl.call_date >= DATE_SUB(CURDATE(), INTERVAL 1 DAY)
    AND vl.call_date < CURDATE()
    AND vl.status NOT IN ('', 'SKIP', 'QUEUE')
GROUP BY 
    vl.campaign_id, c.campaign_name
ORDER BY 
    total_calls DESC;

Save this to a file:

cat > /home/vicidial_admin/reports/daily/daily_volume.sql << 'EOF'
-- Daily Call Volume by Campaign
SELECT 
    c.campaign_name,
    c.campaign_id,
    COUNT(vl.uniqueid) as total_calls,
    SUM(CASE WHEN vl.status = 'SALE' THEN 1 ELSE 0 END) as sales,
    ROUND(SUM(CASE WHEN vl.status = 'SALE' THEN 1 ELSE 0 END) / COUNT(vl.uniqueid) * 100, 2) as conversion_rate,
    ROUND(AVG(vl.call_length), 2) as avg_call_length,
    SUM(vl.call_length) as total_talk_time,
    MIN(vl.call_date) as first_call,
    MAX(vl.call_date) as last_call
FROM 
    vicidial_log vl
    LEFT JOIN vicidial_campaigns c ON vl.campaign_id = c.campaign_id
WHERE 
    vl.call_date >= DATE_SUB(CURDATE(), INTERVAL 1 DAY)
    AND vl.call_date < CURDATE()
    AND vl.status NOT IN ('', 'SKIP', 'QUEUE')
GROUP BY 
    vl.campaign_id, c.campaign_name
ORDER BY 
    total_calls DESC;
EOF

Execute the report:

mysql < /home/vicidial_admin/reports/daily/daily_volume.sql > /home/vicidial_admin/reports/outputs/daily_volume_$(date +%Y%m%d).txt

Agent Performance Report

Track individual agent metrics over a specific period.

SELECT 
    vu.user,
    vu.full_name,
    COUNT(DISTINCT vcl.uniqueid) as calls_handled,
    SUM(vcl.talk_time) as total_talk_time,
    ROUND(AVG(vcl.talk_time), 2) as avg_talk_time,
    COUNT(DISTINCT CASE WHEN vcl.status = 'SALE' THEN vcl.uniqueid END) as sales,
    ROUND(COUNT(DISTINCT CASE WHEN vcl.status = 'SALE' THEN vcl.uniqueid END) / COUNT(DISTINCT vcl.uniqueid) * 100, 2) as sales_percentage,
    MIN(vcl.call_date) as first_call,
    MAX(vcl.call_date) as last_call
FROM 
    vicidial_closer_log vcl
    LEFT JOIN vicidial_users vu ON vcl.user = vu.user
WHERE 
    vcl.call_date >= DATE_SUB(CURDATE(), INTERVAL 7 DAY)
    AND vcl.call_date < CURDATE()
    AND vcl.status NOT IN ('', 'QUEUE')
    AND vu.user != ''
GROUP BY 
    vcl.user, vu.full_name
ORDER BY 
    calls_handled DESC;

Disposition Breakdown

Understand how calls are being disposed across your system.

SELECT 
    c.campaign_name,
    vl.status as disposition,
    COUNT(vl.uniqueid) as count,
    ROUND(COUNT(vl.uniqueid) / (SELECT COUNT(*) FROM vicidial_log WHERE call_date >= DATE_SUB(CURDATE(), INTERVAL 1 DAY) AND campaign_id = c.campaign_id) * 100, 2) as percentage
FROM 
    vicidial_log vl
    LEFT JOIN vicidial_campaigns c ON vl.campaign_id = c.campaign_id
WHERE 
    vl.call_date >= DATE_SUB(CURDATE(), INTERVAL 1 DAY)
    AND vl.call_date < CURDATE()
    AND vl.status NOT IN ('')
GROUP BY 
    vl.campaign_id, c.campaign_name, vl.status
ORDER BY 
    c.campaign_name, count DESC;

Calls by Hour of Day

Identify peak calling times and staffing patterns.

SELECT 
    HOUR(vl.call_date) as hour_of_day,
    COUNT(vl.uniqueid) as total_calls,
    COUNT(DISTINCT vl.user) as agents_active,
    ROUND(AVG(vl.call_length), 2) as avg_call_length,
    SUM(CASE WHEN vl.status = 'SALE' THEN 1 ELSE 0 END) as sales,
    ROUND(SUM(CASE WHEN vl.status = 'SALE' THEN 1 ELSE 0 END) / COUNT(vl.uniqueid) * 100, 2) as sales_rate
FROM 
    vicidial_log vl
WHERE 
    vl.call_date >= DATE_SUB(CURDATE(), INTERVAL 1 DAY)
    AND vl.call_date < CURDATE()
    AND vl.status NOT IN ('', 'SKIP', 'QUEUE')
GROUP BY 
    HOUR(vl.call_date)
ORDER BY 
    hour_of_day ASC;

DNC Compliance Report

Monitor Do-Not-Call list compliance for regulatory requirements.

SELECT 
    COUNT(DISTINCT CASE WHEN vl.status = 'DNC' THEN vl.phone_number END) as dnc_calls,
    COUNT(DISTINCT vl.phone_number) as unique_numbers_called,
    ROUND(COUNT(DISTINCT CASE WHEN vl.status = 'DNC' THEN vl.phone_number END) / COUNT(DISTINCT vl.phone_number) * 100, 2) as dnc_percentage,
    COUNT(DISTINCT vl.campaign_id) as campaigns_involved
FROM 
    vicidial_log vl
WHERE 
    vl.call_date >= DATE_SUB(CURDATE(), INTERVAL 30 DAY)
    AND vl.status IN ('DNC', 'DNC PERM');

Advanced Query Patterns

Using Window Functions for Ranking

Identify top-performing agents with ranking:

SELECT 
    @rank := @rank + 1 as rank,
    user,
    calls_handled,
    sales,
    sales_percentage
FROM (
    SELECT 
        vcl.user,
        COUNT(DISTINCT vcl.uniqueid) as calls_handled,
        COUNT(DISTINCT CASE WHEN vcl.status = 'SALE' THEN vcl.uniqueid END) as sales,
        ROUND(COUNT(DISTINCT CASE WHEN vcl.status = 'SALE' THEN vcl.uniqueid END) / COUNT(DISTINCT vcl.uniqueid) * 100, 2) as sales_percentage
    FROM 
        vicidial_closer_log vcl
    WHERE 
        vcl.call_date >= DATE_SUB(CURDATE(), INTERVAL 7 DAY)
        AND vcl.call_date < CURDATE()
    GROUP BY 
        vcl.user
    ORDER BY 
        sales_percentage DESC
) as ranked_agents, (SELECT @rank := 0) as init;

Multi-Campaign Comparison

Compare performance metrics across multiple campaigns simultaneously.

SELECT 
    c.campaign_name,
    DATE(vl.call_date) as call_date,
    COUNT(vl.uniqueid) as calls,
    SUM(CASE WHEN vl.status = 'SALE' THEN 1 ELSE 0 END) as sales,
    ROUND(SUM(CASE WHEN vl.status = 'SALE' THEN 1 ELSE 0 END) / COUNT(vl.uniqueid) * 100, 2) as conversion,
    ROUND(AVG(vl.call_length), 2) as avg_length
FROM 
    vicidial_log vl
    LEFT JOIN vicidial_campaigns c ON vl.campaign_id = c.campaign_id
WHERE 
    vl.call_date >= DATE_SUB(CURDATE(), INTERVAL 30 DAY)
    AND c.campaign_id IN ('CAMPAIGN1', 'CAMPAIGN2', 'CAMPAIGN3')
GROUP BY 
    vl.campaign_id, DATE(vl.call_date)
ORDER BY 
    DATE(vl.call_date) DESC, c.campaign_name ASC;

Contact List Activity Report

Track activity on specific contact lists.

SELECT 
    vl.list_id,
    COUNT(DISTINCT vl.phone_number) as unique_contacts,
    COUNT(vl.uniqueid) as total_calls,
    COUNT(DISTINCT CASE WHEN vl.status = 'SALE' THEN vl.phone_number END) as contacts_converted,
    SUM(CASE WHEN vl.status = 'SALE' THEN 1 ELSE 0 END) as total_sales,
    ROUND(SUM(CASE WHEN vl.status = 'SALE' THEN 1 ELSE 0 END) / COUNT(vl.uniqueid) * 100, 2) as sales_rate,
    MIN(vl.call_date) as first_call_date,
    MAX(vl.call_date) as last_call_date
FROM 
    vicidial_log vl
WHERE 
    vl.call_date >= DATE_SUB(CURDATE(), INTERVAL 7 DAY)
    AND vl.list_id IN (SELECT list_id FROM vicidial_list GROUP BY list_id HAVING COUNT(*) > 0)
GROUP BY 
    vl.list_id
ORDER BY 
    total_calls DESC;

Creating Automated Reports

Bash Script for Scheduled Reports

Create a production-ready reporting script that runs via cron.

#!/bin/bash
# /home/vicidial_admin/reports/generate_reports.sh

REPORT_DIR="/home/vicidial_admin/reports"
OUTPUT_DIR="/home/vicidial_admin/reports/outputs"
BACKUP_DIR="/home/vicidial_admin/reports/archive"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
LOG_FILE="/var/log/vicidial_reports.log"

# Ensure directories exist
mkdir -p "$OUTPUT_DIR" "$BACKUP_DIR"

# Function to log messages
log_message() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
}

log_message "Starting ViciDial report generation"

# Generate daily volume report
log_message "Generating daily volume report..."
mysql --defaults-extra-file=~/.my.cnf < "$REPORT_DIR/daily/daily_volume.sql" > "$OUTPUT_DIR/daily_volume_$TIMESTAMP.csv" 2>> "$LOG_FILE"

if [ $? -eq 0 ]; then
    log_message "Daily volume report completed successfully"
else
    log_message "ERROR: Daily volume report failed"
fi

# Generate agent performance report
log_message "Generating agent performance report..."
mysql --defaults-extra-file=~/.my.cnf < "$REPORT_DIR/daily/agent_performance.sql" > "$OUTPUT_DIR/agent_performance_$TIMESTAMP.csv" 2>> "$LOG_FILE"

if [ $? -eq 0 ]; then
    log_message "Agent performance report completed successfully"
else
    log_message "ERROR: Agent performance report failed"
fi

# Clean up old reports (keep 30 days)
log_message "Cleaning up old reports..."
find "$OUTPUT_DIR" -name "*.csv" -mtime +30 -exec mv {} "$BACKUP_DIR" \; >> "$LOG_FILE" 2>&1

log_message "Report generation completed"

Make the script executable:

chmod +x /home/vicidial_admin/reports/generate_reports.sh

Schedule Reports via Cron

Add to root's crontab to run daily at 6 AM:

sudo crontab -e

# Generate ViciDial reports daily at 6 AM
0 6 * * * /home/vicidial_admin/reports/generate_reports.sh

Verify cron job is set:

sudo crontab -l | grep generate_reports

Email Report Delivery

Enhance the bash script to email reports:

#!/bin/bash
# Add this to your generate_reports.sh script

REPORT_DIR="/home/vicidial_admin/reports"
OUTPUT_DIR="/home/vicidial_admin/reports/outputs"
TIMESTAMP=$(date +%Y%m%d)
EMAIL_TO="manager@company.com"
EMAIL_SUBJECT="ViciDial Daily Report - $TIMESTAMP"
HOSTNAME=$(hostname)

# Generate reports first
mysql --defaults-extra-file=~/.my.cnf < "$REPORT_DIR/daily/daily_volume.sql" > "$OUTPUT_DIR/daily_volume_$TIMESTAMP.csv"

# Create email body
cat > /tmp/email_body.txt << EOF
ViciDial Daily Report
Generated: $(date)
Hostname: $HOSTNAME

Daily Call Volume Summary:
$(head -20 "$OUTPUT_DIR/daily_volume_$TIMESTAMP.csv")

Full reports attached.
EOF

# Send email with attachment
mail -s "$EMAIL_SUBJECT" \
     -a "From: vicidial@$HOSTNAME" \
     -a "$OUTPUT_DIR/daily_volume_$TIMESTAMP.csv" \
     "$EMAIL_TO" < /tmp/email_body.txt

rm /tmp/email_body.txt

Performance Optimization

Index Strategy for Reporting Queries

Check existing indexes:

SHOW INDEX FROM vicidial_log;
SHOW INDEX FROM vicidial_closer_log;

Add critical indexes for reporting if missing:

-- For call_date filtering (most common)
ALTER TABLE vicidial_log ADD INDEX idx_call_date (call_date);

-- For campaign filtering
ALTER TABLE vicidial_log ADD INDEX idx_campaign_id (campaign_id);

-- For user filtering
ALTER TABLE vicidial_closer_log ADD INDEX idx_closer_user (user, call_date);

-- Combined index for date range and campaign queries
ALTER TABLE vicidial_log ADD INDEX idx_campaign_date (campaign_id, call_date);

-- Verify indexes are created
SHOW INDEX FROM vicidial_log\G

Query Performance Testing

Use EXPLAIN to analyze query execution:

EXPLAIN 
SELECT 
    COUNT(*) as calls,
    SUM(call_length) as total_time
FROM 
    vicidial_log
WHERE 
    call_date >= DATE_SUB(CURDATE(), INTERVAL 1 DAY)
    AND campaign_id = 'CAMPAIGN1';

Expected output should show:

Type: range or ref (not ALL)
Rows: Should be reasonably small relative to table size
Extra: Should not say "Using temporary" or "Using filesort"

Archive Old Data

For very large databases, archive records older than 1 year:

#!/bin/bash
# Archive reports to separate database for historical analysis

ARCHIVE_DB="asterisk_archive"
RETENTION_DAYS=365

mysql << 'EOF'
-- Create archive table if not exists
CREATE TABLE IF NOT EXISTS ${ARCHIVE_DB}.vicidial_log_archive LIKE asterisk.vicidial_log;

-- Copy old records to archive
INSERT INTO ${ARCHIVE_DB}.vicidial_log_archive
SELECT * FROM asterisk.vicidial_log
WHERE call_date < DATE_SUB(NOW(), INTERVAL ${RETENTION_DAYS} DAY);

-- Delete archived records from main table
DELETE FROM asterisk.vicidial_log
WHERE call_date < DATE_SUB(NOW(), INTERVAL ${RETENTION_DAYS} DAY);

-- Optimize table to reclaim space
OPTIMIZE TABLE asterisk.vicidial_log;
EOF

Integration with ViciDial Web Interface

Custom Report Module Integration

ViciDial allows custom reports via the admin interface. Place your report script in the correct directory:

cat > /var/www/html/vicidial/admin/custom_reports.php << 'EOF'
<?php
// Simple custom report viewer for ViciDial

$db = mysqli_connect('localhost', 'vicidial_reports', 'password', 'asterisk');

if (!$db) {
    die("Database connection failed: " . mysqli_connect_error());
}

// Sanitize input
$report_type = isset($_GET['type']) ? mysqli_real_escape_string($db, $_GET['type']) : 'daily_volume';
$days = isset($_GET['days']) ? intval($_GET['days']) : 1;

// Simple report queries
$queries = array(
    'daily_volume' => "
        SELECT 
            c.campaign_name,
            COUNT(vl.uniqueid) as calls,
            SUM(CASE WHEN vl.status = 'SALE' THEN 1 ELSE 0 END) as sales
        FROM vicidial_log vl
        LEFT JOIN vicidial_campaigns c ON vl.campaign_id = c.campaign_id
        WHERE vl.call_date >= DATE_SUB(CURDATE(), INTERVAL $days DAY)
        GROUP BY vl.campaign_id
        ORDER BY calls DESC
    ",
    'agent_performance' => "
        SELECT 
            vcl.user,
            COUNT(vcl.uniqueid) as calls,
            SUM(vcl.talk_time) as talk_time,
            COUNT(CASE WHEN vcl.status = 'SALE' THEN 1 END) as sales
        FROM vicidial_closer_log vcl
        WHERE vcl.call_date >= DATE_SUB(CURDATE(), INTERVAL $days DAY)
        GROUP BY vcl.user
        ORDER BY calls DESC
    "
);

if (isset($queries[$report_type])) {
    $result = mysqli_query($db, $queries[$report_type]);

    echo "<table border='1'>";

    // Print header
    $row = mysqli_fetch_assoc($result);
    echo "<tr>";
    foreach ($row as $key => $value) {
        echo "<th>$key</th>";
    }
    echo "</tr>";

    // Print rows
    echo "<tr>";
    foreach ($row as $value) {
        echo "<td>$value</td>";
    }
    echo "</tr>";

    while ($row = mysqli_fetch_assoc($result)) {
        echo "<tr>";
        foreach ($row as $value) {
            echo "<td>$value</td>";
        }
        echo "</tr>";
    }

    echo "</table>";
}

mysqli_close($db);
?>
EOF

chmod 644 /var/www/html/vicidial/admin/custom_reports.php

Access the report at: http://your-vicidial-server/vicidial/admin/custom_reports.php?type=daily_volume&days=7

Troubleshooting

Database Connection Issues

Problem: "Can't connect to MySQL server"

Solution:

# Check MySQL service status
systemctl status mysql

# Verify credentials
mysql -u vicidial_reports -p -e "SELECT 1;"

# Check user permissions
mysql -u root -p -e "SHOW GRANTS FOR 'vicidial_reports'@'localhost';"

# Review MySQL error log
tail -50 /var/log/mysql/error.log

Slow Query Performance

Problem: Report queries taking too long (>10 seconds)

Solution:

# Enable query logging
mysql -u root -p -e "SET GLOBAL slow_query_log = 'ON';"
mysql -u root -p -e "SET GLOBAL long_query_time = 5;"

# Check slow query log
tail -100 /var/log/mysql/slow.log

# Run EXPLAIN on slow queries
mysql << 'EOF'
SET SESSION sql_mode='';
EXPLAIN SELECT ... FROM ... WHERE ...;
EOF

# Create missing indexes based on EXPLAIN results
ALTER TABLE vicidial_log ADD INDEX idx_analysis (campaign_id, call_date);

Inconsistent Report Data

Problem: Different results when running the same report twice

Solution:

-- Check for locking issues
SHOW OPEN TABLES WHERE in_use > 0;

-- Check table integrity
CHECK TABLE vicidial_log;
REPAIR TABLE vicidial_log;

-- Verify data consistency
SELECT COUNT(*) FROM vicidial_log WHERE call_date IS NULL;
SELECT COUNT(*) FROM vicidial_log WHERE status = '';

High Memory Usage During Report Generation

Problem: Server runs out of memory when generating large reports

Solution:

# Break report into smaller date ranges
# Instead of 365 days at once, do monthly:

for month in {1..12}; do
    START_DATE="2024-$(printf '%02d' $month)-01"
    END_DATE="2024-$(printf '%02d' $((month+1)))-01"

    mysql << EOF
SELECT * FROM vicidial_log 
WHERE call_date >= '$START_DATE' 
  AND call_date < '$END_DATE'
INTO OUTFILE '/tmp/report_$month.csv';
EOF
done

Missing Data in Reports

Problem: Report shows fewer calls than expected

Solution:

-- Check for NULL campaigns
SELECT COUNT(*) FROM vicidial_log WHERE campaign_id IS NULL OR campaign_id = '';

-- Verify date range filter
SELECT MIN(call_date), MAX(call_date) FROM vicidial_log;

-- Check status filters in query
SELECT DISTINCT status FROM vicidial_log LIMIT 20;

-- Ensure no excluded statuses
SELECT status, COUNT(*) FROM vicidial_log 
WHERE call_date >= DATE_SUB(CURDATE(), INTERVAL 1 DAY)
GROUP BY status;

Summary

Creating custom ViciDial reports with SQL requires understanding the database schema, mastering JOIN operations, and implementing performance optimizations. Key takeaways:

Essential Skills:

Master the vicidial_log, vicidial_closer_log, and vicidial_users tables
Use proper date filtering with call_date for accurate period-based reports
Leverage GROUP BY and aggregate functions for summarization
Implement indexes on frequently queried columns (campaign_id, call_date, user)

Production Best Practices:

Create dedicated read-only database users for reporting
Schedule reports via cron for consistent delivery
Monitor query performance with EXPLAIN and slow query logs
Archive old data to maintain query speed
Validate data consistency regularly

Common Mistakes to Avoid:

Forgetting to filter out empty or test statuses
Not joining with vicidial_campaigns/vicidial_users tables
Running reports without date range filters (inefficient)
Ignoring NULL values in campaign_id or user fields
Failing to account for time zone differences in call_date

Next Steps:

Start with pre-built queries from this guide
Test queries on non-peak hours first
Create backup indexes for high-frequency report queries
Document your custom queries in version control
Monitor execution time and optimize based on EXPLAIN analysis
Integrate with ViciDial's admin interface for user accessibility
Set up automated email delivery for stakeholder reports
Establish data retention and archival policies

With these fundamentals, you can build enterprise-grade reporting solutions that give real-time insights into your ViciDial call center operations.

How to Set Up ViciDial Auto-Dial (Predictive, Ratio & Progressive)

Moisi Trungu — Fri, 14 Aug 2026 03:30:04 +0000

How to Set Up ViciDial Auto-Dial (Predictive, Ratio & Progressive)

Master ViciDial's three auto-dial modes with production-ready configurations, database tuning, and real-world troubleshooting for enterprise call centers

Prerequisites

Before proceeding, ensure you have:

ViciDial 2.14+ installed and running (check via asterisk -rx "core show version")
MySQL/MariaDB access to the asterisk database
Asterisk 11+ or higher with DAHDI/SIP trunks configured
Root or sudo access on the ViciDial server
A working inbound/outbound carrier with available channels
At least 3-5 agents trained and ready to test
Backup of your asterisk database (mysqldump asterisk > backup_$(date +%Y%m%d).sql)

Understanding ViciDial Auto-Dial Modes

ViciDial offers three fundamentally different calling strategies:

Predictive Dialing: System dials before agent is available. AI-driven pacing predicts agent availability and adjusts dial rate dynamically.
Ratio-Based Dialing: Fixed multiplier applied to available agents (e.g., 3:1 = 3 dials per agent). Simple, predictable, less sophisticated.
Progressive Dialing: Agent initiates dial manually or via single-click. Lowest abandonment rates, highest agent idle time.

Each mode has different CPU, database, and channel requirements. Predictive uses the most resources but achieves highest contact rates.

Section 1: Database Configuration & Prerequisites

Create Your Campaign

Access the ViciDial admin interface:

# SSH into your ViciDial server
ssh -i your_key.pem root@vicidial.example.com

# Verify MySQL connectivity
mysql -u root -p asterisk -e "SELECT * FROM vicidial_campaigns LIMIT 1;"

Insert a new campaign via admin panel (/vicidial/admin.php) or via MySQL:

USE asterisk;

INSERT INTO vicidial_campaigns (
  campaign_id,
  campaign_name,
  campaign_description,
  dial_method,
  phone_number_format,
  dispo_group_id,
  campaign_status,
  auto_dial_level,
  dial_timeout,
  call_volume_group,
  lead_recycle_method,
  drop_percentage,
  local_call_time,
  min_ingroup_agents,
  scheduled_callbacks,
  test_call_flag
)
VALUES (
  'PREDICTIVE_01',
  'Predictive Campaign Test',
  'High-volume predictive outbound campaign',
  'INBOUND',
  'US',
  '1',
  'ACTIVE',
  '0.8',
  '45',
  'default',
  'DISABLED',
  '5',
  'GMT',
  '1',
  'ENABLED',
  'N'
);

Key field explanations:

dial_method: INBOUND (most common), BLENDED, CALLBACK
auto_dial_level: 0.1–1.0 (0.8 recommended for predictive; 0.3 for progressive)
drop_percentage: Acceptable % of calls dropped due to no-agent availability (5-10% standard)
dial_timeout: Seconds to wait for answer before abandoning

Configure Dialing Parameters

Update the vicidial_campaigns table with auto-dial specifics:

UPDATE vicidial_campaigns 
SET auto_dial_level = 0.8,
    dial_timeout = 45,
    drop_percentage = 8,
    scheduled_callbacks = 'ENABLED'
WHERE campaign_id = 'PREDICTIVE_01';

Verify the campaign is properly configured:

mysql -u root -p asterisk -e "SELECT campaign_id, campaign_name, dial_method, auto_dial_level, drop_percentage FROM vicidial_campaigns WHERE campaign_id = 'PREDICTIVE_01';"

Section 2: Asterisk SIP/Carrier Configuration

Configure Outbound Carrier Trunks

Edit the carrier configuration in /etc/asterisk/sip-vicidial.conf:

[CARRIER_OUTBOUND_01](!)
type=friend
host=123.45.67.89
port=5060
secret=YourSecretPassword123
fromuser=vicidial
fromdomain=123.45.67.89
dtmfmode=rfc2833
disallow=all
allow=ulaw,alaw
context=from-internal
qualify=yes
qualify_freq=60
maxcallbitrate=128
nat=no
canreinvite=no
directmedia=no
progressinband=yes

Create a production-safe carrier entry:

[carrier_sirius](CARRIER_OUTBOUND_01)
host=carrier.sirius.com
secret=SiriusCarrierSecret999
fromuser=vicidial_client_001
fromdomain=carrier.sirius.com

Configure Dial Plan Extensions

Edit /etc/asterisk/extensions-vicidial.conf to add outbound dialing routes:

[from-internal]
exten => _1NXXNXXXXXX,1,NoOp(ViciDial Outbound - ${EXTEN})
same => n,Set(CHANNEL(hangup_handler_push)=hangup,s,1)
same => n,Dial(SIP/${EXTEN}@carrier_sirius,45,TtKk)
same => n,Hangup()
same => n,Busy()
same => n,Unavailable()

Load and Verify Asterisk Configuration

# Backup current config
cp /etc/asterisk/extensions-vicidial.conf /etc/asterisk/extensions-vicidial.conf.backup

# Reload Asterisk dialplan
asterisk -rx "dialplan reload"

# Check for syntax errors
asterisk -rx "dialplan show from-internal" | head -20

# Verify carrier registration
asterisk -rx "sip show peers" | grep carrier_sirius

Expected output should show your carrier with UNREACHABLE or OK status (OK is ideal):

carrier_sirius/1234567890    123.45.67.89:5060      D   yes          yes     OK

Section 3: Predictive Dialing Setup

Understanding Predictive Algorithm

ViciDial's predictive dialer uses a dynamic pacing algorithm. The system:

Monitors agent availability in real-time
Dials calls ahead of agent availability
Adjusts dial rate based on answer rates, talk time, and wrap-up time
Aims to minimize agent idle time while staying within drop percentage limits

Set Campaign to Predictive Mode

Access /vicidial/admin.php → Campaigns → Select your campaign → Edit

Or update via SQL:

UPDATE vicidial_campaigns 
SET 
  dial_method = 'INBOUND',
  auto_dial_level = 0.85,
  drop_percentage = 8,
  scheduled_callbacks = 'ENABLED',
  lead_recycle_method = 'DISABLED',
  pause_dialing = 'N'
WHERE campaign_id = 'PREDICTIVE_01';

Configure Predictive Parameters in vicidial_settings

Edit the ViciDial system settings table:

UPDATE vicidial_settings 
SET 
  predictive_dialer_flag = '1',
  predictive_answer_rate = '45',
  predictive_drop_rate_threshold = '3',
  predictive_cpu_limit = '90',
  outbound_autodial = '1'
WHERE setting_name = 'ViciDial';

Parameter definitions:

predictive_dialer_flag: 1 = enable, 0 = disable
predictive_answer_rate: Expected % of calls that connect (e.g., 45%)
predictive_drop_rate_threshold: Pause dialing if drop rate exceeds this %
predictive_cpu_limit: CPU threshold before throttling dials

Configure the Predictive Dialer Service

The ViciDial Predictive Dialer runs as a background service. Check if it's active:

# Check if vicidial_dialer.pl is running
ps aux | grep vicidial_dialer.pl | grep -v grep

# If not running, start it manually
/usr/share/astguiclient/vicidial_dialer.pl > /var/log/asterisk/vicidial_dialer.log 2>&1 &

# Make permanent via cron (check root crontab)
crontab -e

# Add this line to restart dialer if it crashes:
* * * * * /usr/share/astguiclient/check_vicidial_process.sh > /dev/null 2>&1

Create Campaign-Specific Lead Lists

Prepare your phone number list. Insert leads into the vicidial_list table:

USE asterisk;

INSERT INTO vicidial_list (
  lead_id,
  lead_phone_number,
  lead_phone_number_2,
  first_name,
  last_name,
  email,
  campaign_id,
  list_id,
  vendor_lead_code,
  status,
  phone_code,
  phone_number_formatted
)
VALUES
(NULL, '5551234567', '', 'John', 'Doe', 'john@example.com', 'PREDICTIVE_01', '1', 'CODE001', 'NEW', '555', '555-123-4567'),
(NULL, '5559876543', '', 'Jane', 'Smith', 'jane@example.com', 'PREDICTIVE_01', '1', 'CODE002', 'NEW', '555', '555-987-6543'),
(NULL, '5552223333', '', 'Bob', 'Johnson', 'bob@example.com', 'PREDICTIVE_01', '1', 'CODE003', 'NEW', '555', '555-222-3333');

-- Verify insertion
SELECT COUNT(*) FROM vicidial_list WHERE campaign_id = 'PREDICTIVE_01' AND status = 'NEW';

Monitor Predictive Dialing

In real-time, check the dialer status:

# Monitor dialer queue
asterisk -rx "core show channels concise" | wc -l

# Check dial queue depth
mysql -u root -p asterisk -e "SELECT COUNT(*) as pending_dials FROM vicidial_list WHERE campaign_id = 'PREDICTIVE_01' AND status IN ('NEW', 'QUEUE');"

# Monitor predictive drops
mysql -u root -p asterisk -e "SELECT call_result, COUNT(*) as count FROM vicidial_log WHERE campaign_id = 'PREDICTIVE_01' AND call_date > DATE_SUB(NOW(), INTERVAL 1 HOUR) GROUP BY call_result;"

Section 4: Ratio-Based Dialing Setup

Understanding Ratio Dialing

Ratio (or Power) dialing maintains a fixed multiplier between agents and dials:

3:1 ratio: For every 1 available agent, system dials 3 calls
2:1 ratio: More conservative; 2 dials per available agent
5:1 ratio: Aggressive; higher abandonment but maximum throughput

Formula: Dials Per Minute = (Available Agents) × (Ratio) × (Calls Per Agent Per Minute)

Configure Campaign for Ratio Dialing

Set the auto_dial_level to 0.5 for a moderate ratio approach:

UPDATE vicidial_campaigns 
SET 
  dial_method = 'INBOUND',
  auto_dial_level = 0.50,
  drop_percentage = 12,
  scheduled_callbacks = 'ENABLED',
  pause_dialing = 'N'
WHERE campaign_id = 'RATIO_01';

In the ViciDial admin panel, under "Dialer Settings," configure:

Dial Ratio: 3:1
Dial Timeout: 45 seconds
Drop Percentage Threshold: 12%

Adjust the Dialing Queue Script

Edit /usr/share/astguiclient/vicidial_dialer.pl (or create a wrapper):

# Around line 850, locate the ratio calculation:
# Example modification for stricter ratio control

my $available_agents = $dbh->selectrow_array(
  "SELECT COUNT(*) FROM vicidial_log WHERE campaign_id='$campaign_id' 
   AND call_date > DATE_SUB(NOW(), INTERVAL 10 SECOND)
   AND status IN ('QUEUE', 'INCALL')"
);

my $ratio = 3; # Set your ratio here
my $dials_to_queue = $available_agents * $ratio;

# Queue dials accordingly
for (my $i = 0; $i < $dials_to_queue; $i++) {
  queue_dial_for_agent($campaign_id);
}

Monitor Ratio Dialing Performance

# Check current agent count
mysql -u root -p asterisk -e "
  SELECT 
    COUNT(DISTINCT user) as active_agents,
    COUNT(*) as total_sessions
  FROM vicidial_log 
  WHERE campaign_id = 'RATIO_01' 
  AND call_date > DATE_SUB(NOW(), INTERVAL 5 MINUTE)
  AND status IN ('QUEUE', 'INCALL');
"

# Calculate real-time dial rate
mysql -u root -p asterisk -e "
  SELECT 
    COUNT(*) as calls_last_minute
  FROM vicidial_log 
  WHERE campaign_id = 'RATIO_01' 
  AND call_date > DATE_SUB(NOW(), INTERVAL 1 MINUTE);
"

Section 5: Progressive Dialing Setup

Understanding Progressive Dialing

Progressive dialing is the most conservative:

Agent clicks DIAL button manually (or via macro)
One call per button click
Zero abandon rate (no automatic dialing)
Best for new campaigns or compliance-heavy environments

Configure Campaign for Progressive Mode

UPDATE vicidial_campaigns 
SET 
  dial_method = 'INBOUND',
  auto_dial_level = 0.15,
  drop_percentage = 0,
  scheduled_callbacks = 'ENABLED',
  pause_dialing = 'N'
WHERE campaign_id = 'PROGRESSIVE_01';

Configure Agent Macro for One-Click Dialing

Edit the agent's hotkey configuration in /agc/vicidial.php:

Agent users can assign a dial macro. In ViciDial admin, under "User Settings," set:

Dial Prefix: 0  (Agent dials 0 + number, or auto-fills from lead)
Dial Method: PROGRESSIVE
Auto Dial: Disabled

Or configure via database:

UPDATE vicidial_users 
SET 
  auto_dial_mode = 'PROGRESSIVE',
  auto_dial_level = 0.15,
  auto_call_override = 'OFF'
WHERE user = 'agent_001';

Enable Manual Dial Button in Agent Screen

The standard ViciDial agent screen (/agc/vicidial.php) already includes a DIAL button. Ensure it's enabled:

Log in as an agent
Lead information populates from the list
Agent clicks DIAL button
Call connects to that single lead

No additional configuration is required for basic progressive dialing.

Section 6: Performance Tuning & Optimization

Database Query Optimization

ViciDial relies on frequent database queries. Optimize with proper indexing:

-- Check existing indexes
SHOW INDEX FROM vicidial_log;

-- Add performance indexes if missing
ALTER TABLE vicidial_list 
ADD INDEX idx_campaign_status (campaign_id, status),
ADD INDEX idx_phone_number (lead_phone_number),
ADD INDEX idx_call_date (call_date);

ALTER TABLE vicidial_log 
ADD INDEX idx_campaign_call_date (campaign_id, call_date),
ADD INDEX idx_status_date (status, call_date),
ADD INDEX idx_user_date (user, call_date);

-- Optimize tables after adding indexes
OPTIMIZE TABLE vicidial_log;
OPTIMIZE TABLE vicidial_list;
OPTIMIZE TABLE vicidial_closer_log;

Asterisk Channel Configuration

Increase available channels based on your trunking:

; In /etc/asterisk/sip.conf
[general]
maxforwards=20
udpbindaddr=0.0.0.0
tcpenable=yes
tcpbindaddr=0.0.0.0
tlsenable=no
srvlookup=yes
pedantic=no
maxcallbitrate=256000
autocreatepeer=no
relaxdtmf=yes
rtpholdtimeout=300
rtpkeepalive=no
rtptimeout=7200

CPU and Memory Limits

Monitor resource usage:

# Real-time system monitor
top -p $(pidof asterisk)

# Check memory usage
free -h

# Limit ViciDial processes if needed
ulimit -m 2097152  # 2GB memory limit
ulimit -n 65536    # 65K file descriptors

Optimize vicidial_dialer.pl Performance

Edit /usr/share/astguiclient/vicidial_dialer.pl to reduce query frequency:

# Around line 250, adjust loop sleep interval
my $loop_sleep = 0.5;  # 500ms between dial checks (higher = less CPU)

# Reduce the number of campaigns processed per cycle
my $campaigns_per_cycle = 10;

# Increase batch dial size for efficiency
my $dial_batch_size = 50;

Section 7: Troubleshooting Common Issues

Issue 1: Dialer Not Making Calls

Symptoms: Campaign active but no calls initiated.

Diagnosis:

# Check if dialer process is running
ps aux | grep vicidial_dialer.pl

# Check error logs
tail -100 /var/log/asterisk/messages | grep -i "dial\|error"

# Verify database connection
mysql -u root -p asterisk -e "SELECT COUNT(*) FROM vicidial_list WHERE campaign_id='PREDICTIVE_01' AND status='NEW';"

# Check Asterisk core
asterisk -rx "core show channels concise" | wc -l

Solutions:

Restart the dialer: killall vicidial_dialer.pl && sleep 2 && /usr/share/astguiclient/vicidial_dialer.pl &
Verify carrier registration: asterisk -rx "sip show peers"
Check campaign status in database: UPDATE vicidial_campaigns SET pause_dialing='N' WHERE campaign_id='PREDICTIVE_01';

Issue 2: High Call Drop Rate

Symptoms: Drop percentage exceeding threshold; caller disconnect before agent connects.

Diagnosis:

# Check drop rate by call result
mysql -u root -p asterisk -e "
  SELECT 
    call_result,
    COUNT(*) as count,
    ROUND(COUNT(*) / (SELECT COUNT(*) FROM vicidial_log WHERE campaign_id='PREDICTIVE_01' AND call_date > DATE_SUB(NOW(), INTERVAL 1 HOUR)) * 100, 2) as percentage
  FROM vicidial_log 
  WHERE campaign_id='PREDICTIVE_01' 
  AND call_date > DATE_SUB(NOW(), INTERVAL 1 HOUR)
  GROUP BY call_result;
"

# Check agent availability
mysql -u root -p asterisk -e "SELECT user, COUNT(*) FROM vicidial_log WHERE campaign_id='PREDICTIVE_01' AND call_date > DATE_SUB(NOW(), INTERVAL 1 HOUR) GROUP BY user;";

Solutions:

Reduce auto_dial_level from 0.85 to 0.70
Increase drop_percentage threshold temporarily
Add more agents to the campaign
Check agent call handling times: SELECT user, AVG(LENGTH_OF_CALL) FROM vicidial_log GROUP BY user;

Issue 3: SIP Carrier Errors / Registration Failures

Symptoms: Carrier shows UNREACHABLE; calls fail with SIP 503.

Diagnosis:

# Check SIP registration
asterisk -rx "sip show registry"

# Test carrier connectivity
asterisk -rx "sip show peer carrier_sirius"

# Check carrier logs
tail -50 /var/log/asterisk/messages | grep -i "sirius\|carrier"

Solutions:

Verify carrier IP and credentials: cat /etc/asterisk/sip-vicidial.conf | grep -A5 carrier_sirius
Check network connectivity: ping -c 5 carrier.sirius.com
Restart SIP channel driver: asterisk -rx "module reload res_sip"

Issue 4: Agent Screen Not Showing Leads

Symptoms: Agent sees blank lead information despite calls in queue.

Diagnosis:

# Check lead list status
mysql -u root -p asterisk -e "SELECT COUNT(*) FROM vicidial_list WHERE campaign_id='PREDICTIVE_01' AND status IN ('NEW', 'QUEUE');";

# Check user campaign assignment
mysql -u root -p asterisk -e "SELECT user, campaign_id FROM vicidial_users WHERE user='agent_001';";

# Verify vicidial.php logs
tail -50 /var/log/apache2/error.log | grep vicidial

Solutions:

Assign user to campaign: UPDATE vicidial_users SET campaign_id='PREDICTIVE_01' WHERE user='agent_001';
Reload agent screen (Ctrl+R or refresh browser)
Clear browser cache and cookies

Issue 5: Calls Dialing to Wrong Number or Format

Symptoms: Calls connecting to incomplete or malformed numbers.

Diagnosis:

# Check last 10 call attempts
mysql -u root -p asterisk -e "
  SELECT 
    lead_id,
    lead_phone_number,
    phone_number_formatted,
    call_result
  FROM vicidial_log 
  WHERE campaign_id='PREDICTIVE_01' 
  ORDER BY call_date DESC LIMIT 10;
";

# Check dial plan
asterisk -rx "dialplan show from-internal"

Solutions:

Verify phone_number_format in campaign: Should be 'US' or 'INTL'
Ensure lead phone numbers in vicidial_list don't include non-numeric characters (except +)
Check extensions-vicidial.conf dial pattern: exten => _1NXXNXXXXXX

Section 8: Production Monitoring & Maintenance

Real-Time Dashboard Query

Create a monitoring script to check campaign health:

#!/bin/bash
# /usr/local/bin/vicidial_monitor.sh

CAMPAIGN="PREDICTIVE_01"
INTERVAL=60

while true; do
  echo "=== ViciDial Campaign Status: $CAMPAIGN ==="
  echo "Time: $(date)"

  mysql -u root -p asterisk -e "
    SELECT 
      'Active Agents' as metric, COUNT(DISTINCT user) as value 
    FROM vicidial_log 
    WHERE campaign_id='$CAMPAIGN' 
    AND call_date > DATE_SUB(NOW(), INTERVAL 5 MINUTE)
    AND status IN ('QUEUE', 'INCALL')
    UNION ALL
    SELECT 
      'Channels In Use', COUNT(*) 
    FROM vicidial_log 
    WHERE campaign_id='$CAMPAIGN' 
    AND call_date > DATE_SUB(NOW(), INTERVAL 5 MINUTE)
    UNION ALL
    SELECT 
      'Leads Pending', COUNT(*) 
    FROM vicidial_list 
    WHERE campaign_id='$CAMPAIGN' AND status='NEW'
    UNION ALL
    SELECT 
      'Avg Talk Time (sec)', ROUND(AVG(LENGTH_OF_CALL)) 
    FROM vicidial_log 
    WHERE campaign_id='$CAMPAIGN' 
    AND call_date > DATE_SUB(NOW(), INTERVAL 1 HOUR)
    AND call_result='SALE';
  "

  echo ""
  sleep $INTERVAL
done

Run the script:

chmod +x /usr/local/bin/vicidial_monitor.sh
/usr/local/bin/vicidial_monitor.sh

Regular Database Maintenance

#!/bin/bash
# /usr/local/bin/vicidial_maintenance.sh

# Backup database daily
mysqldump -u root -p asterisk > /backups/asterisk_$(date +%Y%m%d).sql

# Purge old logs (keep 90 days)
mysql -u root -p asterisk -e "
  DELETE FROM vicidial_log WHERE call_date < DATE_SUB(NOW(), INTERVAL 90 DAY);
  DELETE FROM vicidial_closer_log WHERE call_date < DATE_SUB(NOW(), INTERVAL 90 DAY);
  OPTIMIZE TABLE vicidial_log;
  OPTIMIZE TABLE vicidial_closer_log;
"

# Report on campaign performance
mysql -u root -p asterisk -e "
  SELECT 
    campaign_id,
    DATE(call_date) as date,
    COUNT(*) as total_calls,
    SUM(CASE WHEN call_result='SALE' THEN 1 ELSE 0 END) as sales,
    SUM(CASE WHEN call_result='DROPPED' THEN 1 ELSE 0 END) as dropped,
    ROUND(SUM(CASE WHEN call_result='DROPPED' THEN 1 ELSE 0 END) / COUNT(*) * 100, 2) as drop_rate_percent
  FROM vicidial_log
  WHERE call_date > DATE_SUB(NOW(), INTERVAL 7 DAY)
  GROUP BY campaign_id, DATE(call_date)
  ORDER BY campaign_id, date DESC;
" > /var/log/vicidial_daily_report.txt

Schedule in crontab:

crontab -e

# Add:
0 2 * * * /usr/local/bin/vicidial_maintenance.sh > /dev/null 2>&1

Summary

This tutorial covered the complete setup and tuning of ViciDial's three auto-dial modes:

Predictive Dialing provides the highest contact rate and throughput by predicting agent availability and dialing ahead. Ideal for high-volume campaigns where some call drops are acceptable. Requires careful monitoring of drop rates and CPU usage.

Ratio-Based Dialing maintains fixed dial multipliers (e.g., 3:1) per available agent. More predictable than predictive; suitable for mid-range campaigns. Requires less tuning but achieves lower contact rates than predictive.

Progressive Dialing offers zero abandonment by requiring manual agent dial actions. Best for compliance-heavy environments and new campaigns. Maximizes agent control but minimizes throughput.

Key implementation steps:

Create campaigns and leads in the asterisk database
Configure SIP carriers and Asterisk dialplan
Enable the vicidial_dialer.pl background service
Set auto_dial_level, drop_percentage, and dial_timeout per mode
Optimize database indexes and Asterisk channel limits
Monitor via SQL queries, Asterisk CLI, and real-time dashboards
Troubleshoot using logs, database diagnostics, and SIP peer status checks
Maintain via regular backups, log rotation, and performance reports

Production deployments benefit from starting conservative (lower dial rates, higher drop thresholds) and gradually increasing intensity while monitoring agent satisfaction, call quality, and network capacity. Always maintain backups and test configuration changes in a staging environment first.

For enterprise setups, consider implementing load balancing across multiple ViciDial servers and using dedicated trunk capacity with your carrier to ensure reliable, scalable operation.

How to Upload a Lead List to ViciDial — CSV Format & Mapping

Moisi Trungu — Thu, 13 Aug 2026 03:30:03 +0000

How to Upload a Lead List to ViciDial — CSV Format & Mapping

Master the complete process of importing lead lists into ViciDial with proper CSV formatting, field mapping, and validation techniques to avoid common import failures in production environments.

Prerequisites

Before uploading a lead list to ViciDial, ensure you have the following:

ViciDial installation (tested on 2.14.x and later)
Admin access to the web interface (/vicidial/admin.php)
Database credentials for the asterisk database
Sufficient disk space in /var/spool/vicidial/LEADS_IN/ (typically 5GB+ for large lists)
Linux command-line access to the ViciDial server
Campaign already created in ViciDial (required before list assignment)
MySQL/MariaDB client installed on your local machine (if importing via SSH tunnel)
Basic understanding of CSV format and field delimiters

Understanding ViciDial Lead List Structure

Core Lead Tables

ViciDial stores lead data primarily in two tables:

-- Main lead table
SHOW CREATE TABLE vicidial_list\G

-- This shows the structure containing:
-- lead_id (primary key, auto-increment)
-- phone_number (VARCHAR 20)
-- first_name, last_name, address, city, state, postal_code
-- email, vendor_lead_code, source_id
-- list_id (foreign key to campaign list)
-- status (NEW, ACTIVE, etc.)
-- gmt_offset_now (for timezone handling)

The most critical fields for import are:

phone_number – Required; primary dialing field
list_id – Links lead to campaign
first_name, last_name – Optional but recommended for agent context
email – Optional but valuable for callback/document delivery
vendor_lead_code – Unique external identifier; prevents duplicates
source_id – Tracks lead source for compliance/analytics
gmt_offset_now – Critical for timezone-aware calling windows

List Management in ViciDial

Campaigns in ViciDial are containers with associated lists. Each campaign can have multiple lists, and each list contains leads.

-- View existing campaigns
SELECT campaign_id, campaign_name, active, dial_method 
FROM vicidial_campaigns 
LIMIT 10;

-- View lists under a campaign
SELECT list_id, campaign_id, list_name, lead_count 
FROM vicidial_lists 
WHERE campaign_id = 'TEST_CAMPAIGN';

Preparing Your CSV File

CSV Format Specifications

ViciDial expects a specific CSV structure with proper field ordering and encoding.

phone_number,first_name,last_name,email,vendor_lead_code,source_id,gmt_offset_now
5551234567,John,Doe,john@example.com,VND-123456,WEB,America/New_York
5559876543,Jane,Smith,jane@example.com,VND-123457,PHONE,America/Chicago
5559998888,Bob,Johnson,bob@example.com,VND-123458,REFERRAL,America/Los_Angeles

Required vs. Optional Fields

Required fields:

phone_number – E.164 or 10-digit format (ViciDial accepts both)

Strongly recommended:

first_name – Improves agent interaction quality
vendor_lead_code – Prevents duplicate imports
gmt_offset_now – Essential for respecting TCPA calling windows

Optional but useful:

last_name, email, address, city, state, postal_code
source_id – Track which source generated the lead
Custom fields (if your ViciDial instance uses extended schema)

CSV Field Mapping Reference

Here's the complete list of importable fields and their SQL column equivalents:

CSV Field Name          | SQL Table Column    | Data Type    | Max Length
phone_number            | phone_number        | VARCHAR(20)  | 20
first_name              | first_name          | VARCHAR(50)  | 50
last_name               | last_name           | VARCHAR(50)  | 50
middle_initial          | middle_initial      | VARCHAR(1)   | 1
address                 | address             | VARCHAR(100) | 100
city                    | city                | VARCHAR(50)  | 50
state                   | state               | VARCHAR(2)   | 2
postal_code             | postal_code         | VARCHAR(10)  | 10
country_code            | country_code        | VARCHAR(3)   | 3
email                   | email               | VARCHAR(100) | 100
vendor_lead_code        | vendor_lead_code    | VARCHAR(20)  | 20
source_id               | source_id           | VARCHAR(50)  | 50
gmt_offset_now          | gmt_offset_now      | VARCHAR(10)  | 10
phone_code              | phone_code          | VARCHAR(20)  | 20
lead_source_id          | lead_source_id      | VARCHAR(20)  | 20

CSV Validation Rules

Before uploading, validate your CSV meets these requirements:

No header row – ViciDial list upload expects data rows only (headers are optional in UI but not recommended)
Consistent field count – Every row must have the same number of columns
Proper encoding – UTF-8 without BOM
Phone number format – 10+ digits, no spaces/dashes in raw CSV (formatting applied on import)
No embedded newlines – Use proper CSV escaping if fields contain commas
File size limits – Practical limit 50MB per file; split larger lists

Creating a Validation Script

#!/bin/bash
# validate_csv.sh - Pre-import CSV validation

CSV_FILE="$1"

if [ ! -f "$CSV_FILE" ]; then
    echo "ERROR: File not found: $CSV_FILE"
    exit 1
fi

# Check file encoding
FILE_ENCODING=$(file -b --mime-encoding "$CSV_FILE")
if [ "$FILE_ENCODING" != "utf-8" ]; then
    echo "WARNING: File encoding is $FILE_ENCODING, expected utf-8"
fi

# Count lines
LINE_COUNT=$(wc -l < "$CSV_FILE")
echo "Total lines: $LINE_COUNT"

# Check for consistent field count (assuming comma-delimited)
FIRST_LINE_FIELDS=$(head -1 "$CSV_FILE" | awk -F',' '{print NF}')
echo "Expected fields per row: $FIRST_LINE_FIELDS"

# Validate all rows have same field count
INVALID_ROWS=$(awk -F',' -v expected=$FIRST_LINE_FIELDS '{
    if (NF != expected) print NR": expected "$FIRST_LINE_FIELDS", got "NF
}' "$CSV_FILE")

if [ -n "$INVALID_ROWS" ]; then
    echo "ERROR: Found rows with inconsistent field counts:"
    echo "$INVALID_ROWS"
    exit 1
fi

# Extract and validate phone numbers (column 1)
INVALID_PHONES=$(awk -F',' '{
    gsub(/[^0-9]/, "", $1)
    if (length($1) < 10) print NR": invalid phone "$1
}' "$CSV_FILE")

if [ -n "$INVALID_PHONES" ]; then
    echo "WARNING: Found potentially invalid phone numbers:"
    echo "$INVALID_PHONES" | head -20
fi

echo "Validation complete!"

Usage:

chmod +x validate_csv.sh
./validate_csv.sh leads.csv

Uploading via Web Interface

Step-by-Step Web Upload

Log into ViciDial Admin Interface:

   https://your-vicidial-server/vicidial/admin.php

Navigate to List Management:
- Click Campaigns → Lists (or Leads in newer versions)
- Select the target campaign from the dropdown
Create New List (if needed):
- Click Create List button
- Enter list name (e.g., "Q4_2024_Leads")
- Set list priority (higher = called first)
- Click Add List
Upload Leads to List:
- Select the list from the dropdown
- Click Upload Leads button
- Choose CSV file from local machine
- Important: Configure field mapping (see next section)

Field Mapping Configuration

When you upload a CSV, ViciDial prompts you to map columns to database fields.

ViciDial Upload Field Mapping Dialog:

CSV Column 1 → phone_number (REQUIRED)
CSV Column 2 → first_name
CSV Column 3 → last_name
CSV Column 4 → email
CSV Column 5 → vendor_lead_code
CSV Column 6 → source_id
CSV Column 7 → gmt_offset_now

[Checkbox] Skip first row as header
[Checkbox] Replace existing leads
[Checkbox] Auto-detect duplicates by phone_number

[UPLOAD LEADS]

Critical mapping tips:

Leave unused columns unmapped (set to "— ignore —")
Ensure phone_number is always mapped to Column 1
If your CSV has a header row, check "Skip first row as header"
Leave "Replace existing leads" unchecked unless you're refreshing the entire list

Command-Line Upload Method

For production environments and large-scale imports, use the CLI approach which is faster and more scriptable.

Using the ViciDial Import Script

ViciDial includes a Perl script for direct database imports:

# Location of import script
/usr/share/astguiclient/VICIDIAL_add_lead_list.pl

# Basic syntax
perl /usr/share/astguiclient/VICIDIAL_add_lead_list.pl \
  --listname "Q4_2024_Leads" \
  --campaign "TEST_CAMPAIGN" \
  --file "leads.csv" \
  --phonefield 1 \
  --firstnamefield 2 \
  --lastnamefield 3 \
  --emailfield 4 \
  --vendorfield 5 \
  --sourcefield 6 \
  --tzfield 7

Complete CLI Import Example

#!/bin/bash
# import_leads.sh - Production lead import script

CAMPAIGN="TEST_CAMPAIGN"
LIST_NAME="$(date +%Y%m%d)_import"
CSV_FILE="leads.csv"
DB_HOST="localhost"
DB_USER="cron"
DB_PASS="1234"
DB_NAME="asterisk"

# Validate file
if [ ! -f "$CSV_FILE" ]; then
    echo "ERROR: CSV file not found: $CSV_FILE"
    exit 1
fi

# Count leads
LEAD_COUNT=$(wc -l < "$CSV_FILE")
echo "Importing $LEAD_COUNT leads to campaign: $CAMPAIGN"

# Run import
perl /usr/share/astguiclient/VICIDIAL_add_lead_list.pl \
    --listname "$LIST_NAME" \
    --campaign "$CAMPAIGN" \
    --file "$CSV_FILE" \
    --phonefield 1 \
    --firstnamefield 2 \
    --lastnamefield 3 \
    --emailfield 4 \
    --vendorfield 5 \
    --sourcefield 6 \
    --tzfield 7 \
    --dbhost "$DB_HOST" \
    --dbuser "$DB_USER" \
    --dbpass "$DB_PASS" \
    --dbname "$DB_NAME" \
    --active "Y" \
    --skipdup "Y" \
    2>&1 | tee import_$(date +%s).log

echo "Import complete. Check log for details."

Direct MySQL Import

For advanced users, direct SQL insertion can be faster for very large lists (10M+ leads):

#!/bin/bash
# direct_sql_import.sh - Ultra-high-volume import

CSV_FILE="$1"
CAMPAIGN_ID="TEST_CAMPAIGN"
LIST_ID="9001"

# Create staging table
mysql -h localhost -u cron -p1234 asterisk << 'EOF'
CREATE TEMPORARY TABLE vicidial_list_staging LIKE vicidial_list;
EOF

# Load CSV into staging table
mysql -h localhost -u cron -p1234 asterisk << EOF
LOAD DATA LOCAL INFILE '$CSV_FILE'
INTO TABLE vicidial_list_staging
FIELDS TERMINATED BY ','
LINES TERMINATED BY '\n'
(phone_number, first_name, last_name, email, vendor_lead_code, source_id, gmt_offset_now);
EOF

# Insert from staging to production, skipping duplicates
mysql -h localhost -u cron -p1234 asterisk << EOF
INSERT INTO vicidial_list 
  (phone_number, first_name, last_name, email, vendor_lead_code, 
   source_id, gmt_offset_now, list_id, campaign_id, status, entry_date)
SELECT 
  phone_number, first_name, last_name, email, vendor_lead_code,
  source_id, gmt_offset_now, $LIST_ID, '$CAMPAIGN_ID', 'NEW', NOW()
FROM vicidial_list_staging
WHERE phone_number NOT IN (
  SELECT phone_number FROM vicidial_list WHERE list_id = $LIST_ID
)
AND phone_number IS NOT NULL
AND LENGTH(REPLACE(phone_number, REGEXP_SUBSTR(phone_number, '[^0-9]'), '')) >= 10;

-- Update lead count
UPDATE vicidial_lists 
SET lead_count = (SELECT COUNT(*) FROM vicidial_list WHERE list_id = $LIST_ID)
WHERE list_id = $LIST_ID;
EOF

echo "Import complete."

Handling Timezones (Critical for TCPA Compliance)

ViciDial respects Do Not Call (DNC) regulations and time-of-day restrictions based on the gmt_offset_now field.

Timezone Values Reference

phone_number,first_name,last_name,gmt_offset_now
5551234567,John,Doe,America/New_York
5559876543,Jane,Smith,America/Chicago
5559998888,Bob,Johnson,America/Denver
5551112222,Alice,Brown,America/Los_Angeles
5551113333,Charlie,Davis,America/Anchorage
5551114444,Diana,Evans,Pacific/Honolulu

Extracting Timezone from Phone Area Code

#!/bin/bash
# area_code_timezone.sh - Auto-detect timezone from area code

# Create mapping file
cat > area_code_tz.txt << 'EOF'
201|America/New_York
202|America/New_York
203|America/New_York
212|America/New_York
# ... (continue for all area codes)
213|America/Los_Angeles
415|America/Los_Angeles
619|America/Los_Angeles
702|America/Los_Angeles
EOF

# Process CSV with timezone detection
awk -F',' '{
    area_code = substr($1, 1, 3)
    cmd = "grep \"^" area_code "|\" area_code_tz.txt | cut -d\"|\" -f2"
    cmd | getline timezone
    close(cmd)
    if (timezone == "") timezone = "America/Chicago"  # default
    print $0 "," timezone
}' input_leads.csv > leads_with_tz.csv

Duplicate Handling and Lead Deduplication

Preventing Duplicate Imports

ViciDial's vendor_lead_code field is your primary defense against duplicates:

# Before importing, deduplicate by vendor_lead_code
sort -t',' -k5 -u leads.csv > leads_dedup.csv

# Or using awk
awk -F',' '!seen[$5]++' leads.csv > leads_dedup.csv

Checking for Existing Leads

-- Find leads already in the system by vendor_lead_code
SELECT list_id, phone_number, vendor_lead_code, status 
FROM vicidial_list 
WHERE vendor_lead_code IN (
    SELECT vendor_lead_code FROM new_import_list
)
LIMIT 100;

-- Find potential phone duplicates
SELECT phone_number, COUNT(*) as count 
FROM vicidial_list 
WHERE list_id = 9001 
GROUP BY phone_number 
HAVING COUNT(*) > 1;

Automated Deduplication Script

#!/bin/bash
# deduplicate_leads.sh

INPUT_CSV="$1"
OUTPUT_CSV="${INPUT_CSV%.csv}_dedup.csv"

# Extract headers (if present)
HEADERS=$(head -1 "$INPUT_CSV")

# Remove duplicates, preserve first occurrence
(echo "$HEADERS"; tail -n +2 "$INPUT_CSV" | sort -t',' -k5 -u) > "$OUTPUT_CSV"

ORIGINAL_COUNT=$(tail -n +2 "$INPUT_CSV" | wc -l)
DEDUP_COUNT=$(tail -n +2 "$OUTPUT_CSV" | wc -l)
REMOVED=$((ORIGINAL_COUNT - DEDUP_COUNT))

echo "Original leads: $ORIGINAL_COUNT"
echo "After dedup: $DEDUP_COUNT"
echo "Removed duplicates: $REMOVED"
echo "Output: $OUTPUT_CSV"

Monitoring Upload Progress

Checking Upload Status via Database

-- Monitor ongoing import
SELECT 
    list_id,
    campaign_id,
    lead_count,
    last_update_date
FROM vicidial_lists 
WHERE list_id IN (SELECT MAX(list_id) FROM vicidial_lists LIMIT 5)
ORDER BY list_id DESC;

-- Check lead distribution
SELECT status, COUNT(*) as count 
FROM vicidial_list 
WHERE list_id = 9001 
GROUP BY status;

-- Check for import errors
SELECT COUNT(*) 
FROM vicidial_list 
WHERE phone_number IS NULL OR phone_number = '';

Real-Time Import Monitoring

#!/bin/bash
# monitor_import.sh - Watch import progress

LIST_ID="9001"
DB_USER="cron"
DB_PASS="1234"
DB_NAME="asterisk"

while true; do
    CURRENT=$(mysql -h localhost -u "$DB_USER" -p"$DB_PASS" "$DB_NAME" \
        -sN -e "SELECT COUNT(*) FROM vicidial_list WHERE list_id = $LIST_ID;")

    TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
    echo "[$TIMESTAMP] Leads in list: $CURRENT"

    sleep 10
done

Troubleshooting Common Import Issues

Issue: "File Not Found" or Permission Denied

Cause: CSV file not in expected directory or incorrect permissions

Solution:

# Ensure file is readable
chmod 644 leads.csv

# Copy to ViciDial's standard upload directory
cp leads.csv /var/spool/vicidial/LEADS_IN/

# Verify permissions
ls -la /var/spool/vicidial/LEADS_IN/ | grep leads.csv

Issue: "Invalid Phone Number Format"

Cause: Phone numbers contain non-numeric characters or are too short

Solution:

#!/bin/bash
# clean_phones.sh

sed 's/[^0-9,\n]//g' leads.csv > leads_clean.csv

# Verify minimum 10 digits
awk -F',' '{
    gsub(/[^0-9]/, "", $1)
    if (length($1) >= 10) print $0
}' leads_clean.csv > leads_valid.csv

Issue: "Field Mapping Mismatch" or Blank Imports

Cause: Incorrect field mapping or CSV column order mismatch

Solution:

Verify your CSV columns match your mapping:

# Show first row with column numbers
head -1 leads.csv | awk -F',' '{for(i=1;i<=NF;i++) print i": "$i}'

# Expected output should match your mapping:
# 1: phone_number
# 2: first_name
# 3: last_name
# etc.

Issue: Duplicate Leads Being Imported

Cause: vendor_lead_code not set or duplicate checking disabled

Solution:

# Check if vendor_lead_code is unique
mysql -u cron -p1234 asterisk -e \
  "SELECT vendor_lead_code, COUNT(*) FROM vicidial_list 
   WHERE list_id = 9001 AND vendor_lead_code IS NOT NULL 
   GROUP BY vendor_lead_code HAVING COUNT(*) > 1 LIMIT 20;"

# Enable duplicate checking in future imports via web UI:
# Check: [X] Auto-detect duplicates by phone_number
# Or use CLI: --skipdup "Y"

Issue: Out of Memory During Large Import

Cause: Importing massive lists (>50M leads) with insufficient RAM

Solution:

#!/bin/bash
# batch_import.sh - Split large files into chunks

CSV_FILE="$1"
CHUNK_SIZE=100000
CAMPAIGN="TEST_CAMPAIGN"

TOTAL_LINES=$(wc -l < "$CSV_FILE")
CHUNKS=$((($TOTAL_LINES / $CHUNK_SIZE) + 1))

echo "Splitting $TOTAL_LINES lines into $CHUNKS chunks of $CHUNK_SIZE..."

for i in $(seq 1 $CHUNKS); do
    START=$(( ($i - 1) * $CHUNK_SIZE + 1 ))
    END=$(( $i * $CHUNK_SIZE ))

    CHUNK_FILE="chunk_${i}.csv"
    sed -n "${START},${END}p" "$CSV_FILE" > "$CHUNK_FILE"

    echo "Importing chunk $i: $CHUNK_FILE"

    perl /usr/share/astguiclient/VICIDIAL_add_lead_list.pl \
        --listname "${CAMPAIGN}_$(date +%s)_chunk_$i" \
        --campaign "$CAMPAIGN" \
        --file "$CHUNK_FILE" \
        --phonefield 1 \
        --firstnamefield 2 \
        --lastnamefield 3 \
        --dbhost localhost \
        --dbuser cron \
        --dbpass 1234 \
        --dbname asterisk \
        --active "Y" 2>&1 | tee "import_chunk_${i}.log"

    rm "$CHUNK_FILE"

    sleep 5  # Prevent database strain
done

echo "All chunks imported."

Issue: Leads Show "NEW" Status But Don't Dial

Cause: Campaign not active or dialers not running

Solution:

# Verify campaign is active
mysql -u cron -p1234 asterisk -e \
  "SELECT campaign_id, campaign_name, active FROM vicidial_campaigns 
   WHERE campaign_id = 'TEST_CAMPAIGN';"

# Check if dialers are running
ps aux | grep -E "vicidial_dial|[p]erl.*dial"

# Start ViciDial daemons if stopped
systemctl restart vicidial

# Check for dialer errors in logs
tail -50 /var/log/asterisk/messages | grep -i dial

Issue: Slow Import Speed

Cause: Single-threaded import, high disk I/O, or database lock contention

Solution:

# Check database performance
mysql -u cron -p1234 asterisk -e "SHOW PROCESSLIST;" | grep -i vicidial

# Optimize table before import
mysql -u cron -p1234 asterisk -e "OPTIMIZE TABLE vicidial_list;"

# Increase insert buffer during import
mysql -u cron -p1234 asterisk << EOF
SET SESSION insert_delayed_insert_limit=100000;
SET SESSION bulk_insert_buffer_size=16000000;
EOF

# Use parallel import with multiple chunks
# (See batch_import.sh above)

Database Verification After Import

Post-Import Validation Queries

-- Count total leads imported
SELECT COUNT(*) as total_leads 
FROM vicidial_list 
WHERE list_id = 9001;

-- Verify required fields populated
SELECT 
    COUNT(*) as total,
    SUM(CASE WHEN phone_number IS NULL THEN 1 ELSE 0 END) as missing_phone,
    SUM(CASE WHEN first_name IS NULL THEN 1 ELSE 0 END) as missing_first,
    SUM(CASE WHEN vendor_lead_code IS NULL THEN 1 ELSE 0 END) as missing_vendor_code
FROM vicidial_list 
WHERE list_id = 9001;

-- Check status distribution
SELECT status, COUNT(*) as count 
FROM vicidial_list 
WHERE list_id = 9001 
GROUP BY status 
ORDER BY count DESC;

-- Verify timezone distribution
SELECT gmt_offset_now, COUNT(*) as count 
FROM vicidial_list 
WHERE list_id = 9001 
GROUP BY gmt_offset_now 
ORDER BY count DESC;

-- Find any malformed phone numbers
SELECT phone_number, COUNT(*) 
FROM vicidial_list 
WHERE list_id = 9001 
AND (LENGTH(REPLACE(phone_number, REGEXP_SUBSTR(phone_number, '[^0-9]'), '')) < 10 
     OR phone_number IS NULL)
GROUP BY phone_number;

-- Verify list_id assignment
SELECT campaign_id, list_id, lead_count 
FROM vicidial_lists 
WHERE list_id = 9001;

Production Best Practices

Pre-Import Checklist

#!/bin/bash
# pre_import_checklist.sh

echo "=== ViciDial Pre-Import Checklist ==="

# 1. Backup database
echo "[ ] Backup database"
mysqldump -u cron -p1234 asterisk > backup_$(date +%s).sql

# 2. Validate CSV
echo "[ ] Validate CSV format and encoding"
file -b --mime-encoding "$1"
head -5 "$1"

# 3. Check campaign exists
echo "[ ] Verify campaign exists"
mysql -u cron -p1234 asterisk -sN -e \
  "SELECT campaign_id FROM vicidial_campaigns WHERE campaign_id = 'TEST_CAMPAIGN';"

# 4. Check disk space
echo "[ ] Check available disk space"
df -h /var/spool/vicidial/

# 5. Check database connection
echo "[ ] Test database connection"
mysql -u cron -p1234 asterisk -e "SELECT COUNT(*) FROM vicidial_list LIMIT 1;"

# 6. Verify daemons running
echo "[ ] Verify ViciDial daemons running"
ps aux | grep -E "vicidial_dial|vicidial_agent" | grep -v grep

echo "=== Checklist Complete ==="

Backup Strategy

#!/bin/bash
# backup_before_import.sh

TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups/vicidial"

mkdir -p "$BACKUP_DIR"

echo "Creating database backup: $BACKUP_DIR/asterisk_$TIMESTAMP.sql.gz"
mysqldump -u cron -p1234 --single-transaction --quick asterisk | \
    gzip > "$BACKUP_DIR/asterisk_$TIMESTAMP.sql.gz"

# Verify backup
gunzip -t "$BACKUP_DIR/asterisk_$TIMESTAMP.sql.gz"
if [ $? -eq 0 ]; then
    echo "Backup verified successfully"
else
    echo "ERROR: Backup verification failed!"
    exit 1
fi

# Keep only last 10 backups
ls -t "$BACKUP_DIR"/asterisk_*.sql.gz | tail -n +11 | xargs rm -f

Logging and Audit Trail

#!/bin/bash
# import_with_audit.sh

IMPORT_LOG="/var/log/vicidial/lead_imports.log"
CSV_FILE="$1"
CAMPAIGN="TEST_CAMPAIGN"

# Log import start
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Starting import: $CSV_FILE" >> "$IMPORT_LOG"

# Get file metadata
FILE_SIZE=$(du -h "$CSV_FILE" | cut -f1)
FILE_HASH=$(md5sum "$CSV_FILE" | awk '{print $1}')
LEAD_COUNT=$(wc -l < "$CSV_FILE")

echo "[$(date '+%Y-%m-%d %H:%M:%S')] File: $CSV_FILE | Size: $FILE_SIZE | Leads: $LEAD_COUNT | MD5: $FILE_HASH" >> "$IMPORT_LOG"

# Run import with error capturing
perl /usr/share/astguiclient/VICIDIAL_add_lead_list.pl \
    --listname "${CAMPAIGN}_$(date +%s)" \
    --campaign "$CAMPAIGN" \
    --file "$CSV_FILE" \
    --phonefield 1 \
    --firstnamefield 2 \
    --lastnamefield 3 \
    --emailfield 4 \
    --vendorfield 5 \
    --sourcefield 6 \
    --tzfield 7 \
    --dbhost localhost \
    --dbuser cron \
    --dbpass 1234 \
    --dbname asterisk \
    --active "Y" 2>&1 | tee -a "$IMPORT_LOG"

# Log completion
FINAL_COUNT=$(mysql -u cron -p1234 asterisk -sN -e \
    "SELECT COUNT(*) FROM vicidial_list WHERE list_id = (SELECT MAX(list_id) FROM vicidial_lists);")

echo "[$(date '+%Y-%m-%d %H:%M:%S')] Import complete. Final lead count: $FINAL_COUNT" >> "$IMPORT_LOG"

Summary

Uploading lead lists to ViciDial requires careful attention to CSV formatting, field mapping, and validation. The key steps are:

Prepare your CSV with proper encoding (UTF-8), consistent field counts, and valid phone numbers
Map fields correctly, ensuring phone_number is primary and vendor_lead_code is set for duplicate detection
Set timezones (gmt_offset_now) for TCPA compliance and proper calling windows
Choose your upload method — web UI for small lists, CLI for production/large-scale imports
Validate after import using database queries to ensure data integrity
Implement safeguards with backups, deduplication, and audit logging for production reliability

For optimal results in production environments:

Always deduplicate leads before import using vendor_lead_code
Split very large lists (>50M leads) into chunks to avoid memory issues
Test imports with a small sample first before running full campaigns
Monitor upload progress with real-time database queries
Keep comprehensive logs and backups for compliance and troubleshooting
Use the CLI/Perl scripts for scriptable, repeatable imports rather than relying on the web UI

With these practices, you can reliably and efficiently manage lead lists at any scale in ViciDial production environments.

How to Change Campaign Dial Speed in ViciDial

Moisi Trungu — Wed, 12 Aug 2026 03:30:03 +0000

How to Change Campaign Dial Speed in ViciDial

Master dial speed adjustments for ViciDial campaigns to optimize agent productivity, improve call connection rates, and reduce idle time in your production Asterisk environment.

Prerequisites

Before modifying campaign dial speed settings, ensure you have:

Root or sudo access to your ViciDial server
Access to the ViciDial admin panel with administrative privileges
MySQL/MariaDB client access to the asterisk database
Familiarity with basic ViciDial campaign configuration
Understanding of your current calling volume and agent count
Recent backup of your ViciDial database
Knowledge of your Asterisk version (tested on 11.x, 13.x, 16.x, 18.x)
Access to server command line via SSH or direct console
At least one active campaign already created

Understanding Campaign Dial Speed in ViciDial

Dial speed (also called "dial ratio" or "calls per agent") determines how many calls ViciDial will attempt to place for each available agent in a campaign. This setting is critical for both inbound and outbound calling operations.

What Dial Speed Controls

The dial speed parameter governs:

Number of simultaneous calls attempted per agent
Queue management and call distribution
Agent idle time and workload balance
System resource consumption on your Asterisk server
Connection rates and answer supervision quality
Overall dialing efficiency and campaign profitability

Common Dial Speed Values

1.0 - 1.2 (Conservative)

One call per agent, minimal preview time
Best for complex calls requiring agent preparation
Lower abandonment rates
Reduced system load

1.3 - 1.5 (Moderate)

Standard for most outbound campaigns
Balanced productivity and call quality
Typical industry standard

1.6 - 2.5 (Aggressive)

Multiple calls queued per agent
Higher connection rates but increased abandonment
Requires experienced agents
Higher system resource usage

2.5+ (Power dialing)

Maximum throughput mode
Primarily for high-volume, simple messaging
Risk of high abandonment rates
Only for compliant campaigns

Accessing the Admin Panel

Via Web Interface

Launch your browser and navigate to your ViciDial admin URL:

http://your-vicidial-ip/vicidial/admin.php

Click on Campaigns from the main menu, then select your target campaign from the list.

Locating the Dial Speed Setting

In the Campaign Edit screen, locate the Dial Speed field. In most ViciDial versions, this appears in the main campaign settings section, often labeled:

Dial Speed
Calls Per Agent
Dial Ratio
Agent Dial Speed

The field typically accepts decimal values between 0.1 and 5.0.

Method 1: Changing Dial Speed via Web Admin Panel

This is the most user-friendly approach for most administrators.

Step-by-Step Process

Navigate to Campaigns → Select Your Campaign
Scroll to the campaign configuration section
Locate the Dial Speed field
Enter your desired dial speed value (e.g., 1.5)
Click SAVE or UPDATE button
Confirm the change was applied

Example Configuration

Campaign: SALES_OUTBOUND_Q2
Current Dial Speed: 1.2
New Dial Speed: 1.8
Active Agents: 25
Expected simultaneous calls: 45 (25 agents × 1.8)

Immediate Effects

Once saved:

The new dial speed takes effect within 1-2 minutes
Existing calls continue on previous settings
New outbound calls follow the new dial speed
No service interruption occurs

Method 2: Direct Database Modification

For bulk changes or scripted deployments, you can modify the ViciDial database directly.

Identifying the Campaign

First, confirm your campaign ID:

SELECT campaign_id, campaign_name, dial_speed 
FROM vicidial_campaigns 
WHERE campaign_name = 'SALES_OUTBOUND_Q2'\G

Example output:

*************************** 1. row ***************************
campaign_id: 1001
campaign_name: SALES_OUTBOUND_Q2
dial_speed: 1.2

Updating Dial Speed via SQL

Connect to the asterisk database and execute:

UPDATE vicidial_campaigns 
SET dial_speed = 1.8 
WHERE campaign_id = '1001';

Verify the change:

SELECT campaign_id, campaign_name, dial_speed 
FROM vicidial_campaigns 
WHERE campaign_id = '1001'\G

Batch Updates for Multiple Campaigns

To update multiple campaigns at once:

UPDATE vicidial_campaigns 
SET dial_speed = 1.5 
WHERE campaign_id IN ('1001', '1002', '1003', '1004')
AND status = 'ACTIVE';

Reverting a Change

Always preserve the original value:

UPDATE vicidial_campaigns 
SET dial_speed = 1.2 
WHERE campaign_id = '1001';

Method 3: API-Based Modification

For integration with external systems or automated workflows:

ViciDial API Endpoint

ViciDial exposes campaign modification through its API. Example request:

curl -X POST http://your-vicidial-ip/vicidial/non_agent_api.php \
  -d "user=admin_username" \
  -d "pass=admin_password" \
  -d "campaign_id=1001" \
  -d "campaign_name=SALES_OUTBOUND_Q2" \
  -d "dial_speed=1.8" \
  -d "format=json"

Expected Response

{
  "response": "CAMPAIGN UPDATED",
  "campaign_id": "1001",
  "dial_speed": "1.8"
}

Error Handling

#!/bin/bash
RESPONSE=$(curl -s -X POST http://your-vicidial-ip/vicidial/non_agent_api.php \
  -d "user=admin_username" \
  -d "pass=admin_password" \
  -d "campaign_id=1001" \
  -d "dial_speed=1.8" \
  -d "format=json")

echo "$RESPONSE" | grep -q "CAMPAIGN UPDATED"
if [ $? -eq 0 ]; then
  echo "Success: Dial speed updated"
else
  echo "Error: Update failed"
  echo "$RESPONSE"
fi

Monitoring Impact of Dial Speed Changes

Real-Time Call Monitoring

Monitor the immediate effects using Asterisk CLI:

asterisk -rx "core show channels"

Sample output:

Channel              State   Application Data
SIP/1234-00000abc    Up      AppDial
SIP/1235-00000abd    Up      AppDial
SIP/1236-00000abe    Up      VoiceMail
--- 47 active channels
--- 3 active calls

ViciDial Log Analysis

Check the vicidial_log table for real-time statistics:

SELECT 
  campaign_id,
  campaign_name,
  COUNT(*) as total_calls,
  SUM(CASE WHEN status = 'ANSWER' THEN 1 ELSE 0 END) as answered_calls,
  ROUND(100.0 * SUM(CASE WHEN status = 'ANSWER' THEN 1 ELSE 0 END) / COUNT(*), 2) as answer_rate,
  AVG(LENGTH) as avg_call_length,
  SUM(LENGTH) as total_talk_time
FROM vicidial_log 
WHERE campaign_id = '1001'
AND call_date > DATE_SUB(NOW(), INTERVAL 1 HOUR)
GROUP BY campaign_id, campaign_name\G

System Resource Monitoring

Monitor CPU, memory, and disk I/O during and after changes:

top -b -n 1 | head -20

Check Asterisk process specifically:

ps aux | grep -i asterisk | grep -v grep

Monitor database connections:

mysql -u root -p -e "SHOW PROCESSLIST;" | grep -i vicidial

Agent Idle Time Tracking

Query for agent idle statistics:

SELECT 
  user,
  COUNT(*) as total_logins,
  AVG(UNIX_TIMESTAMP(logout_time) - UNIX_TIMESTAMP(login_time)) as avg_session_length,
  SUM(CASE WHEN status = 'IDLE' THEN idle_sec ELSE 0 END) as total_idle_seconds
FROM vicidial_agent_log 
WHERE login_time > DATE_SUB(NOW(), INTERVAL 24 HOUR)
GROUP BY user
ORDER BY total_idle_seconds DESC
LIMIT 15;

Performance Tuning Considerations

Database Connection Limits

Verify your MySQL max connections setting:

mysql -u root -p -e "SHOW VARIABLES LIKE 'max_connections';"

For high dial speeds (>2.0), ensure adequate connections:

mysql -u root -p -e "SET GLOBAL max_connections = 500;"

Make permanent in /etc/mysql/my.cnf:

[mysqld]
max_connections = 500
max_allowed_packet = 64M

Asterisk Channel Limits

Check current SIP channel limits in /etc/asterisk/sip.conf:

[general]
maxcallbitrate = 384000
dtmfmode = rfc2833
rtptimeout = 60
rtpholdtimeout = 300
sipdebug = no

For high-volume campaigns, modify /etc/asterisk/extensions-vicidial.conf:

[from-vicidial]
exten => _X.,1,NoOp(Vicidial outbound call - ${CALLERID(num)})
exten => _X.,n,Set(CHANNEL_LIMIT=50)
exten => _X.,n,Dial(SIP/${EXTEN}@carrier,180,L(${CHANNEL_LIMIT}):10000)
exten => _X.,n,Hangup()

Asterisk Configuration Reload

After modifying Asterisk configs, reload without dropping calls:

asterisk -rx "module reload chan_sip.so"

Or completely reload dialplan:

asterisk -rx "dialplan reload"

Advanced: Campaign Dial Speed Scheduling

Time-Based Dial Speed Adjustment

Create a scheduled script to adjust dial speed based on time of day:

#!/bin/bash
# /usr/local/bin/adjust_dial_speed.sh

DB_USER="cron"
DB_PASS="yourpassword"
DB_NAME="asterisk"
CAMPAIGN_ID="1001"

HOUR=$(date +%H)

# Morning (9-12): Conservative
if [ $HOUR -ge 9 ] && [ $HOUR -lt 12 ]; then
  DIAL_SPEED="1.2"
fi

# Afternoon (12-17): Moderate
if [ $HOUR -ge 12 ] && [ $HOUR -lt 17 ]; then
  DIAL_SPEED="1.5"
fi

# Evening (17-21): Aggressive
if [ $HOUR -ge 17 ] && [ $HOUR -lt 21 ]; then
  DIAL_SPEED="1.8"
fi

# Late night (21+): Conservative
if [ $HOUR -ge 21 ] || [ $HOUR -lt 9 ]; then
  DIAL_SPEED="1.0"
fi

mysql -u $DB_USER -p$DB_PASS $DB_NAME -e \
  "UPDATE vicidial_campaigns SET dial_speed = $DIAL_SPEED WHERE campaign_id = '$CAMPAIGN_ID';"

echo "$(date): Campaign $CAMPAIGN_ID dial speed set to $DIAL_SPEED" >> /var/log/vicidial_dial_speed.log

Add to crontab for automatic execution:

crontab -e

Add the line:

0 9,12,17,21 * * * /usr/local/bin/adjust_dial_speed.sh

Agent Count-Based Dynamic Adjustment

Adjust dial speed based on currently logged-in agents:

#!/bin/bash
# /usr/local/bin/dynamic_dial_speed.sh

DB_USER="cron"
DB_PASS="yourpassword"
DB_NAME="asterisk"
CAMPAIGN_ID="1001"

# Get active agent count
AGENT_COUNT=$(mysql -u $DB_USER -p$DB_PASS $DB_NAME -sN -e \
  "SELECT COUNT(*) FROM vicidial_users WHERE active = '1' AND user_level > 1;")

# Adjust dial speed based on agent availability
if [ $AGENT_COUNT -lt 10 ]; then
  DIAL_SPEED="1.0"
elif [ $AGENT_COUNT -lt 20 ]; then
  DIAL_SPEED="1.3"
elif [ $AGENT_COUNT -lt 50 ]; then
  DIAL_SPEED="1.5"
else
  DIAL_SPEED="1.8"
fi

mysql -u $DB_USER -p$DB_PASS $DB_NAME -e \
  "UPDATE vicidial_campaigns SET dial_speed = $DIAL_SPEED WHERE campaign_id = '$CAMPAIGN_ID';"

echo "$(date): Agents: $AGENT_COUNT, Dial Speed: $DIAL_SPEED" >> /var/log/vicidial_dynamic.log

Troubleshooting

Issue: Dial Speed Change Not Taking Effect

Symptoms: Campaign shows updated dial speed in admin panel, but calling behavior unchanged.

Solution:

Verify the change was saved to the database:

SELECT campaign_id, campaign_name, dial_speed 
FROM vicidial_campaigns 
WHERE campaign_id = '1001'\G

Check if campaign is paused:

SELECT campaign_id, campaign_name, active, dial_speed 
FROM vicidial_campaigns 
WHERE campaign_id = '1001'\G

If active = '0', enable the campaign:

UPDATE vicidial_campaigns SET active = '1' WHERE campaign_id = '1001';

Restart the vicidial_agent_api service:

systemctl restart vicidial_agent_api

Or if using older init:

/etc/init.d/vicidial_agent_api restart

Wait 2-3 minutes for the change to propagate through the system.

Issue: Calls Connecting Too Slowly Despite High Dial Speed

Symptoms: Dial speed set to 2.0 or higher, but agents still idle frequently.

Diagnosis:

Check for failed/abandoned calls:

SELECT 
  status,
  COUNT(*) as count
FROM vicidial_log 
WHERE campaign_id = '1001'
AND call_date > DATE_SUB(NOW(), INTERVAL 1 HOUR)
GROUP BY status;

High counts of 'CANCEL', 'NO ANSWER', or 'BUSY' indicate connection issues, not dial speed problems.

Verify carrier/trunk capacity:

asterisk -rx "sip show peers"

Look for registration status and call count per carrier.

Check for dialplan errors:

tail -f /var/log/asterisk/messages | grep -i error

Solutions:

Reduce dial speed to improve call quality and answer rates
Add additional trunks/carriers
Optimize dialplan rules in extensions-vicidial.conf
Increase available bandwidth for better SIP handling

Issue: High System Load After Increasing Dial Speed

Symptoms: CPU usage spikes to 100%, increased latency, database slowness.

Diagnosis:

top -b -n 1 | head -30

Check database query performance:

mysql -u root -p -e "SHOW FULL PROCESSLIST\G" | grep -i Query_time

Check Asterisk CPU usage:

asterisk -rx "core show calls"

Solutions:

Reduce dial speed:

UPDATE vicidial_campaigns SET dial_speed = 1.2 WHERE campaign_id = '1001';

Optimize database:

mysql -u root -p asterisk -e "OPTIMIZE TABLE vicidial_log;"
mysql -u root -p asterisk -e "OPTIMIZE TABLE vicidial_agent_log;"

Increase server resources (CPU, RAM, disk I/O)
Distribute load across multiple Asterisk boxes
Enable connection pooling in my.cnf:

[mysqld]
innodb_buffer_pool_size = 4G
thread_cache_size = 128
query_cache_size = 512M
query_cache_type = 1

Issue: Abandonment Rate Increased After Speed Change

Symptoms: Dial speed increased, but customer abandonment rate (calls hung up before agent pickup) jumped.

Analysis:

SELECT 
  campaign_id,
  COUNT(*) as total_calls,
  SUM(CASE WHEN status = 'ABANDON' THEN 1 ELSE 0 END) as abandoned,
  ROUND(100.0 * SUM(CASE WHEN status = 'ABANDON' THEN 1 ELSE 0 END) / COUNT(*), 2) as abandon_rate
FROM vicidial_log 
WHERE campaign_id = '1001'
AND call_date > DATE_SUB(NOW(), INTERVAL 24 HOUR)
GROUP BY campaign_id;

Solutions:

Reduce dial speed incrementally (e.g., from 1.8 to 1.5)
Implement answer supervision to filter busy/no-answer calls
Add agent headsets to speed up connect time
Train agents on faster call acceptance
Increase agent count to handle call volume

Issue: Cannot Connect to Database to Update Dial Speed

Error: ERROR 1045 (28000): Access denied for user 'cron'@'localhost'

Solution:

Verify database credentials in /etc/astguiclient/astguiclient.conf:

grep -i password /etc/astguiclient/astguiclient.conf

If using wrong credentials, update:

vi /etc/astguiclient/astguiclient.conf

Or test connection directly:

mysql -h localhost -u cron -p asterisk -e "SELECT 1;"

If cron user doesn't exist, create it:

mysql -u root -p mysql -e \
  "GRANT ALL ON asterisk.* TO 'cron'@'localhost' IDENTIFIED BY 'newpassword';"

Best Practices

Monitoring and Documentation

Always document dial speed changes:

# /var/log/vicidial_changes.log
2024-01-15 10:30:00 - Campaign SALES_Q1: dial_speed 1.2 → 1.5 (reason: 20 new agents)
2024-01-15 14:00:00 - Campaign SALES_Q1: dial_speed 1.5 → 1.3 (reason: high abandonment)

Incremental Changes

Never jump from 1.2 to 2.0. Increase in small steps:

-- Day 1
UPDATE vicidial_campaigns SET dial_speed = 1.3 WHERE campaign_id = '1001';

-- Day 2 (after monitoring)
UPDATE vicidial_campaigns SET dial_speed = 1.5 WHERE campaign_id = '1001';

-- Day 3
UPDATE vicidial_campaigns SET dial_speed = 1.7 WHERE campaign_id = '1001';

Regular Performance Reviews

Schedule weekly reviews:

-- Weekly dial speed effectiveness report
SELECT 
  DATE(call_date) as date,
  campaign_id,
  campaign_name,
  COUNT(*) as total_calls,
  SUM(CASE WHEN status = 'ANSWER' THEN 1 ELSE 0 END) as answered,
  ROUND(100.0 * SUM(CASE WHEN status = 'ANSWER' THEN 1 ELSE 0 END) / COUNT(*), 2) as answer_rate,
  AVG(LENGTH) as avg_duration,
  SUM(CASE WHEN status = 'ABANDON' THEN 1 ELSE 0 END) as abandoned
FROM vicidial_log 
WHERE campaign_id = '1001'
AND call_date > DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY DATE(call_date)
ORDER BY call_date DESC;

Compliance Considerations

Check FCC/TCPA regulations for your campaign type. Some call types have maximum abandonment limits. Document dial speed choices to demonstrate compliance efforts.

Summary

Changing campaign dial speed in ViciDial is a straightforward process with three primary methods:

Web Admin Panel - Best for manual, single-campaign changes
Direct Database Updates - Fastest for bulk changes or scripted deployments
API-Based Modifications - Ideal for system integration and automation

The key to successful dial speed optimization is:

Monitor incrementally - Small changes with monitoring periods
Track metrics - Answer rates, abandonment, agent idle time
Document changes - Maintain audit trail of all adjustments
Consider context - Agent experience, system resources, compliance requirements
Test thoroughly - Always have a rollback plan
Automate responsibly - Use scheduling for predictable patterns

A well-tuned dial speed balances agent productivity with call quality and customer satisfaction. Start conservative (1.2-1.3) and gradually increase based on your specific operational metrics and constraints. Your optimal dial speed depends on your agents' experience, your calling list quality, your system resources, and your business goals.

How to Add an Agent in ViciDial — User Setup & Phone Config

Moisi Trungu — Tue, 11 Aug 2026 03:30:02 +0000

How to Add an Agent in ViciDial — User Setup & Phone Config

Master the complete process of creating and configuring a new agent in ViciDial, from database entry through SIP registration and phone extension setup.

Prerequisites

Before adding an agent to your ViciDial system, ensure you have:

ViciDial 2.x or 3.x installed and running (tested on 2.14+ through 3.x)
Root or sudo access to the ViciDial server
Access to the ViciDial web admin panel (http://your-server/vicidial/admin.php)
An existing campaign configured in the system
A SIP phone or softphone application ready for the agent
MySQL database access (for manual verification)
Asterisk running and accessible via CLI
Basic familiarity with Linux command line

Understanding ViciDial Agent Architecture

Agent vs. User vs. Extension

ViciDial uses three interconnected concepts:

User: The administrative login account in the ViciDial system
Agent: The voice channel and phone configuration tied to that user
Extension: The SIP endpoint (phone) that registers to Asterisk

One user can have one active agent, though multiple extensions can exist. The agent record defines which campaign the user can access, pause codes, and phone behavior.

Database Tables Involved

Three primary tables interact when adding an agent:

vicidial_users           — User login credentials and permissions
vicidial_agents          — Agent configuration (user_id, phone, campaign)
asterisk_sip_peers       — SIP phone registration details (generated from sip-vicidial.conf)

Step 1: Create the User Account in ViciDial Web Admin

The fastest and recommended method is through the web interface.

Access the User Management Panel

Log in to /vicidial/admin.php as an administrator
Navigate to Users → Add User
Fill in the required fields:

Field	Example	Notes
User Login	`agent001`	Must be unique; lowercase recommended
Password	`SecurePass123!`	Min 6 characters; change after first login
Full Name	`John Smith`	For reporting and display
Email	`john@company.com`	Used for alerts and notifications
Phone Number	`5551234567`	Contact number for agent
Status	`ACTIVE`	Set to ACTIVE or INACTIVE

Configure User Permissions

Under the User Permissions section:

Group: Assign to ADMIN, QA, SALES, or custom group
User Level: Set to 1 for agent, 7 for manager, 8 for admin
Confirm Password Changes: Check if agent must change password at login
Inbound Only: Check to restrict to inbound calls only
Outbound Only: Check to restrict to outbound calls only

Leave blank for both inbound and outbound access.

Save and Note the User ID

After saving, ViciDial assigns a unique user_id. You'll need this for the agent configuration.

Step 2: Create the Agent Record

Via Web Admin (Recommended)

Navigate to Agents → Add Agent
Complete the agent setup form:

Field	Example	Notes
User	`agent001`	Auto-populated from user creation
Agent ID	`100001`	Can be auto-assigned; must be unique
Phone Number	`1001`	SIP extension for this agent
Phone Type	`SIP`	Use SIP for modern deployments
Status	`ACTIVE`	Ready to log in
Campaign	`SALES_OUTBOUND`	Default campaign for agent
Closer Group	`SALES`	(Optional) Queue for inbound

Via MySQL (For Scripted Deployments)

If you're automating agent creation, use SQL directly:

USE asterisk;

INSERT INTO vicidial_agents 
(user_id, agent_id, user, phone_number, phone_type, status, 
 campaign_id, closer_group, email, active, last_login, last_call_time)
VALUES 
(123, 100001, 'agent001', '1001', 'SIP', 'ACTIVE', 
 'SALES_OUTBOUND', 'SALES', 'john@company.com', 'Y', NOW(), 0);

-- Verify insertion
SELECT user_id, agent_id, user, phone_number, status FROM vicidial_agents 
WHERE user = 'agent001';

Replace:

123 with the actual user_id from step 1
100001 with your agent ID scheme
SALES_OUTBOUND with your campaign name

Step 3: Configure the SIP Phone Extension

Generate SIP Configuration

ViciDial typically generates SIP extensions automatically in /etc/asterisk/sip-vicidial.conf when you add an agent. However, you may need to generate or verify it manually.

Manual SIP Peer Configuration

If auto-generation doesn't work, add the extension to /etc/asterisk/sip-vicidial.conf:

[1001]
type=friend
context=from-vicidial-agents
callerid="Agent 001" <1001>
host=dynamic
secret=YourSecurePassword123
qualify=yes
port=5060
nat=yes
insecure=port,invite
canreinvite=no
disallow=all
allow=ulaw,alaw,gsm
directmedia=no
username=1001
mailbox=1001@default

Key settings explained:

type=friend — Allows bidirectional calling
context=from-vicidial-agents — Routes to ViciDial context (verify in extensions.conf)
secret — SIP password; must match phone config
nat=yes — Accommodates agents behind NAT
insecure=port,invite — Relaxes authentication (production: tighten this)
disallow=all; allow=ulaw — Codec restriction for bandwidth

Reload Asterisk Configuration

After editing the SIP config:

sudo asterisk -rx "sip reload"

Verify the extension loaded:

sudo asterisk -rx "sip show peers"

Output should show:

1001/1001                        (Unregistered)

Once the phone registers, it will show an IP:

1001/1001                        192.168.1.105:5064    OK (42 ms)

Step 4: Configure the Phone/Softphone

SIP Phone Credentials

Provide the agent with:

Username: 1001
Password: (matching the SIP secret from config)
Server/Domain: your-vicidial-server.com or IP address
Port: 5060 (or custom if changed)
Display Name: Agent 001 (or agent's name)

Popular Softphone Clients

Zoiper (iOS/Android/Windows/Mac)

Add Account → SIP Account
Enter extension (e.g., 1001@your-server.com)
Password: SIP secret
Server: ViciDial server IP/hostname
Enable "Use SIP directly" if behind NAT

Grandstream GrandStream Desktop (Windows/Mac)

Settings → Accounts
Create SIP Account
Configure with above details
Enable "Behind NAT"

Physical SIP Phones (Yealink, Polycom, Cisco)

Web admin interface of phone
Network settings → VoIP > Accounts
Server address, username, password, port
Enable NAT (usually labeled "Symmetric RTP")

Test SIP Registration

After phone configuration, check Asterisk:

sudo asterisk -rx "sip show peer 1001"

Output should show:

  Name       : 1001
  Exten      : 1001                   ACTIVE
  Context    : from-vicidial-agents
  Callid     : agent001-sip@192.168.1.105
  ChanObjectType : SIP
  Useragent  : Zoiper 5.3.18
  Status     : OK (42 ms)

If status is UNKNOWN or Unreachable, check firewall rules on port 5060/5061.

Step 5: Configure ViciDial Phone Settings

Access Phone Configuration

In the web admin, navigate to System → Phones or Agents → Phone Settings for the agent.

Essential Phone Parameters

Phone Codec:          ULAW (or ALAW if EU-based)
Inbound Context:      from-vicidial-agents
Outbound Context:     from-vicidial-agents
Recording:            ENABLED
Recording Format:     MP3 or WAV
Voicemail Enabled:    YES (optional)
Inbound Answering:    AGENT_ONLY
Ringback:             ENABLED
Ringback Timeout:     30 seconds

Agent-Specific Settings

If your ViciDial uses Vicidial Phone Screen, configure:

Vicidial Phone Type:  SIP
VoiceGain:            0 (0-10 scale; increase if audio is low)
MicGain:              0 (0-10 scale)
Monitoring:           ENABLED (for QA supervisors)
Blind Transfers:      ALLOWED
Attended Transfers:   ALLOWED

These may be set at campaign level (overrides) or globally.

Step 6: Set Campaign Access and Permissions

Assign Agent to Campaign

In the agent record or via the Campaigns panel:

Go to Campaigns → Edit campaign (e.g., SALES_OUTBOUND)
Add agent agent001 to the agent list, or
Add to the agent's campaign_id field in the database:

UPDATE vicidial_agents SET campaign_id = 'SALES_OUTBOUND' WHERE user = 'agent001';

Verify Campaign Settings

Ensure the campaign has the correct:

Dial Method: MANUAL, PREVIEW, or POWER (affects agent workflow)
Call Recording: ENABLED for compliance
Auto-Dial Level: 0.8 - 1.5 (for POWER dial)
Lead Pool: Campaign's lead source

Optional: Restrict to Specific Queues

If using inbound queues:

UPDATE vicidial_agents 
SET closer_group = 'SALES' 
WHERE user = 'agent001';

This restricts the agent to inbound calls routed to the SALES queue.

Step 7: Test the Agent Login

Via Vicidial Agent Screen

Direct agent to /agc/vicidial.php
Log in with username and password
Select the Phone field (should show extension, e.g., 1001)
Agent should see a "READY" or "PAUSED" status

Via CLI – Verify Agent in System

sudo asterisk -rx "vicidial show agents"

This ViciDial-specific command (if installed) shows:

Agent ID     User         Extension  Status    Campaign
100001       agent001     1001       READY     SALES_OUTBOUND

Alternatively, query the database:

mysql -u root -p asterisk -e "SELECT agent_id, user, phone_number, status FROM vicidial_agents WHERE user = 'agent001';"

Make a Test Call

Agent logs in and changes status to READY
Dial the agent extension: asterisk -rx "console dial 1001@from-vicidial-agents"
Agent's phone should ring
Verify audio quality and recording

Step 8: Configure Advanced Features (Optional)

Blind and Attended Transfers

Edit the agent's User Profile to enable transfer permissions:

UPDATE vicidial_users 
SET blind_transfer_enabled = 'Y', 
    attended_transfer_enabled = 'Y'
WHERE user = 'agent001';

Call Recording Configuration

ViciDial records calls by default. Verify:

ls -la /var/spool/asterisk/monitor/

Recordings stored as: YYYY-MM-DD-HH-MM-SS_<extension>_<direction>.wav

To set recording path per agent, edit campaign settings or globally in:

/etc/asterisk/extensions-vicidial.conf

Look for:

exten => 1001,1,MixMonitor(${MYFILENAME}.wav,b)

Voicemail Setup (Optional)

If agents need voicemail:

sudo asterisk -rx "voicemail show users"

Add voicemail to agent extension:

; In /etc/asterisk/sip-vicidial.conf
[1001]
mailbox=1001@default

Create voicemail box:

; In /etc/asterisk/voicemail.conf
[default]
1001 => 1234,Agent 001,john@company.com

Reload:

sudo asterisk -rx "voicemail reload"

Troubleshooting

Agent Cannot Log In

Symptom: "Invalid username or password" error

Solutions:

Verify user exists and status is ACTIVE:

   SELECT user_id, user, password, status FROM vicidial_users WHERE user = 'agent001';

Check agent record exists:

   SELECT agent_id, user, status FROM vicidial_agents WHERE user = 'agent001';

Verify password (ViciDial may hash it):

   UPDATE vicidial_users SET password = MD5('NewPassword123') WHERE user = 'agent001';

Check web server logs:

   tail -f /var/log/apache2/error.log
   tail -f /var/log/asterisk/messages

SIP Phone Not Registering

Symptom: Extension shows "Unregistered" or "Unreachable"

Solutions:

Verify firewall allows SIP (port 5060/5061):

   sudo ufw allow 5060/udp
   sudo ufw allow 5061/udp
   # Or for iptables:
   sudo iptables -A INPUT -p udp --dport 5060 -j ACCEPT

Check SIP config syntax:

   sudo asterisk -rx "sip show peers"
   sudo asterisk -rx "sip reload"

Verify phone has correct credentials and server:
- Check phone's SIP logs (usually in phone settings)
- Test with a different softphone (e.g., Zoiper)
Check Asterisk SIP debug:

   sudo asterisk -rx "sip set debug peer 1001"
   # Watch registration attempts in /var/log/asterisk/messages
   sudo tail -f /var/log/asterisk/messages
   # Then disable:
   sudo asterisk -rx "sip set debug off"

Verify NAT settings if agent is remote:

   nat=yes
   directmedia=no
   insecure=port,invite

Poor Audio Quality or One-Way Audio

Symptom: Agent or caller cannot hear the other party, or audio is choppy

Solutions:

Check codec compatibility:

   sudo asterisk -rx "sip show peer 1001"

Ensure codec is ulaw or alaw, not gsm for production.

Enable media bypass correctly:

   directmedia=no    ; Force media through Asterisk (recommended)

Increase jitter buffer on phone (if supported)
Check packet loss and latency:

   ping -c 10 <agent-phone-ip>
   mtr <agent-phone-ip>

Verify RTP ports are open (5000-20000 UDP):

   sudo ufw allow 5000:20000/udp

Agent Logged In But No Calls Received

Symptom: Agent shows "READY" but doesn't receive inbound calls

Solutions:

Verify agent is assigned to a campaign:

   SELECT campaign_id FROM vicidial_agents WHERE user = 'agent001';

Check campaign has available leads:

   SELECT COUNT(*) FROM vicidial_list 
   WHERE campaign_id = 'SALES_OUTBOUND' AND status = 'NEW';

Verify closer group or queue assignment:

   SELECT closer_group FROM vicidial_agents WHERE user = 'agent001';

Check call routing in dialplan (/etc/asterisk/extensions-vicidial.conf):

   sudo asterisk -rx "dialplan show from-vicidial-agents@1001"

Verify campaign is active and not paused:

   SELECT campaign_id, active, dial_method FROM vicidial_campaigns 
   WHERE campaign_id = 'SALES_OUTBOUND';

Agent Cannot Dial Out

Symptom: Agent clicks dial but call doesn't complete

Solutions:

Check outbound context in extensions.conf:

   grep -n "from-vicidial-agents" /etc/asterisk/extensions-vicidial.conf | head -20

Verify SIP trunk configuration if using external dialing:

   sudo asterisk -rx "sip show peers" | grep -i trunk

Check campaign dial method:

   SELECT dial_method FROM vicidial_campaigns 
   WHERE campaign_id = 'SALES_OUTBOUND';

Should be MANUAL, PREVIEW, or POWER.

Review call logs for errors:

   tail -f /var/log/asterisk/messages | grep -i agent001

Verify dial plan has outbound rules:

   exten => _X.,1,Dial(SIP/${EXTEN}@trunk)

Security Best Practices

When adding agents, follow these security measures:

1. Use Strong Credentials

UPDATE vicidial_users 
SET password = MD5('Tr0pic@l!Mang0#2024SecurePass') 
WHERE user = 'agent001';

Enforce complexity in /usr/share/astguiclient/vicidial_passwd_requirements.php if available.

2. Restrict SIP Access

In /etc/asterisk/sip-vicidial.conf, use insecure carefully:

; Production: More restrictive
insecure=no

; Development/Testing: More permissive
insecure=port,invite

3. Enable User-Level Restrictions

UPDATE vicidial_users 
SET user_level = 1,
    admin = 'N',
    active = 'Y'
WHERE user = 'agent001';

4. Change Default Passwords

Always require agents to change their initial password on first login:

UPDATE vicidial_users 
SET force_password_change = 'Y' 
WHERE user = 'agent001';

5. Monitor Agent Activity

SELECT user, last_login, active, status 
FROM vicidial_users 
WHERE user = 'agent001';

Log all administrative changes for compliance.

Summary

Adding an agent to ViciDial involves a coordinated sequence of steps:

Create User Account — Web admin or MySQL
Create Agent Record — Link user to phone and campaign
Configure SIP Extension — sip-vicidial.conf or auto-generated
Configure Phone/Softphone — Provide credentials and server details
Test SIP Registration — Verify in Asterisk CLI
Configure Phone Settings — Codec, recording, voicemail
Assign Campaign Access — Link agent to campaigns and queues
Test Login and Calling — Verify agent can log in and make/receive calls
Apply Security Measures — Strong passwords, restricted access

For production environments, automate this process with scripts or configuration management tools. Always test new agents with a sample campaign before full deployment.

Key files to remember:

/etc/asterisk/sip-vicidial.conf — SIP phone definitions
/etc/asterisk/extensions-vicidial.conf — Dialplan and call routing
/var/log/asterisk/messages — Debug logs
ViciDial database: asterisk — Agent and user tables
/agc/vicidial.php — Agent login screen
/vicidial/admin.php — Administrative interface

Regular monitoring of agent status, call logs, and system health ensures smooth operation in your ViciDial deployment.

ViciDial VDAD Not Dialing — AST_VDadapt Process Troubleshooting

Moisi Trungu — Mon, 10 Aug 2026 03:30:02 +0000

ViciDial VDAD Not Dialing — AST_VDadapt Process Troubleshooting

Learn how to diagnose and fix the AST_VDadapt process when ViciDial campaigns fail to initiate outbound calls, with real configuration examples, database queries, and step-by-step debugging commands.

Prerequisites

Before starting this troubleshooting guide, you should have:

A production or test ViciDial installation (v2.13+) with Asterisk 13+ running
SSH access to the ViciDial server with root or sudo privileges
Basic familiarity with ViciDial campaign setup and Asterisk dialplan concepts
Access to the ViciDial MySQL database (typically asterisk database)
Understanding of ViciDial architecture: lead lists, campaigns, inbound/outbound routes, and carrier definitions
The ability to check system logs in /var/log/asterisk/messages
A test campaign configured and ready to dial

Understanding ViciDial's Dialing Architecture

What is AST_VDadapt?

AST_VDadapt is the Asterisk Adaptive Dialing engine—the core process responsible for initiating outbound calls in ViciDial. When agents are logged into a campaign, AST_VDadapt monitors the lead list, applies dialing rules (predictive, preview, manual), and generates Asterisk channels to make the actual phone calls.

The process runs as a background daemon and communicates with:

ViciDial MySQL database — reads leads, campaign settings, carrier routes
Asterisk dialplan — executes SIP/IAX channels via extensions-vicidial.conf
ViciDial agent interface — receives real-time dialing commands
System clock — enforces DNC (Do Not Call), time-based call rules

When VDAD is not dialing, no outbound calls are initiated, and agents see a frozen lead screen.

High-Level Call Flow

Agent logs into campaign → AST_VDadapt spawns a dialer thread
VDAD reads active leads from vicidial_list table
VDAD checks campaign settings in vicidial_campaigns and vicidial_carrier_log
VDAD determines outbound carrier/trunk from vicidial_carrier_log
VDAD executes Asterisk dialplan: exten => XXXXXX,n,Dial(SIP/trunk/number)
Call is logged to vicidial_log and vicidial_closer_log

If VDAD fails at any step, the call never dials.

Checking If AST_VDadapt Is Running

Verify Process Status

Start by confirming the AST_VDadapt process is actually running on your system:

ps aux | grep -i vdadapt | grep -v grep

Expected output (you should see one or more processes):

asterisk  12345 0.5 2.3 412344 95212 ?    Ssl  10:45   0:12 /usr/bin/perl /usr/share/astguiclient/AST_VDadapt.pl
asterisk  12346 0.4 1.8 398764 71256 ?    Ssl  10:45   0:08 /usr/bin/perl /usr/share/astguiclient/AST_VDadapt.pl

If no processes appear, the dialer is not running.

Restart the AST_VDadapt Service

ViciDial typically manages AST_VDadapt through init scripts or systemd:

# For systems with systemd
systemctl restart vicidial-astguiclient

# For older SysV init systems
/etc/init.d/vicidial-astguiclient restart

# Manual restart (if scripts don't work)
killall AST_VDadapt.pl
sleep 2
/usr/share/astguiclient/AST_VDadapt.pl &

Wait 10 seconds, then verify with ps aux again.

Check AST_VDadapt Logs

AST_VDadapt writes debugging output to /var/log/asterisk/ or a dedicated log file:

tail -f /var/log/asterisk/messages | grep -i vdadapt

Or check the ViciDial-specific log directory:

ls -lh /var/log/vicidial/
tail -f /var/log/vicidial/vdadapt.log

Look for errors like:

Database connection failed
No carriers available
Campaign paused
No agents logged in

Database Configuration and Lead List Issues

Verify Campaign Is Active

VDAD will not dial if the campaign itself is paused or disabled. Check the campaign status:

SELECT campaign_id, campaign_name, active, dial_method, 
       max_leads_for_24hrs, agents_logged_in 
FROM vicidial_campaigns 
WHERE campaign_id = 'TEST_CAMPAIGN';

Key fields to verify:

active = Y (must be active)
dial_method = ADAPT, MANUAL, INBOUND, or BLENDED (common values)
agents_logged_in > 0 (at least one agent must be logged in)

If active = 'N', activate it:

UPDATE vicidial_campaigns 
SET active = 'Y' 
WHERE campaign_id = 'TEST_CAMPAIGN';

Check for Available Leads

AST_VDadapt cannot dial if there are no leads in the list. Query the lead table:

SELECT COUNT(*) as total_leads, 
       SUM(CASE WHEN status = 'NEW' THEN 1 ELSE 0 END) as new_leads,
       SUM(CASE WHEN status = 'CALLBACK' THEN 1 ELSE 0 END) as callback_leads
FROM vicidial_list 
WHERE campaign_id = 'TEST_CAMPAIGN';

Expected result: total_leads > 0 and new_leads > 0 (or appropriate status for your campaign).

If total_leads = 0, import or add leads:

INSERT INTO vicidial_list 
(campaign_id, phone_number, phone_code, status, gmt_offset_now)
VALUES 
('TEST_CAMPAIGN', '5551234567', '1', 'NEW', '-5');

Verify DNC List and Do-Not-Call Rules

If your leads exist but aren't dialing, they may be blocked by DNC (Do-Not-Call) rules. Check the vicidial_dnc_list table:

SELECT COUNT(*) as dnc_count 
FROM vicidial_dnc_list 
WHERE phone_number IN 
  (SELECT phone_number FROM vicidial_list 
   WHERE campaign_id = 'TEST_CAMPAIGN' AND status = 'NEW');

If a high percentage of your test leads are in the DNC list, remove them temporarily:

DELETE FROM vicidial_dnc_list 
WHERE phone_number = '5551234567';

Check campaign-level DNC enforcement:

SELECT campaign_id, dnc_enforce_state, dnc_enforce_county 
FROM vicidial_campaigns 
WHERE campaign_id = 'TEST_CAMPAIGN';

dnc_enforce_state = 'Y' — respects state-level DNC
dnc_enforce_county = 'Y' — respects county/regional DNC

Outbound Route and Carrier Configuration

List Configured Carriers

VDAD must have at least one carrier (trunk) configured for the campaign. Query the carrier table:

SELECT carrier_id, carrier_name, active, calling_codec, 
       technology, outbound_proxy 
FROM vicidial_carrier_log 
WHERE campaign_id = 'TEST_CAMPAIGN' OR campaign_id = 'AGENT' OR carrier_id = 'default_carrier';

If no carriers appear, create one:

INSERT INTO vicidial_carrier_log 
(carrier_id, carrier_name, active, technology, calling_codec, campaign_id)
VALUES 
('SIP_CARRIER', 'SIP Trunk', 'Y', 'SIP', 'ULAW', 'TEST_CAMPAIGN');

Verify SIP/IAX Peer Configuration

Check that the carrier's trunk is defined in Asterisk. Look in /etc/asterisk/sip-vicidial.conf:

[sip_carrier_trunk]
type=peer
host=sip.carrierhost.com
port=5060
username=your_account_id
secret=your_sip_password
fromuser=your_account_id
fromdomain=sip.carrierhost.com
insecure=port,invite
context=from-vicidial
disallow=all
allow=ulaw
allow=gsm
canreinvite=no
nat=yes
qualify=yes
qualifyfreq=60

Verify the peer is loaded in Asterisk:

asterisk -rx "sip show peers"

Look for your carrier trunk in the output. If it's not listed, reload the SIP config:

asterisk -rx "module reload res_sip" 
# or for old SIP stack
asterisk -rx "sip reload"

Link Campaign to Carrier

Ensure the campaign is mapped to an active carrier in the ViciDial web admin:

Log into /vicidial/admin.php
Navigate to Campaigns → select your campaign
In the Carrier Outbound section, select a carrier
Save

Or verify via database:

SELECT campaign_id, carrier_id 
FROM vicidial_campaigns 
WHERE campaign_id = 'TEST_CAMPAIGN';

If carrier_id is NULL or empty, update it:

UPDATE vicidial_campaigns 
SET carrier_id = 'SIP_CARRIER' 
WHERE campaign_id = 'TEST_CAMPAIGN';

Asterisk Dialplan and Extensions Configuration

Check extensions-vicidial.conf Syntax

ViciDial's dialplan must be syntactically correct. Check for errors:

asterisk -rx "dialplan show from-vicidial" | head -20

If you see errors, validate the configuration file:

asterisk -nf -c
# Then at the Asterisk console:
dialplan show from-vicidial
quit

Common issues in /etc/asterisk/extensions-vicidial.conf:

Missing context definitions
Malformed Dial() applications
Incorrect priority numbering
Unclosed brackets or quotes

Reload Dialplan

After any changes to /etc/asterisk/extensions-vicidial.conf, reload:

asterisk -rx "dialplan reload"

Verify the reload was successful:

asterisk -rx "core show uptime" | grep "Asterisk uptime"

Verify Outbound Dial Context

Check the dialplan for outbound calls. The typical pattern is:

asterisk -rx "dialplan show outbound-vicidial@from-vicidial"

Expected output should show extensions for your carriers. If empty or missing, check /etc/asterisk/extensions-vicidial.conf for the outbound context definition:

[outbound-vicidial]
exten => _X.,n,Dial(SIP/carrier_name/${EXTEN},45,tTwW)
exten => _X.,n,Hangup()

Agent Login and Session Issues

Verify Agents Are Logged In

VDAD only dials if agents are active in a campaign. Check the agent session table:

SELECT user, campaign_id, status, channel 
FROM vicidial_agent_log 
WHERE campaign_id = 'TEST_CAMPAIGN' 
  AND event_epoch > (UNIX_TIMESTAMP() - 300) 
ORDER BY event_epoch DESC;

Expected: You should see at least one agent with status = 'READY' or 'PAUSED'.

If no agents are logged in, log one in via /agc/vicidial.php (the agent screen).

Check Agent Campaign Assignment

The agent must be assigned to the campaign:

SELECT user, campaign_id, active 
FROM vicidial_users 
WHERE user = 'AGENT1';

Verify:

campaign_id matches your test campaign
active = 'Y'

If the agent isn't assigned to the campaign, add them in the admin panel or via SQL:

UPDATE vicidial_users 
SET campaign_id = 'TEST_CAMPAIGN', active = 'Y' 
WHERE user = 'AGENT1';

Check Agent Status in Real Time

Monitor the agent's Asterisk channel while they're logged in:

asterisk -rx "core show channels"

Look for a channel matching the agent's user ID. If no channel appears, the agent's SIP client connection is not active.

Memory and System Resource Constraints

Check System Memory and Load

AST_VDadapt and Asterisk are memory-intensive. If system resources are exhausted, dialing will stall:

free -m
top -b -n 1 | head -15

Look for:

Memory: Free memory should be > 20% of total RAM
Load average: Should be < 4x the number of CPU cores
Swap usage: Should be minimal (< 10% of swap)

If memory is critically low:

systemctl stop vicidial-astguiclient
asterisk -rx "graceful shutdown"
sleep 30
# Clear caches
sync && echo 3 > /proc/sys/vm/drop_caches
# Restart
asterisk -r &
sleep 5
systemctl start vicidial-astguiclient

Monitor AST_VDadapt Memory Usage

Track VDadapt's memory consumption over time:

watch -n 5 'ps aux | grep -i vdadapt | grep -v grep'

If a single process exceeds 500MB, restart the daemon:

killall -9 AST_VDadapt.pl
sleep 2
/usr/share/astguiclient/AST_VDadapt.pl &

Database Connection Issues

Verify MySQL Connectivity from Asterisk User

The asterisk system user must be able to connect to the ViciDial MySQL database:

sudo -u asterisk mysql -h localhost -u asterisk -p'asterisk_db_password' asterisk -e "SELECT COUNT(*) FROM vicidial_list;"

If this fails with "access denied" or "connection refused", verify:

MySQL service is running:

   systemctl status mysql
   # or
   systemctl status mariadb

Asterisk user credentials in /etc/asterisk/asterisk.conf:

   [asterisk-db]
   dbhost = localhost
   dbname = asterisk
   dbuser = asterisk
   dbpass = asterisk_db_password

MySQL user grants:

   GRANT ALL ON asterisk.* TO 'asterisk'@'localhost' IDENTIFIED BY 'asterisk_db_password';
   FLUSH PRIVILEGES;

Check for Database Locks

Long-running queries or deadlocks can block AST_VDadapt. Check for blocked processes:

SHOW PROCESSLIST;

Look for queries with long Time values or State = 'Locked'. Kill problematic queries:

KILL QUERY 12345;  -- Replace 12345 with the process ID

Verify vicidial_log Permissions

The asterisk user must have write access to log tables. Test an insert:

sudo -u asterisk mysql -h localhost -u asterisk -p'asterisk_db_password' asterisk -e \
"INSERT INTO vicidial_log (user, campaign_id, phone_number, call_date, call_time_start) 
 VALUES ('test', 'TEST_CAMPAIGN', '5551234567', NOW(), '00:00:00');"

If the insert fails, rebuild table permissions:

GRANT INSERT, UPDATE, SELECT ON asterisk.vicidial_log TO 'asterisk'@'localhost';
GRANT INSERT, UPDATE, SELECT ON asterisk.vicidial_list TO 'asterisk'@'localhost';
GRANT INSERT, UPDATE, SELECT ON asterisk.vicidial_campaigns TO 'asterisk'@'localhost';
FLUSH PRIVILEGES;

Real-World Configuration Example

Here's a complete, working configuration for a test campaign:

Campaign Setup

-- Create a test campaign
INSERT INTO vicidial_campaigns 
(campaign_id, campaign_name, active, dial_method, agents_logged_in, 
 rate_frame, calls_queued, carrier_id, max_leads_for_24hrs)
VALUES 
('TEST_CAMPAIGN', 'Test Campaign', 'Y', 'ADAPT', 0, 
 60, 10, 'SIP_CARRIER', 100);

-- Assign a user to the campaign
UPDATE vicidial_users 
SET campaign_id = 'TEST_CAMPAIGN', active = 'Y' 
WHERE user = 'test_agent';

-- Insert test leads
INSERT INTO vicidial_list 
(campaign_id, phone_number, status, gmt_offset_now, entry_date)
VALUES 
('TEST_CAMPAIGN', '5551234567', 'NEW', '-5', NOW()),
('TEST_CAMPAIGN', '5559876543', 'NEW', '-5', NOW()),
('TEST_CAMPAIGN', '5552468135', 'NEW', '-5', NOW());

Asterisk SIP Peer Configuration

; /etc/asterisk/sip-vicidial.conf

[SIP_CARRIER]
type=peer
host=sip.provider.com
port=5060
username=myaccount
secret=mypassword
fromuser=myaccount
fromdomain=sip.provider.com
insecure=port,invite
context=from-vicidial
disallow=all
allow=ulaw
allow=gsm
canreinvite=no
nat=yes
qualify=yes
qualifyfreq=60
maxcallbitrate=384

Dialplan Extension

; /etc/asterisk/extensions-vicidial.conf

[outbound-vicidial]
exten => _1[2-9]XX[2-9]XXXXXX,1,Dial(SIP/SIP_CARRIER/${EXTEN},45,tTwW)
exten => _1[2-9]XX[2-9]XXXXXX,n,Hangup()

exten => _[2-9]XX[2-9]XXXXXX,1,Dial(SIP/SIP_CARRIER/1${EXTEN},45,tTwW)
exten => _[2-9]XX[2-9]XXXXXX,n,Hangup()

Troubleshooting

Symptom: AST_VDadapt Process Crashes Repeatedly

Cause: Database connection loss, memory leak, or segmentation fault.

Solution:

Check Asterisk logs for core dumps:

   dmesg | tail -20
   ls -lh /tmp/core*

Monitor AST_VDadapt startup:

   # Kill any existing processes
   killall -9 AST_VDadapt.pl
   sleep 2

   # Run in foreground with verbose output
   /usr/share/astguiclient/AST_VDadapt.pl --debug 2>&1 | tee /tmp/vdadapt_debug.log

Watch for errors in the output. Common crashes:
- DBI->connect failed — MySQL unavailable
- Can't locate Asterisk/AGI.pm — Missing Perl module
- Segmentation fault — Corrupt Asterisk installation
Rebuild Perl modules if needed:

   cd /usr/src/asterisk-version/
   make menuselect
   # Select extra modules if needed
   make install

Symptom: Calls Dial but Hang Up Immediately

Cause: Incorrect carrier settings, NAT issues, or codec mismatch.

Solution:

Monitor the actual SIP traffic:

   asterisk -rx "sip set debug on"
   # Attempt a call
   # Watch the output for SIP errors
   asterisk -rx "sip set debug off"

Check the carrier's SIP authentication:

   asterisk -rx "sip show peers" | grep SIP_CARRIER

Look for UNREACHABLE status. If so, verify host/port/auth in the config.

Test carrier connectivity:

   # Direct SIP REGISTER test
   sipsak -U -C sip:myaccount@sip.provider.com -l 0 -s sip:sip.provider.com

Force codec to ULAW (most compatible):

   [SIP_CARRIER]
   disallow=all
   allow=ulaw

Symptom: Leads in vicidial_list but VDAD Reports "No Leads Available"

Cause: Lead status filtering, date/time constraints, or VDAD logic blocking.

Solution:

Check lead statuses directly:

   SELECT status, COUNT(*) 
   FROM vicidial_list 
   WHERE campaign_id = 'TEST_CAMPAIGN' 
   GROUP BY status;

VDAD typically dials only NEW, CALLBACK, or RECALL statuses. Verify your campaign calls the right statuses.

Check for timezone/callback time constraints:

   SELECT phone_number, status, entry_date, callback_date, callback_time 
   FROM vicidial_list 
   WHERE campaign_id = 'TEST_CAMPAIGN' 
     AND status = 'CALLBACK' 
     AND callback_date IS NOT NULL;

If callback times are in the future, they won't dial until that time arrives.

Reset stuck leads to NEW:

   UPDATE vicidial_list 
   SET status = 'NEW' 
   WHERE campaign_id = 'TEST_CAMPAIGN' 
     AND status IN ('DNCL', 'XDEL');

Symptom: "ERROR: No Carrier Available" in VDAD Logs

Cause: Campaign not linked to carrier, or carrier is inactive/offline.

Solution:

Verify carrier assignment:

   SELECT carrier_id FROM vicidial_campaigns 
   WHERE campaign_id = 'TEST_CAMPAIGN';

Verify carrier is active:

   SELECT carrier_id, active FROM vicidial_carrier_log 
   WHERE carrier_id = 'SIP_CARRIER';

Test Asterisk can reach the carrier:

   asterisk -rx "sip show peers" | grep -i carrier

Look for OK status, not UNREACHABLE.

Force a manual dial test via Asterisk console:

   asterisk -r
   channel originate SIP/SIP_CARRIER/5551234567 application wait 10

If this fails, the carrier is not configured correctly in Asterisk.

Symptom: High CPU Usage by AST_VDadapt, Dialing Is Slow

Cause: Inefficient database queries, large lead lists, or CPU contention.

Solution:

Profile the AST_VDadapt process:

   strace -c -p $(pgrep AST_VDadapt | head -1) 2>&1 | head -30

Identify slow database queries:

   -- Enable slow query log
   SET GLOBAL slow_query_log = 'ON';
   SET GLOBAL long_query_time = 2;
   -- Then check
   TAIL /var/log/mysql/slow.log

Add indexes to improve query performance:

   CREATE INDEX idx_campaign_status ON vicidial_list (campaign_id, status);
   CREATE INDEX idx_dnc_phone ON vicidial_dnc_list (phone_number);

Limit the number of AST_VDadapt processes:

   ps aux | grep AST_VDadapt | grep -v grep | wc -l

More than 3-4 processes may indicate runaway spawning. Restart:

   killall -9 AST_VDadapt.pl
   sleep 2
   /usr/share/astguiclient/AST_VDadapt.pl &

Summary

ViciDial VDAD not dialing is typically caused by one of these categories:

Process Issues: AST_VDadapt not running, crashing, or unable to connect to MySQL
Database Configuration: Missing leads, inactive campaigns, or agent login failures
Carrier/Trunk Issues: Missing or inactive SIP/IAX carrier, incorrect authentication, unreachable host
Dialplan Issues: Malformed extensions, missing contexts, or syntax errors
System Resources: Insufficient memory, high CPU load, or disk I/O bottlenecks

Quick Troubleshooting Checklist:

✅ Is AST_VDadapt process running? ps aux | grep AST_VDadapt
✅ Is the campaign active? SELECT active FROM vicidial_campaigns WHERE campaign_id = ?
✅ Are there leads to dial? SELECT COUNT(*) FROM vicidial_list WHERE campaign_id = ? AND status = 'NEW'
✅ Is an agent logged in? SELECT user FROM vicidial_agent_log WHERE campaign_id = ?
✅ Is the carrier configured and online? asterisk -rx "sip show peers"
✅ Does the dialplan load without errors? asterisk -rx "dialplan reload"
✅ Can MySQL be reached? mysql -u asterisk -p asterisk -e "SELECT 1"

Follow the sections above in order, test each component, and you'll identify the root cause. Most production VDAD failures are resolved within 15 minutes once you narrow down which subsystem is failing.

Asterisk Core Dump & Crash Analysis — Debugging Segfaults

Moisi Trungu — Sun, 09 Aug 2026 03:30:03 +0000

Asterisk Core Dump & Crash Analysis — Debugging Segfaults

Learn how to capture, analyze, and fix segmentation faults in production Asterisk systems running ViciDial by examining core dumps, generating backtraces, and identifying memory corruption and module conflicts.

Prerequisites

Before you start debugging core dumps, ensure you have:

Root access to your Asterisk/ViciDial server
GDB (GNU Debugger) installed: apt-get install gdb or yum install gdb
Asterisk debug symbols (compile from source with debug flags or install -debuginfo package)
Basic familiarity with Asterisk CLI commands and ViciDial architecture
Backup of your running system before making debugging changes
At least 2GB free disk space in /var/spool/asterisk/ for core dumps
Knowledge of your Asterisk version (run asterisk -V)

Understanding Core Dumps

What is a Core Dump?

A core dump is a file containing the memory snapshot of your process at the moment it crashed. When Asterisk segfaults, the kernel writes this memory to disk (if enabled), allowing you to inspect the call stack, variable states, and identify what caused the crash.

Why Core Dumps Matter in Production

In ViciDial environments, unpredictable crashes disrupt:

Active agent calls
Inbound call routing
Database synchronization
Lead distribution
Campaign execution

Core dumps let you identify whether crashes are caused by:

Custom modules or dialplan issues
SIP peer misconfigurations
Memory leaks in third-party codecs
Race conditions in high-concurrency scenarios
Incompatible module versions

Enabling Core Dumps on Linux

Step 1: Configure Kernel to Write Core Dumps

Check current core dump limit:

ulimit -c

If output is 0, core dumps are disabled. Enable unlimited core dumps:

ulimit -c unlimited

Make this permanent by adding to /etc/security/limits.conf:

# Allow asterisk user to generate unlimited core dumps
asterisk soft core unlimited
asterisk hard core unlimited
asterisk soft nofile 65536
asterisk hard nofile 65536

Verify:

su - asterisk -s /bin/bash -c "ulimit -c"

Expected output: unlimited

Step 2: Set Core Dump Location

Define where core files are written. Edit /etc/sysctl.conf:

kernel.core_pattern = /var/spool/asterisk/core-%e-%p-%t
kernel.core_uses_pid = 1

Apply immediately:

sysctl -p

This creates files like /var/spool/asterisk/core-asterisk-12345-1703020800 when crashes occur.

Step 3: Ensure Directory Permissions

mkdir -p /var/spool/asterisk
chown asterisk:asterisk /var/spool/asterisk
chmod 755 /var/spool/asterisk

Configuring Asterisk for Debug Output

Enable Core Dumps in asterisk.conf

Edit /etc/asterisk/asterisk.conf:

[options]
; Enable core dumps even when run as daemon
dumpcore = yes

; Log all debug output
debug = 3

; Verbose logging for call flow
verbose = 3

; Log warnings about lock contention
lockingtest = yes

Restart Asterisk (gracefully):

asterisk -rx "core restart graceful"

Wait for all channels to clear before Asterisk terminates.

Enable Module-Specific Debug

For SIP debugging (ViciDial primary protocol):

asterisk -rx "sip set debug on"
asterisk -rx "sip set debug ip 192.168.1.100"  # Debug single peer

For channel/bridge issues:

asterisk -rx "core set debug 3"

View live logs:

tail -f /var/log/asterisk/messages

Compiling Asterisk with Debug Symbols

If your Asterisk binary lacks debug symbols, backtraces will be useless. Recompile:

cd /usr/src/asterisk-16.x.x
./configure CFLAGS="-g -O0" CXXFLAGS="-g -O0"
make clean
make -j4
make install

Key flags:

-g: Include debug symbols
-O0: Disable optimization (makes symbols more readable; impacts performance)

Production tip: Compile with -g -O2 to balance debugging capability with performance.

Verify symbols are present:

file /usr/sbin/asterisk

Should show: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, with debug_info

nm -l /usr/sbin/asterisk | grep asterisk_log | head -5

Should return symbol entries, not empty output.

Triggering and Capturing a Crash

Safe Testing: Use Test Dialplan

Create a crashing dialplan in /etc/asterisk/extensions-test.conf:

[test-crash]
exten => 999,1,NoOp(Testing crash scenario)
exten => 999,n,SIPNotify(reboot,${CHANNEL})
exten => 999,n,Wait(2)
exten => 999,n,Hangup()

Or trigger via asterisk CLI:

asterisk -rx "core set debug 5"
asterisk -rx "dialplan eval ${SOME_BROKEN_VAR}"  # Intentional bad variable

Identify Recent Crashes

ls -lah /var/spool/asterisk/core-* 2>/dev/null | tail -10

ls -lah /tmp/core.* 2>/dev/null | tail -10

Check system logs for segmentation fault:

journalctl -xe | grep -i segfault
dmesg | grep -i segfault
tail -50 /var/log/syslog | grep -i "segmentation\|core dump"

Example journal output:

Nov 23 14:32:01 vicidial-01 kernel: [34567.891234] asterisk[12345]: segfault at 0x0 ip 00007ffff5a2c000 sp 00007fffabc12345 error 4

Analyzing Core Dumps with GDB

Step 1: Locate the Core File

ls -lah /var/spool/asterisk/core-asterisk-* | tail -1

Output example:

-rw------- 1 asterisk asterisk 324M Nov 23 14:32 /var/spool/asterisk/core-asterisk-12345-1700731920

Step 2: Start GDB Session

gdb /usr/sbin/asterisk /var/spool/asterisk/core-asterisk-12345-1700731920

You should see:

GNU gdb (Ubuntu 12.1-0ubuntu1~22.04) 12.1
Reading symbols from /usr/sbin/asterisk...
Reading symbols from /usr/lib/debug/.build-id/...
[New LWP 12345]
[New LWP 12346]
...
Core was generated by `/usr/sbin/asterisk -f'
Program terminated with signal SIGSEGV, Segmentation fault.

Step 3: Generate Full Backtrace

(gdb) thread apply all bt full

This shows the call stack for all threads. Example output:

Thread 47 (LWP 12389):
#0  0x00007ffff5a2c000 in chan_sip_pvt_lock () from /usr/lib/asterisk/modules/chan_sip.so
#1  0x00007ffff5a1f234 in sip_pvt_lock_full () from /usr/lib/asterisk/modules/chan_sip.so
#2  0x00007ffff5a3d123 in handle_incoming () from /usr/lib/asterisk/modules/chan_sip.so
#3  0x00007ffff5a2e456 in sip_io_read () from /usr/lib/asterisk/modules/chan_sip.so
#4  0x000055555555c789 in ast_channel_tech_read () at channel.c:5432
#5  0x000055555556b012 in __ast_read () at channel.c:4123
#6  0x000055555556c234 in ast_read () at channel.c:4234
#7  0x00007ffff7890000 in bridge_channel_wait_for_frame () from /usr/lib/asterisk/modules/app_bridging.so
#8  0x00007ffff7891200 in bridge_channel_run () from /usr/lib/asterisk/modules/app_bridging.so
#9  0x000055555558c345 in ast_spawn_extension () at pbx.c:3912
#10 0x000055555558c600 in pbx_exec () at pbx.c:4012
#11 0x00007ffff6234567 in handle_request_invite () from /usr/lib/asterisk/modules/chan_sip.so

Step 4: Focus on the Crashing Thread

Find the thread that crashed (typically reported first):

(gdb) thread 1
(gdb) bt

Limit output to top 20 frames:

(gdb) bt 20

Step 5: Inspect Variables at Crash Point

(gdb) frame 0
(gdb) info local
(gdb) print *variablename
(gdb) print sizeof(structname)

Example: Check if a pointer is NULL:

(gdb) print pvt
$1 = (struct sip_pvt *) 0x0

A NULL pointer dereference is your culprit.

Step 6: Examine SIP Channel State

For ViciDial crashes, inspect the SIP channel context:

(gdb) frame 2
(gdb) print pvt->callid
(gdb) print pvt->dialplan
(gdb) print pvt->thestate
(gdb) print pvt->lastinvite

Common Crash Patterns in ViciDial

Pattern 1: Null Pointer Dereference in SIP Module

Symptom: Crash in chan_sip.so when handling INVITE

Backtrace indicator:

#0  0x... in chan_sip_pvt_lock
#1  0x... in handle_incoming
#2  0x... in sip_io_read

Root cause: SIP peer object deallocated while handling incoming request.

Debugging:

(gdb) print pvt
$1 = (struct sip_pvt *) 0x0
(gdb) print dialog
$2 = (struct sip_pvt *) 0x0

Fix: Add NULL check in custom dialplan or module. Check /etc/asterisk/sip-vicidial.conf for stale peer configs:

asterisk -rx "sip show peers" | grep -i "UNREACHABLE\|LAGGED"

Remove outdated peers:

asterisk -rx "sip prune peers"

Pattern 2: Memory Leak Leading to Crash

Symptom: Asterisk runs fine initially, crashes after hours/days of operation.

Indicator: Check memory usage:

ps aux | grep asterisk | grep -v grep
# Look at RSS column (resident set size)

Monitor over time:

watch -n 5 'ps aux | grep asterisk | grep -v grep'

If RSS grows continuously, memory leak is present. Backtrace will show:

#0  0x... in malloc (or realloc)

Debugging: Enable MALLOC_DEBUG in Asterisk:

Edit /etc/asterisk/asterisk.conf:

[options]
allowmultiple = no
astdb = /var/lib/asterisk/astdb.sqlite3
debug = 3
verbose = 3
dumpcore = yes

Recompile Asterisk with:

./configure --with-malloc-debug
make
make install

Then run GDB and check memory allocator:

(gdb) handle SIG35 noprint nostop
(gdb) continue
# ... let it run and crash ...
(gdb) bt
(gdb) print heapmgr

Pattern 3: Race Condition in Database Access

Symptom: Intermittent crashes when multiple channels access ViciDial database tables simultaneously.

Affected tables: vicidial_log, vicidial_closer_log, vicidial_carrier_log

Backtrace indicator:

#0  0x... in ast_db_get
#1  0x... in ast_app_parse_timezones
#2  0x... in custom_app_exec

Debugging: Check for missing table locks in custom AGI scripts or dialplan:

grep -r "astdb\|ast_db_get" /etc/asterisk/extensions-vicidial.conf | head -20

Fix: Use dialplan locks when accessing shared resources:

exten => 100,1,Lock(vicidial-db-lock)
exten => 100,n,NoOp(Safe database access)
exten => 100,n,Unlock(vicidial-db-lock)

Or use database transactions in AGI scripts:

#!/bin/bash
# Safe database query in AGI
(
  flock -x 200
  mysql -N -e "SELECT * FROM vicidial_log WHERE lead_id = $LEAD_ID LIMIT 1" asterisk
) 200>/var/lock/vicidial-db.lock

Pattern 4: Module Incompatibility

Symptom: Crash when loading custom module or third-party codec.

Backtrace indicator:

#0  0x... in module_symbol_not_found
#1  0x... in dlopen

Debugging: Check loaded modules:

asterisk -rx "module show loaded" | grep -i "custom\|third"

Check module dependencies:

ldd /usr/lib/asterisk/modules/codec_custom.so | grep -i "not found"

Fix: Rebuild module with correct Asterisk version:

cd /usr/src/asterisk-16.x.x/addons
make clean
make
make install

Verify module loads without errors:

asterisk -rx "module load codec_custom"
asterisk -rx "core show settings" | grep "Build Date"

Creating a Core Dump Archive for Analysis

Preserve crashes for later investigation or vendor support:

#!/bin/bash
# save_core_dump.sh

CORE_FILE=$1
ARCHIVE_DIR="/var/spool/asterisk/crash-archives"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)

mkdir -p $ARCHIVE_DIR

# Tar the core and associated binaries
tar -czf $ARCHIVE_DIR/crash-$TIMESTAMP.tar.gz \
  $CORE_FILE \
  /usr/sbin/asterisk \
  /usr/lib/asterisk/modules/*.so \
  /etc/asterisk/ \
  /var/log/asterisk/messages \
  2>/dev/null

# Generate backtrace for quick reference
gdb -batch -ex "bt" /usr/sbin/asterisk $CORE_FILE > \
  $ARCHIVE_DIR/crash-$TIMESTAMP.backtrace.txt 2>&1

echo "Core dump archived: $ARCHIVE_DIR/crash-$TIMESTAMP.tar.gz"
echo "Backtrace: $ARCHIVE_DIR/crash-$TIMESTAMP.backtrace.txt"

Usage:

chmod +x /usr/local/bin/save_core_dump.sh
/usr/local/bin/save_core_dump.sh /var/spool/asterisk/core-asterisk-12345-1700731920

Automated Crash Detection and Response

Create a Core Dump Watcher

#!/bin/bash
# /usr/local/bin/asterisk-crash-monitor.sh

CORE_DIR="/var/spool/asterisk"
LOG_FILE="/var/log/asterisk/crash-monitor.log"
ALERT_EMAIL="admin@example.com"

check_for_new_cores() {
  find $CORE_DIR -name "core-*" -type f -mmin -5 2>/dev/null | while read core_file; do
    timestamp=$(date '+%Y-%m-%d %H:%M:%S')

    # Extract backtrace
    backtrace=$(gdb -batch -ex "bt 30" /usr/sbin/asterisk "$core_file" 2>&1 | tail -50)

    # Log incident
    echo "[$timestamp] Crash detected: $core_file" >> $LOG_FILE
    echo "$backtrace" >> $LOG_FILE
    echo "---" >> $LOG_FILE

    # Send alert
    echo "$backtrace" | mail -s "Asterisk Crash: $(hostname)" $ALERT_EMAIL

    # Restart Asterisk if needed
    if ! pgrep -x asterisk > /dev/null; then
      systemctl start asterisk
      echo "[$timestamp] Asterisk restarted" >> $LOG_FILE
    fi
  done
}

# Run every 2 minutes
while true; do
  check_for_new_cores
  sleep 120
done

Install as systemd service:

# /etc/systemd/system/asterisk-crash-monitor.service
[Unit]
Description=Asterisk Crash Monitor
After=network.target
Wants=asterisk.service

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/asterisk-crash-monitor.sh
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable:

systemctl daemon-reload
systemctl enable asterisk-crash-monitor
systemctl start asterisk-crash-monitor

GDB Automation Script

For unattended backtrace generation:

#!/bin/bash
# /usr/local/bin/extract_backtrace.sh

CORE_FILE=$1
BINARY="/usr/sbin/asterisk"
OUTPUT="${CORE_FILE}.backtrace.txt"

gdb -batch \
  -ex "thread apply all bt full" \
  -ex "quit" \
  $BINARY $CORE_FILE > $OUTPUT 2>&1

echo "Backtrace written to: $OUTPUT"
cat $OUTPUT

Usage:

/usr/local/bin/extract_backtrace.sh /var/spool/asterisk/core-asterisk-12345-1700731920

ViciDial-Specific Debugging Tips

Check for Lead Lock Deadlocks

ViciDial's lead distribution can deadlock when multiple processes compete for the same lead:

asterisk -rx "database show vicidial-lead-locks" | head -20

If locks don't clear within seconds, investigate:

mysql> SELECT * FROM vicidial_log WHERE lead_id = <LEAD_ID> ORDER BY entry_date DESC LIMIT 1\G

Clear stale locks manually (if safe):

asterisk -rx "database deltree vicidial-lead-locks"

Monitor Call Bridge Issues

ViciDial bridges agent and carrier channels. Crashes often occur at bridge setup:

asterisk -rx "core set debug 3"
asterisk -rx "bridge show all"

Check for stuck bridges:

asterisk -rx "channel show all" | wc -l

If channel count grows unbounded, bridge leak exists. Restart may be necessary:

asterisk -rx "core restart graceful"

Review Dialplan Syntax

Dialplan errors can trigger crashes in edge cases. Validate:

asterisk -rx "dialplan reload"

Check for warnings in /var/log/asterisk/messages:

grep -i "warning\|error" /var/log/asterisk/messages | tail -50

Inspect AGI Script Failures

Custom AGI scripts sometimes cause Asterisk to crash. Test scripts in isolation:

/var/lib/asterisk/agi-bin/vicidial_loader.agi test

Add error handling to AGI scripts:

#!/bin/bash
trap 'echo "HANGUP" >&3' EXIT
trap 'exit' SIGTERM

while read -t 1 line; do
  case "$line" in
    agi_uniqueid:*) UNIQUEID="${line#*: }" ;;
    agi_calleridnum:*) CALLERID="${line#*: }" ;;
  esac
  [ -z "$line" ] && break
done

echo "EXEC Hangup" >&3

Troubleshooting

Issue: Core Dumps Not Being Generated

Check 1: ulimit

ulimit -c

Should return unlimited. If not:

ulimit -c unlimited
echo "ulimit -c unlimited" >> /etc/profile

Check 2: File System Space

df -h /var/spool/asterisk

If full, clean old cores:

rm -f /var/spool/asterisk/core-*

Check 3: SELinux

If enabled, SELinux may block core dumps:

getenforce

If Enforcing, add policy:

semanage fcontext -a -t asterisk_var_spool_t "/var/spool/asterisk(/.*)?"
restorecon -Rv /var/spool/asterisk

Issue: GDB Backtrace Shows "??" Instead of Function Names

Cause: Missing debug symbols.

Fix: Recompile Asterisk with -g flag:

./configure CFLAGS="-g -O2"
make -j4
make install

Verify:

gdb /usr/sbin/asterisk -batch -ex "file /usr/sbin/asterisk" -ex "quit" 2>&1 | grep "debug_info"

Issue: GDB Takes Too Long to Load Large Core Files

Workaround: Use gdb --nx to skip initialization:

gdb --nx /usr/sbin/asterisk /var/spool/asterisk/core-asterisk-12345-1700731920

Or extract backtrace without full symbols:

gdb -batch -ex "bt" /usr/sbin/asterisk /var/spool/asterisk/core-asterisk-12345-1700731920 2>&1 | head -100

Issue: Asterisk Keeps Crashing in Infinite Loop

Diagnosis: Check crash frequency:

ls -lh /var/spool/asterisk/core-* | wc -l

Disable automatic restart temporarily:

systemctl stop asterisk

Run Asterisk in foreground with debug:

asterisk -f -d -v -v -v

Stop at first crash with Ctrl+C. Review console output for error messages.

Issue: Backtrace Points to Third-Party Module, But Module Isn't Loaded

Cause: Module was loaded in a previous process instance, shared library is corrupted.

Fix: Force reload all modules:

asterisk -rx "module reload FORCE"

If crash persists:

asterisk -rx "module unload extra/codec_custom"

Rebuild module:

cd /usr/src/asterisk-16.x.x/addons
make clean
./configure --with-asterisk=/usr
make
make install

Summary

Debugging Asterisk core dumps in production ViciDial environments requires:

Preparation: Enable core dumps at OS, kernel, and Asterisk levels. Compile with debug symbols.
Capture: Monitor /var/spool/asterisk/ for new core files. Log crash timestamps and associated system state.
Analysis: Use GDB to extract full backtraces with thread apply all bt full. Focus on the faulting thread. Inspect variable states at crash point.
Pattern Recognition: Know common ViciDial crash patterns—SIP channel deallocation, database race conditions, memory leaks, module incompatibilities.
ViciDial-Specific Checks: Verify lead locks aren't stuck, call bridges aren't leaking, dialplan is valid, AGI scripts have error handling.
Response: Automate crash detection with systemd services. Generate backtrace archives for vendor support. Implement graceful restarts to minimize call loss.
Remediation: Address root causes—patch Asterisk, rebuild incompatible modules, refactor dialplan, fix AGI scripts, update SIP peers.

Core dumps are your most powerful debugging tool in production. Invest in capturing and preserving them. A single backtrace can save weeks of troubleshooting and prevent recurring crashes that destroy agent productivity and customer experience.

Keep backtraces, logs, and configurations together when escalating to Asterisk support or ViciDial engineers. Always test fixes in staging before deploying to production.

SIP 408 Request Timeout — Network & Firewall Troubleshooting

Moisi Trungu — Sat, 08 Aug 2026 03:30:02 +0000

SIP 408 Request Timeout — Network & Firewall Troubleshooting

Master the complete diagnostic and resolution process for SIP 408 errors in ViciDial and Asterisk production environments, covering network analysis, firewall rules, SIP configuration tuning, and carrier-level debugging.

Prerequisites

Before diving into this tutorial, ensure you have:

A running ViciDial/Asterisk installation (tested on 2.14+)
SSH access to your Asterisk server with sudo privileges
Basic understanding of SIP protocol and VoIP concepts
Network diagnostic tools: tcpdump, netstat, iptables
Access to /etc/asterisk/ configuration directory
ViciDial database access (MySQL/MariaDB)
Knowledge of your carrier's SIP trunk details
Ability to check firewall rules and NAT configuration

Understanding SIP 408 Request Timeout

What Is SIP 408?

The SIP 408 (Request Timeout) response indicates that the Asterisk server did not receive a response from the remote SIP endpoint (usually your carrier's SIP trunk) within the expected timeframe. This is fundamentally different from call failures caused by rejection—the server is simply not answering.

Common Scenarios in ViciDial

Outbound calls hang: Agents see "no answer" or calls drop during routing
Inbound calls fail: DIDs receive no connection attempts from carrier
Intermittent issues: Timeout occurs randomly, typically under load
Carrier-specific problems: One carrier works, another doesn't

The root cause is always one of these categories:

Network connectivity issues (firewall blocking, NAT misconfiguration)
SIP timeout values too aggressive for your infrastructure
Asymmetric routing or packet loss
Carrier not properly configured or experiencing issues
DNS resolution failures
RTP port range problems

Network Diagnostics: Foundational Steps

Step 1: Verify Basic Connectivity

Start by confirming your Asterisk server can reach your SIP carrier:

# Test carrier IP/hostname resolution
nslookup sip.yourcarrier.com
dig sip.yourcarrier.com +short

# Ping the carrier (may be disabled by carrier, but worth trying)
ping -c 5 203.0.113.50

# Test SIP port connectivity with nc (netcat)
nc -zv 203.0.113.50 5060
nc -zv 203.0.113.50 5061

# More detailed test with timeout
timeout 5 bash -c 'echo > /dev/tcp/203.0.113.50/5060' && echo "Port 5060 is open" || echo "Port 5060 is closed"

Step 2: Check Asterisk Binding

Verify that Asterisk is properly binding to the correct interface:

# View all SIP ports Asterisk is listening on
netstat -tlnp | grep asterisk | grep -E '5060|5061'

# Example output should show:
# tcp  0  0 0.0.0.0:5060  0.0.0.0:*  LISTEN  1234/asterisk
# udp  0  0 0.0.0.0:5060  0.0.0.0:*           1234/asterisk

If Asterisk is only binding to 127.0.0.1 or a specific internal IP, external carriers cannot reach it.

Step 3: Analyze Outbound Packet Flow

Use tcpdump to capture SIP packets and identify where the conversation breaks:

# Capture SIP traffic to/from your carrier
tcpdump -i any -n -s 0 -vvv host 203.0.113.50 and port 5060 -w /tmp/sip_capture.pcap

# In another terminal, initiate a test call, then stop capture with Ctrl+C

# View the capture in human-readable format
tcpdump -r /tmp/sip_capture.pcap -vvv | head -100

# Count SIP messages by type
tcpdump -r /tmp/sip_capture.pcap | grep -oE 'SIP/2.0 [A-Z]+ |^[A-Z]+ sip:' | sort | uniq -c

Look for this pattern:

INVITE sent to carrier (your server → carrier)
100 Trying received from carrier (carrier → your server)
INVITE TIMEOUT (no 183/180/200 response)
BYE sent (cleanup)

If you see INVITE but no response, the issue is almost certainly carrier-side or network-path related.

Step 4: Monitor Real-Time SIP Sessions

While making test calls, observe Asterisk's SIP channel state:

# SSH to Asterisk server
asterisk -rx "sip show channels" | grep -E 'Channel|TO|FROM'

# Example output:
# Channel              State     Type      Exten     Context     
# SIP/carrier-0000001f DOWN      INVITE    s         from-external

# Get detailed info on a specific channel
asterisk -rx "sip show channel SIP/carrier-0000001f"

Firewall Configuration & NAT

Understanding the Firewall Problem

The most common cause of 408 timeouts in production ViciDial systems is asymmetric firewall rules or NAT configuration. Your outbound packets reach the carrier, but their responses are blocked coming back.

Firewall Rules: Bulletproof Configuration

# First, determine your internal IP and external carrier IP
# Internal SIP IP (usually private):
ip addr show | grep "inet " | grep -v 127.0.0.1

# External interface (usually eth0, ens0, etc.):
ip route | grep default

# Check current iptables rules
iptables -L -n -v | grep -E '5060|5061|10000:20000'

# If using UFW (Ubuntu/Debian):
ufw status

Proper firewall rules for a ViciDial system:

# Allow SIP from your carrier (CRITICAL)
iptables -I INPUT -p udp --dport 5060 -s 203.0.113.50 -j ACCEPT
iptables -I INPUT -p tcp --dport 5060 -s 203.0.113.50 -j ACCEPT
iptables -I INPUT -p udp --dport 5061 -s 203.0.113.50 -j ACCEPT
iptables -I INPUT -p tcp --dport 5061 -s 203.0.113.50 -j ACCEPT

# Allow RTP audio stream (critical!)
iptables -I INPUT -p udp --dport 10000:20000 -s 203.0.113.50 -j ACCEPT

# Allow established/related connections
iptables -I INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# Allow loopback (internal communication)
iptables -I INPUT -i lo -j ACCEPT

# Outbound: Allow SIP to carrier
iptables -I OUTPUT -p udp --dport 5060 -d 203.0.113.50 -j ACCEPT
iptables -I OUTPUT -p tcp --dport 5060 -d 203.0.113.50 -j ACCEPT
iptables -I OUTPUT -p udp --dport 5061 -d 203.0.113.50 -j ACCEPT
iptables -I OUTPUT -p tcp --dport 5061 -d 203.0.113.50 -j ACCEPT

# Allow RTP outbound
iptables -I OUTPUT -p udp --dport 10000:20000 -d 203.0.113.50 -j ACCEPT

# Save rules permanently (iptables-persistent)
iptables-save > /etc/iptables/rules.v4

UFW Configuration (Modern Ubuntu/Debian)

# Enable UFW if not already
sudo ufw enable

# Allow from carrier (replace with your carrier IP)
sudo ufw allow from 203.0.113.50 to any port 5060 proto udp
sudo ufw allow from 203.0.113.50 to any port 5061 proto tcp
sudo ufw allow from 203.0.113.50 to any port 10000:20000 proto udp

# Allow SSH to not lock yourself out
sudo ufw allow ssh

# Check active rules
sudo ufw status verbose

NAT Configuration

If your ViciDial server is behind NAT, Asterisk must know its public IP:

# Edit main SIP config
nano /etc/asterisk/sip-vicidial.conf

# Find or add these lines under [general]:
externip = 203.0.113.100           ; Your PUBLIC IP (not carrier IP)
localnet = 192.168.1.0/24          ; Your INTERNAL network
nat = yes                           ; Enable NAT processing

If using a dynamic public IP (not recommended for production), use:

[general]
externhost = mypublicip.dyndns.org
localnet = 192.168.1.0/24
nat = yes

After NAT changes, reload Asterisk:

asterisk -rx "sip reload"

Asterisk SIP Configuration Tuning

Aggressive vs. Conservative Timeout Values

The default SIP timeout in Asterisk (6 seconds) is too aggressive for international carriers or congested networks. ViciDial's default is better, but still needs tuning.

# Backup current config
cp /etc/asterisk/sip-vicidial.conf /etc/asterisk/sip-vicidial.conf.backup.$(date +%s)

# Edit the main SIP configuration
nano /etc/asterisk/sip-vicidial.conf

Add or modify these parameters in the [general] section:

[general]
; === Timeout Configuration ===
; Default SIP invite timeout in milliseconds (default: 6000)
; For unstable/international carriers, increase to 15000-30000
sip_t1 = 500                    ; Initial timeout between retransmissions (ms)
sip_t1min = 100                 ; Minimum T1 value (ms)
sip_invite_timeout = 30         ; Timeout for INVITE responses (seconds)
sip_register_timeout = 20       ; Registration timeout

; === Retransmission Policy ===
; Number of retransmissions before giving up
; Default is usually 6, which means ~32 seconds total
; For ViciDial production: 8-10 is safer
max_retries = 8

; === Connection Management ===
; Timeout for idle connections (seconds)
; Prevents phantom timeouts from long-lived connections
tcp_connect_timeout = 10
tcp_read_timeout = 10

; === Keep-Alive / Session-Timer ===
; Enable session timers to refresh connection state
session_timer = 1800            ; Session timer in seconds (30 minutes)
session_refresher = uas          ; Who refreshes: uas, uac, or auto
session_expires = 1800
min_se = 90

; === Other Critical Settings ===
; Disable aggressive NAT if you've configured externip correctly
directmedia = no               ; Force media through Asterisk (safer)
nat = yes                       ; Enable NAT mode
qualify = 100                   ; Send OPTIONS to peers every 100ms
qualify_timeout = 2             ; Timeout for qualify (seconds)

Carrier-Specific Configuration

Each carrier endpoint needs its own timeout values. In the [carrier_name] sections:

[mycarrier]
type = peer
host = sip.mycarrier.com
port = 5060
context = from-carrier
fromdomain = mycarrier.com
fromname = ViciDial-System
disallow = all
allow = ulaw,alaw
insecure = port,invite
nat = yes
directmedia = no

; Carrier-specific timeouts
sip_t1 = 1000                   ; Longer initial timeout for this carrier
sip_invite_timeout = 45         ; Very tolerant timeout
qualify = yes
qualify_timeout = 3             ; Longer qualify timeout

Check Configuration Syntax

Before reloading, validate the configuration:

# Validate SIP config
asterisk -C /etc/asterisk/asterisk.conf -n

# If valid, reload SIP module
asterisk -rx "sip reload"

# Verify the changes took effect
asterisk -rx "sip show settings" | grep -i timeout

ViciDial-Specific Configuration

Update ViciDial Carrier Settings via Database

Some timeout settings are stored in the ViciDial database, not Asterisk config:

# Access ViciDial database
mysql -u root -p asterisk

-- View your carriers
SELECT carrier_id, carrier_name, active FROM vicidial_carriers;

-- Check SIP carrier details
SELECT * FROM vicidial_sip_headers WHERE carrier_id = 'YOUR_CARRIER' \G

-- Update carrier settings (e.g., increase timeout)
UPDATE vicidial_carriers 
SET notes = 'Timeout 45s, Qualify enabled'
WHERE carrier_id = 'YOUR_CARRIER';

-- Check if there are carrier-specific SIP parameters
SELECT * FROM vicidial_sip_headers LIMIT 10;

Verify ViciDial Dialplan Integration

ViciDial's dialplan in /etc/asterisk/extensions-vicidial.conf must properly route to carriers:

grep -n "from-carrier\|from-external" /etc/asterisk/extensions-vicidial.conf | head -20

# Should show proper routing contexts for incoming calls from carrier

Check the ViciDial web admin panel for carrier configuration:

Navigate to /vicidial/admin.php
Go to Carriers section
Edit your SIP carrier
Verify:
- Carrier IP/Host: Correct
- Carrier Port: Usually 5060
- Protocol: SIP UDP or TCP
- DID Pattern: Matches your incoming numbers
- Active: Yes

Real-World Troubleshooting Scenarios

Scenario 1: Intermittent Timeouts Under Load

Symptom: Timeouts happen when call volume is high, not during testing.

Root Cause: Network congestion or Asterisk overload causing response delays.

Solution:

# Check Asterisk CPU and memory under load
top -p $(pgrep asterisk)

# Check network interface statistics
netstat -i

# Monitor packet loss
mtr -r -c 100 203.0.113.50 | tail -5

# If packet loss > 2%, contact carrier or ISP
# If Asterisk CPU > 80%, increase server resources or reduce call load

Increase SIP timeouts further:

[general]
sip_invite_timeout = 60
max_retries = 10

Scenario 2: International Carrier Timeouts

Symptom: Timeouts to UK, India, or other remote carriers, but domestic calls work fine.

Root Cause: High latency on international routes (normal 100-300ms).

Solution:

# Measure latency to carrier
ping -c 20 sip.international-carrier.com | grep -E 'min/avg/max'

# Example output: min/avg/max = 150.234/175.123/200.456 ms
# With this latency, set sip_t1 to ~200-250ms

Configure for international:

[international_carrier]
type = peer
host = sip.international-carrier.com
sip_t1 = 250                    ; Match latency
sip_invite_timeout = 60         ; Very tolerant
max_retries = 10
qualify = yes
qualify_timeout = 5

Scenario 3: DNS Resolution Failures

Symptom: Carrier works sometimes, then stops. Logs show "unresolved"

Root Cause: Carrier hostname not resolving, or DNS is failing intermittently.

Solution:

# Check Asterisk's DNS resolution
nslookup sip.carrier.com
dig sip.carrier.com

# Force Asterisk to use specific nameserver in /etc/asterisk/asterisk.conf:
# [options]
# Don't add this to asterisk.conf typically, instead use system resolver

# Check /etc/resolv.conf
cat /etc/resolv.conf

# Add reliable nameservers (Google DNS, Cloudflare DNS)
# Edit /etc/resolv.conf or netplan config

# For Ubuntu 20.04+ (Netplan):
nano /etc/netplan/00-installer-config.yaml

# Add:
# nameservers:
#   addresses: [8.8.8.8, 8.8.4.4, 1.1.1.1]

netplan apply

# Verify:
nslookup sip.carrier.com

Use carrier IP directly instead of hostname (if stable):

[carrier]
type = peer
host = 203.0.113.50             ; Use IP instead of hostname
; ... rest of config

Scenario 4: One-Way Audio (RTP Issues)

Symptom: Calls connect (no 408), but no audio. Often misdiagnosed as timeout.

Root Cause: RTP ports blocked or NAT misconfiguration.

Solution:

# Ensure RTP port range is open
grep "rtpstart\|rtpend" /etc/asterisk/rtp.conf

# Should show something like:
# rtpstart=10000
# rtpend=20000

# Verify firewall allows RTP
iptables -L -n -v | grep "10000:20000"

# If not present, add:
iptables -I INPUT -p udp --dport 10000:20000 -j ACCEPT
iptables -I OUTPUT -p udp --dport 10000:20000 -j ACCEPT

# For carrier-specific NAT, ensure externip includes RTP:
# In sip.conf: externip = YOUR_PUBLIC_IP (applies to all media)

Verify RTP is actually flowing:

# Tcpdump on RTP port range during call
tcpdump -i any -n 'udp portrange 10000-20000' -c 50

Monitoring and Alerting

Set Up Asterisk Logging for SIP Issues

Configure detailed SIP logging:

# Edit logger configuration
nano /etc/asterisk/logger.conf

# Add these lines:
[logfiles]
sip => WARNING,NOTICE,DEBUG
messages => WARNING,NOTICE,ERROR

# Optionally log to separate file:
# messages => WARNING,NOTICE,ERROR(/var/log/asterisk/sip-debug.log)

Reload logging:

asterisk -rx "logger reload"

# Tail the debug log
tail -f /var/log/asterisk/messages | grep -i "sip\|timeout"

Monitor 408 Errors in ViciDial Logs

# Check ViciDial call logs for 408 patterns
mysql -u root -p asterisk << 'EOF'
SELECT call_date, vicidial_id, length_in_sec, hangup_cause
FROM vicidial_log
WHERE hangup_cause LIKE '%408%' OR hangup_cause LIKE '%timeout%'
AND call_date >= DATE_SUB(NOW(), INTERVAL 1 DAY)
LIMIT 20;
EOF

# Check closer log (agent-initiated calls)
mysql -u root -p asterisk << 'EOF'
SELECT call_date, closer_id, length_in_sec, hangup_reason
FROM vicidial_closer_log
WHERE hangup_reason LIKE '%timeout%'
AND call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR);
EOF

Create a Real-Time Monitoring Script

#!/bin/bash
# File: /usr/local/bin/monitor-sip-408.sh

CARRIER_IP="203.0.113.50"
ALERT_EMAIL="admin@yourcompany.com"
THRESHOLD=10  # Alert if 10+ timeouts in 5 minutes

while true; do
    # Count recent 408s from tcpdump (5 minute window)
    TIMEOUT_COUNT=$(timeout 10 tcpdump -i any -n "host $CARRIER_IP and port 5060" -A 2>/dev/null | \
                    grep -c "SIP/2.0 408")

    if [ "$TIMEOUT_COUNT" -gt "$THRESHOLD" ]; then
        echo "ALERT: $TIMEOUT_COUNT SIP 408 timeouts detected" | \
        mail -s "ViciDial SIP 408 Alert" "$ALERT_EMAIL"

        # Log to asterisk messages
        asterisk -rx "log channel verbose \"ALERT: High 408 timeout rate detected: $TIMEOUT_COUNT\""
    fi

    sleep 300  # Check every 5 minutes
done

Make it executable and add to cron:

chmod +x /usr/local/bin/monitor-sip-408.sh

# Add to crontab
(crontab -l 2>/dev/null; echo "@reboot /usr/local/bin/monitor-sip-408.sh &") | crontab -

Troubleshooting Checklist

Use this systematic approach when 408 errors occur:

#!/bin/bash
# ViciDial SIP 408 Diagnostic Checklist

echo "=== SIP 408 Troubleshooting Checklist ==="
echo ""

# 1. Network Connectivity
echo "[1] Testing carrier connectivity..."
CARRIER_IP="203.0.113.50"
timeout 5 bash -c "echo > /dev/tcp/$CARRIER_IP/5060" && echo "✓ Port 5060 accessible" || echo "✗ Port 5060 blocked"

# 2. Asterisk Binding
echo "[2] Checking Asterisk SIP bindings..."
netstat -tlnp 2>/dev/null | grep asterisk | grep 5060 && echo "✓ Asterisk listening on 5060" || echo "✗ Asterisk not bound to 5060"

# 3. Firewall Rules
echo "[3] Verifying firewall rules..."
iptables -L -n 2>/dev/null | grep -q "5060" && echo "✓ Firewall rules exist" || echo "✗ No firewall rules found"

# 4. RTP Configuration
echo "[4] Checking RTP port range..."
grep -E "rtpstart|rtpend" /etc/asterisk/rtp.conf && echo "✓ RTP configured" || echo "✗ RTP config missing"

# 5. NAT Configuration
echo "[5] Verifying NAT settings..."
grep "externip\|nat" /etc/asterisk/sip-vicidial.conf | head -3

# 6. Timeout Values
echo "[6] SIP timeout settings..."
grep -E "sip_invite_timeout|sip_t1|max_retries" /etc/asterisk/sip-vicidial.conf | head -5

# 7. Active Channels
echo "[7] Current SIP channels..."
asterisk -rx "sip show channels" 2>/dev/null | head -10

# 8. Carrier Status
echo "[8] Carrier registration status..."
asterisk -rx "sip show peers" 2>/dev/null | grep -i carrier

# 9. Recent Errors
echo "[9] Recent SIP errors in logs..."
tail -20 /var/log/asterisk/messages | grep -i "408\|timeout\|sip"

echo ""
echo "=== End Diagnostic ==="

Save as /usr/local/bin/check-sip-408.sh and run:

chmod +x /usr/local/bin/check-sip-408.sh
./check-sip-408.sh

Summary

SIP 408 Request Timeout errors in ViciDial are almost always caused by one of these factors:

Firewall/NAT Issues (most common): Ensure inbound SIP/RTP from carrier is explicitly allowed, and externip is correctly set.
Aggressive Timeouts: Increase sip_invite_timeout to 30-60 seconds and sip_t1 to 500-1000ms for production stability.
Network Path Problems: Verify latency with ping/mtr, use tcpdump to confirm packets reach Asterisk.
Carrier Configuration: Double-check carrier IP, port, and context routing in both /etc/asterisk/sip-vicidial.conf and ViciDial database.
DNS Failures: Use carrier IPs directly if hostname resolution is unreliable.

Quick Fix Procedure:

Run /usr/local/bin/check-sip-408.sh to identify the issue
If firewall: Add rules with iptables or ufw
If timeouts: Update /etc/asterisk/sip-vicidial.conf with carrier-specific settings
If NAT: Verify externip matches your public IP
Reload SIP: asterisk -rx "sip reload"
Test with tcpdump to confirm fix
Monitor logs: tail -f /var/log/asterisk/messages

Most 408 issues resolve within 30 minutes using this systematic approach. Document your carrier-specific settings for future reference, and implement monitoring to catch issues before users report them.

SIP 503 Service Unavailable — Carrier & Server-Side Fixes

Moisi Trungu — Fri, 07 Aug 2026 03:30:02 +0000

SIP 503 Service Unavailable — Carrier & Server-Side Fixes

Learn how to diagnose and resolve SIP 503 errors in ViciDial and Asterisk production environments, with carrier-side and server-side remediation strategies

Prerequisites

Before implementing the fixes in this tutorial, ensure you have:

Root or sudo access to your ViciDial/Asterisk server
SSH terminal access to the production system
Basic understanding of SIP protocol and VoIP call flow
Access to /etc/asterisk/ configuration directory
MySQL/MariaDB access to the asterisk database
Asterisk CLI knowledge (asterisk -rx commands)
A working ViciDial installation (tested on 2.14+)
Network monitoring tools: tcpdump, tshark, or similar
Carrier/trunk documentation and support contact information

Understanding SIP 503 Service Unavailable

What Is a 503 Error?

A SIP 503 Service Unavailable response indicates that the server (or the route to it) is temporarily unable to handle the request. In ViciDial and Asterisk environments, this typically means:

Carrier side: The carrier's SIP infrastructure is overloaded, under maintenance, or rejecting calls
Server side: Your Asterisk instance is overloaded, channels are exhausted, or no available trunks exist
Routing side: The dial plan cannot find a valid route to the destination

The 503 is not a call rejection due to invalid credentials or blocked numbers—those are 401, 403, or 486. A 503 means "temporarily unavailable, try again later."

Common Causes in ViciDial

Insufficient trunk channels on carrier connections
Carrier API/service outage or maintenance window
Max channels exceeded on the Asterisk server
Codec mismatch between endpoints
NAT/firewall blocking SIP responses
DNS resolution failure for carrier SIP servers
Asterisk resource exhaustion (memory, file descriptors, SIP slots)
Load-balanced trunk pool misconfiguration (all trunks unavailable)
Carrier rate-limit or threshold hit
Bad SIP header or malformed request from ViciDial

Carrier-Side Diagnostics and Fixes

Step 1: Verify Carrier Trunk Configuration in ViciDial

Log into the ViciDial web admin panel and navigate to System Admin → Carriers.

# Query the carrier configuration directly
mysql -u root -p asterisk -e "
SELECT carrier_id, carrier_name, active, outbound_sip_ip, outbound_sip_port, 
       max_channels, carrier_protocol FROM vicidial_carrier_log 
WHERE active='Y' 
ORDER BY carrier_id;"

Check the following fields:

carrier_name: Ensure the carrier is active and correctly named
outbound_sip_ip: Verify IP matches carrier documentation
outbound_sip_port: Default is 5060; some carriers use 5061 (TLS) or custom ports
max_channels: Should match carrier's license/plan (not 1 or 0)
carrier_protocol: Should be SIP for modern deployments

Step 2: Test Carrier Connectivity

# Perform basic connectivity test to carrier SIP server
# Replace CARRIER_IP and PORT with your carrier's details
timeout 5 nc -zv 203.0.113.50 5060

# For TLS (port 5061)
timeout 5 nc -zv 203.0.113.50 5061

# DNS resolution test
nslookup sip.carrier.example.com
dig sip.carrier.example.com +short

If the connection times out or DNS fails, contact your carrier immediately. If connectivity is good, continue to step 3.

Step 3: Monitor Real-Time SIP Traffic

Use tcpdump to capture SIP traffic to the carrier:

# Capture SIP traffic to specific carrier IP (replace with actual IP)
tcpdump -i any -n 'host 203.0.113.50 and (port 5060 or port 5061)' -A -v | head -100

# Alternatively, use tshark for more detailed SIP analysis
tshark -i any -f 'host 203.0.113.50 and port 5060' -O SIP | head -50

Look for:

INVITE messages sent (should see FROM/TO headers)
SIP/2.0 100 Trying (carrier acknowledges receipt)
SIP/2.0 503 Service Unavailable (where the failure occurs)
SIP/2.0 200 OK (successful calls, for comparison)

A 503 response without "100 Trying" suggests the carrier is rejecting at gateway level, not downstream.

Step 4: Check Carrier Account Status and Limits

Contact your carrier's technical support and request:

Account/trunk status — Is the account active? Any blocks?
Current channel utilization — Are you at max concurrent channels?
Rate limits — CPS (calls per second) or PPS (packets per second) limits
IP allowlist — Is your ViciDial server IP whitelisted?
Maintenance windows — Any scheduled maintenance today?
Recent changes — Any recent carrier-side configuration changes?

Step 5: Review ViciDial Trunk Configuration File

Check the SIP trunk definition:

# View the carrier-specific SIP context
grep -A 50 "carrier_" /etc/asterisk/sip-vicidial.conf | head -100

Look for your carrier's SIP registration block. It should resemble:

[carrier_mycarrier]
type=peer
host=203.0.113.50
port=5060
username=youraccountid
secret=yoursecretkey
fromdomain=sip.carrier.example.com
fromuser=youraccountid
context=from-carrier
canreinvite=no
dtmfmode=rfc2833
disallow=all
allow=ulaw
allow=alaw
qualifyfreq=60
insecure=port,invite
nat=yes
register=>youraccountid:yoursecretkey@203.0.113.50:5060/youraccountid

Critical checks:

username/secret: Match carrier account credentials
host/port: Match carrier's primary SIP server (not a secondary or failover)
register line: Must be present and correct; it registers your trunk with the carrier
allow codecs: Must match carrier's supported codecs (ulaw is safest)
nat=yes: Enable if your ViciDial server is behind NAT
insecure=port,invite: May be required by some carriers for IP-based auth

Step 6: Force Trunk Re-registration

After correcting configuration, force Asterisk to re-register with the carrier:

# Reload SIP configuration
asterisk -rx "sip reload"

# Unregister and re-register
asterisk -rx "sip unregister carrier_mycarrier"
sleep 2
asterisk -rx "sip register carrier_mycarrier"

# Verify registration status
asterisk -rx "sip show registry"

Expected output from sip show registry:

Host                            dnsmgr Username       State       Reg.Expires ID
203.0.113.50:5060               N      youraccountid  Registered  60

If the state is "Unregistered" or "Rejected," review the carrier credentials and contact support.

Step 7: Check Carrier-Specific Rate Limits

Some carriers enforce strict CPS (calls per second) or concurrent channel limits. Query your recent call volume:

# Check concurrent calls in the last hour
mysql -u root -p asterisk -e "
SELECT DATE_FORMAT(call_date, '%Y-%m-%d %H:00:00') as hour,
       COUNT(*) as total_calls,
       SUM(IF(call_duration > 0, 1, 0)) as connected_calls,
       SUM(IF(call_duration = 0, 1, 0)) as failed_calls
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
AND carrier_id = 'CARRIER_ID_HERE'
GROUP BY hour
ORDER BY hour DESC;"

If you see a spike corresponding to 503 errors, you may have exceeded the carrier's threshold. Request higher limits or implement call-rate throttling.

Server-Side Diagnostics and Fixes

Step 1: Check Asterisk Channel Availability

# View current SIP channel status
asterisk -rx "sip show channels"

# Count active channels
asterisk -rx "sip show channels" | grep -c "sip:"

# View max channels setting
asterisk -rx "sip show settings" | grep -i "maxcallbitrate\|max"

Check if channels are approaching the configured maximum:

# Query Asterisk config for max channels
grep -i "^maxchannels" /etc/asterisk/asterisk.conf

# Default is usually unlimited or 1000; for ViciDial, set explicitly
cat /etc/asterisk/asterisk.conf | grep -A 5 "\[options\]"

Step 2: Monitor System Resources

A 503 often indicates resource exhaustion. Check:

# Memory usage
free -h

# CPU load
uptime

# Disk I/O
iostat -x 1 5

# File descriptors in use
lsof -p $(pgrep -f "asterisk -p") | wc -l

# Network connections by state
netstat -an | grep SIP | wc -l
netstat -an | grep ESTABLISHED | wc -l

Critical thresholds:

Memory: If free memory < 500 MB, Asterisk may fail to allocate SIP slots
CPU: Load > 80% of cores indicates saturation
File descriptors: If approaching the system limit (usually 1024 or more), increase with ulimit -n
Network: If SIP connections > 5000, you may hit kernel limits

Step 3: Increase File Descriptor Limits

Edit the Asterisk systemd service or init script:

# For systemd-based systems (modern ViciDial)
cat > /etc/systemd/system/asterisk.service.d/limits.conf << 'EOF'
[Service]
LimitNOFILE=65536
LimitNPROC=65536
EOF

systemctl daemon-reload
systemctl restart asterisk

# Verify
cat /proc/$(pgrep -f "asterisk -p")/limits | grep files

For older init.d systems:

# Edit /etc/init.d/asterisk
# Add before asterisk startup:
ulimit -n 65536
ulimit -u 65536

Step 4: Review Asterisk SIP Channel Limits

Check the main SIP configuration:

# View SIP channel configuration
grep -E "^maxexpire|^minexpire|^defaultexpire|^srvlookup" /etc/asterisk/sip.conf

Add or adjust these settings in /etc/asterisk/sip.conf:

[general]
; Increase SIP slot capacity
maxchannels = 2000

; Enable DNS SRV lookups for carrier failover
srvlookup = yes

; Optimize timers
minexpire = 60
defaultexpire = 3600
maxexpire = 3600

; Enable call completion on busy subscriber (CCBS) to reduce rejections
; This requires carrier support
ccbsmode = core

; Increase UDP buffer size
udpbuffersize = 262144

; Session timers to detect dead calls
session_expires = 1800
session_minse = 90
sessiontimeout = 0

After changes, reload:

asterisk -rx "sip reload"

Step 5: Optimize Codec Selection

Codec negotiation failures can trigger 503s. Enforce a single, widely-supported codec:

# Current codec configuration for a trunk
grep -A 10 "carrier_mycarrier\]" /etc/asterisk/sip-vicidial.conf | grep -E "allow|disallow"

Update to use only G.711 µ-law (most universal):

[carrier_mycarrier]
disallow=all
allow=ulaw

Reload:

asterisk -rx "sip reload"

Step 6: Monitor Asterisk Logs for Errors

Real-time log monitoring:

# Tail Asterisk messages log
tail -f /var/log/asterisk/messages | grep -i "503\|service\|unavailable"

# Search for recent errors
grep -i "service.*unavailable\|503" /var/log/asterisk/messages | tail -20

# Full SIP debug output (verbose, use sparingly)
asterisk -rx "sip set debug on"
# ... make a test call ...
asterisk -rx "sip set debug off"

# Check debug output
grep -i "sip.*debug\|<--" /var/log/asterisk/messages | tail -50

Step 7: Enable and Check Asterisk Queue Logs

ViciDial relies on queue logs to track call outcomes. Verify they're being written:

# Check queue logging
grep -i "^queue_log" /etc/asterisk/logger.conf

# Ensure this line exists:
# queue_log => queue_log

# Restart logger if needed
asterisk -rx "logger reload"

# Verify queue_log file exists and is being written
ls -lh /var/log/asterisk/queue_log
tail -20 /var/log/asterisk/queue_log | grep -i "COMPLETE\|503"

Step 8: Check ViciDial Dial Plan Logic

Review the outbound dial plan for the carrier. In ViciDial, this is controlled by extensions-vicidial.conf:

# Search for outbound call routing
grep -A 30 "^exten => _[0-9]" /etc/asterisk/extensions-vicidial.conf | grep -A 30 "Dial\|SIP"

Look for a pattern like:

exten => _1NXXNXXXXXX,1,Set(OUTBOUND_GROUP=${CHANNEL(group)})
exten => _1NXXNXXXXXX,2,Set(GROUP_COUNT_LIMIT=10)
exten => _1NXXNXXXXXX,3,CheckGroup()
exten => _1NXXNXXXXXX,4,Dial(SIP/${EXTEN}@carrier_mycarrier,45,TM(custom_hangup))
exten => _1NXXNXXXXXX,5,Hangup()

If CheckGroup() is blocking calls due to GROUP_COUNT_LIMIT, increase the limit:

exten => _1NXXNXXXXXX,2,Set(GROUP_COUNT_LIMIT=100)

Reload dialplan:

asterisk -rx "dialplan reload"

Step 9: Monitor ViciDial Call Log for Patterns

Use the ViciDial database to identify 503 error rates:

-- Find all calls with 503 or similar SIP errors in the last hour
SELECT call_date, phone_number, length(call_duration) as duration_sec, 
       SIP_RESPONSE, carrier_id, user_id
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
AND SIP_RESPONSE IN ('503', '500', '502')
ORDER BY call_date DESC
LIMIT 20;

If SIP_RESPONSE is NULL, check the call_result field:

-- Alternative: filter by call_result
SELECT call_date, phone_number, call_result, carrier_id, 
       COUNT(*) as count
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
GROUP BY call_result
ORDER BY count DESC;

If you see a spike in "FAILED" or "SERVICE_UNAVAILABLE" call results, correlate with the time of the 503 errors.

Step 10: Implement Call Rate Throttling

If you're generating calls too quickly for the carrier or your own system, implement rate limiting in the ViciDial dial plan:

; In extensions-vicidial.conf, add before the Dial() command
exten => _1NXXNXXXXXX,2,Set(GROUP_COUNT_LIMIT=20)
exten => _1NXXNXXXXXX,3,Set(OUTBOUND_GROUP=${CHANNEL(group)})
exten => _1NXXNXXXXXX,4,CheckGroup()
exten => _1NXXNXXXXXX,5,Wait(0.5)
exten => _1NXXNXXXXXX,6,Dial(SIP/${EXTEN}@carrier_mycarrier,45,TM())

Adjust the Wait() duration to throttle call initiation (0.5 = 500ms delay per call).

Alternatively, set a CPS limit in ViciDial's carrier config:

# In ViciDial web admin, set the carrier's "CPS Limit" field to a conservative value
# (e.g., 10 calls/second) and reload the carrier

Advanced Troubleshooting

Scenario 1: 503 Only on Specific Destinations

If 503 errors occur only for certain phone numbers or prefixes:

# Query logs filtered by destination prefix
mysql -u root -p asterisk -e "
SELECT phone_number, COUNT(*) as attempts, 
       SUM(IF(SIP_RESPONSE = '503', 1, 0)) as sip_503_count
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
GROUP BY SUBSTR(phone_number, 1, 3)
ORDER BY sip_503_count DESC;"

This may indicate a route-specific issue on the carrier. Contact support for that specific destination or region.

Scenario 2: 503 During Peak Hours

If 503s only occur during peak call volumes (e.g., 9 AM - 5 PM):

# Identify peak hour patterns
mysql -u root -p asterisk -e "
SELECT DATE_FORMAT(call_date, '%Y-%m-%d %H:00:00') as hour_block,
       COUNT(*) as total_calls,
       SUM(IF(SIP_RESPONSE = '503', 1, 0)) as sip_503_count,
       ROUND(100 * SUM(IF(SIP_RESPONSE = '503', 1, 0)) / COUNT(*), 2) as fail_rate_pct
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY hour_block
ORDER BY fail_rate_pct DESC;"

Solutions:

Request carrier to increase allocated channels
Implement call queuing: instead of rejecting with 503, queue calls and retry when capacity available
Load-balance across multiple carrier trunks

Scenario 3: 503 + High Latency

If network latency to the carrier is high (> 200ms), SIP timeouts may trigger 503s:

# Measure latency to carrier SIP server
ping -c 10 203.0.113.50

# For UDP latency (more accurate for SIP)
mtr -c 10 203.0.113.50

If latency > 200ms:

Contact your ISP or network provider
Request a dedicated link to the carrier
Implement connection pooling in Asterisk to reduce RTT

Increase SIP timeout in asterisk.conf:

[options]
; Increase SIP transaction timeout from default (6 seconds) to 10 seconds
maxcallbitrate = 384

Unfortunately, Asterisk's SIP timeout is not easily configurable per-trunk; you may need to upgrade to PJSIP channel driver (Asterisk 13+) for finer control.

Scenario 4: 503 + High Memory Usage

If system memory is near capacity:

# Check memory by process
ps aux --sort=-%mem | head -10

# Monitor Asterisk memory specifically
watch -n 1 'ps aux | grep -i asterisk | grep -v grep'

Solutions:

Restart Asterisk during a maintenance window
Increase server RAM
Reduce call queue size or max concurrent calls

Restart Asterisk cleanly:

asterisk -rx "core stop gracefully"
# Wait for all calls to complete (check status)
sleep 30
/etc/init.d/asterisk start

# Verify restart
asterisk -rx "core show version"

Troubleshooting

Issue: "Registration failed" for carrier trunk

Cause: Incorrect SIP credentials or carrier doesn't recognize the IP.

Fix:

# Verify credentials in sip-vicidial.conf
grep -A 5 "username=\|secret=" /etc/asterisk/sip-vicidial.conf

# Confirm with carrier documentation
# Reload SIP and check registration
asterisk -rx "sip reload"
asterisk -rx "sip show registry"

# Check detailed registration attempt
asterisk -rx "sip set debug on"
# Reload SIP
asterisk -rx "sip reload"
# Wait 10 seconds
sleep 10
asterisk -rx "sip set debug off"
# Review logs
grep -i "register\|auth" /var/log/asterisk/messages | tail -30

Issue: Calls fail immediately with 503, no "100 Trying" response

Cause: Carrier is rejecting at gateway level (possibly due to IP allowlist or account block).

Fix:

Verify your server's public IP:

   dig @8.8.8.8 myserver.example.com +short
   # or
   curl -s https://ifconfig.me

Contact carrier and request they whitelist your IP
Check if carrier requires specific SIP headers or authentication method:

   # Enable detailed SIP logging
   asterisk -rx "sip set debug on"
   # Attempt a call
   # Check logs for authentication challenges
   grep -i "401\|407" /var/log/asterisk/messages

Issue: Random 503s, no correlation with load or time

Cause: Intermittent carrier connectivity or DNS resolution failures.

Fix:

# Test carrier DNS continuously
watch -n 1 'dig sip.carrier.example.com +short'

# Verify DNS resolution doesn't change
for i in {1..20}; do dig sip.carrier.example.com +short; sleep 1; done

# If DNS is inconsistent, set static IP in sip.conf
# Instead of: host=sip.carrier.example.com
# Use: host=203.0.113.50 (static IP)

# Reload SIP
asterisk -rx "sip reload"

If carrier's DNS is unreliable, request their static SIP server IP.

Issue: 503 after Asterisk restart

Cause: SIP registration hasn't completed yet.

Fix:

# Monitor registration status during startup
watch -n 2 'asterisk -rx "sip show registry"'

# Wait for all trunks to show "Registered" status
# This typically takes 10-30 seconds

# If any trunk remains "Unregistered" after 1 minute, check:
asterisk -rx "sip show peers" | grep carrier_mycarrier

# Force re-registration
asterisk -rx "sip unregister carrier_mycarrier"
sleep 3
asterisk -rx "sip register carrier_mycarrier"

Issue: 503 for international calls only

Cause: Carrier may not have routing to that destination, or special handling required.

Fix:

# Query international call attempts
mysql -u root -p asterisk -e "
SELECT phone_number, COUNT(*) as attempts,
       SUM(IF(SIP_RESPONSE = '503', 1, 0)) as sip_503_count
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 1 DAY)
AND phone_number LIKE '00%' OR phone_number LIKE '+%'
GROUP BY SUBSTR(phone_number, 1, 3)
ORDER BY sip_503_count DESC;"

# Contact carrier and verify:
# 1. International routing is enabled on account
# 2. Destination country is in approved list
# 3. Specific prefix handling (e.g., +1 vs 1)

Issue: Carrier returns 503 with "Temporarily Unavailable" message

Cause: Carrier is overloaded or performing maintenance.

Fix:

# Check carrier status page or contact support
# In the meantime, implement automatic failover:

# In extensions-vicidial.conf, add a secondary carrier
exten => _1NXXNXXXXXX,4,Dial(SIP/${EXTEN}@carrier_mycarrier,30,TM())
exten => _1NXXNXXXXXX,5,Dial(SIP/${EXTEN}@carrier_backup,30,TM())
exten => _1NXXNXXXXXX,6,Hangup()

# Reload dialplan
asterisk -rx "dialplan reload"

# Verify both carriers are registered
asterisk -rx "sip show registry"

Summary

Resolving SIP 503 Service Unavailable errors requires systematic diagnosis of both carrier-side and server-side factors:

Carrier-side fixes:

Verify trunk configuration (IP, port, credentials)
Test connectivity to carrier SIP server
Monitor SIP traffic for 503 responses
Contact carrier for account status, channel limits, and rate limits
Force trunk re-registration
Check for geographic or destination-specific routing issues

Server-side fixes:

Monitor Asterisk channel availability and resource usage
Increase file descriptor limits and SIP maxchannels
Optimize codec selection for carrier compatibility
Review and fix dial plan logic (CheckGroup limits)
Enable call rate throttling to prevent overload
Monitor ViciDial logs for error patterns
Implement call queuing and failover to secondary carriers
Address network latency and DNS issues

Prevention:

Set up continuous monitoring of SIP registration status and channel utilization
Implement alerting when carrier registration fails or channel usage exceeds 80%
Schedule regular carrier connectivity tests
Maintain redundant carrier connections
Document carrier SIP configurations with clear comments
Keep Asterisk and ViciDial updated to latest stable versions

Most 503 errors resolve quickly once you identify whether the issue is carrier-side (contact support) or server-side (resource scaling or configuration). Use the diagnostic commands in this tutorial to pinpoint the root cause and apply targeted fixes.