DEV Community: Moisi Trungu

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.

SIP 403 Forbidden Error — Trunk Authentication Troubleshooting

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

SIP 403 Forbidden Error — Trunk Authentication Troubleshooting

Master the complete diagnostic and resolution process for SIP 403 Forbidden errors affecting your ViciDial trunks and Asterisk SIP authentication

Overview

A SIP 403 Forbidden error indicates that your Asterisk server attempted to authenticate with a remote SIP trunk provider, but the credentials or authorization rules were rejected. In ViciDial production environments, this manifests as failed outbound calls, dropped inbound routes, and frustrated agents seeing "trunk unavailable" errors.

This tutorial covers the exact troubleshooting methodology used in production ViciDial deployments running hundreds of concurrent calls. You'll learn to diagnose root causes, modify configurations, validate changes, and implement monitoring to prevent future occurrences.

Prerequisites

Active ViciDial installation (16.x or later)
Root or sudo access to your Asterisk server
Familiarity with Linux command line and basic Asterisk concepts
Access to /etc/asterisk/ configuration directory
ViciDial MySQL database credentials
SIP trunk provider account details and authentication parameters
Working Asterisk CLI access via asterisk -rx commands

Understanding SIP 403 Forbidden in Context

What Causes 403 Forbidden Errors

A 403 Forbidden response in SIP means the upstream server understood your request but refused to authorize it. Unlike 401 (Unauthorized, requiring credentials) or 407 (Proxy Authentication Required), a 403 indicates:

Invalid or expired credentials
Username/password mismatch
IP authentication failure
Rate limiting or blacklisting
Missing or incorrect authentication headers
Codec mismatch (rarely, but possible)
Subscriber not authorized for that endpoint
Account suspension or payment issues

Where ViciDial Processes Trunk Authentication

ViciDial manages trunks through:

SIP Configuration Files: /etc/asterisk/sip-vicidial.conf contains peer definitions
Database: vicidial_carrier_log and trunk definitions in Asterisk dialplan
Extensions Dialplan: /etc/asterisk/extensions-vicidial.conf routes calls through specific trunks
Asterisk Core: Processes authentication before sending requests upstream

ViciDial Trunk Configuration Structure

Database Trunk Definition

First, verify your trunk exists in the database:

SELECT * FROM vicidial_list WHERE list_id = 'YOUR_TRUNK_ID'\G

For carrier-level configuration, check:

SELECT carrier_id, carrier_name, auth_type, carrier_user, carrier_pass, ip_address FROM vicidial_carrier_log ORDER BY date_added DESC LIMIT 10;

SIP Peer Configuration

Locate your trunk definition in /etc/asterisk/sip-vicidial.conf:

[mytrunksip]
type=peer
host=sip.provider.com
port=5060
username=youraccountname
secret=yourpassword
fromuser=youraccountname
fromdomain=sip.provider.com
context=from-trunk
insecure=port,invite
qualify=yes
qualifyfreq=60
canreinvite=no
dtmfmode=rfc2833
nat=force_rport,comedia
directmedia=no

Key fields related to 403 errors:

username: The authentication username (must match provider account)
secret: The password (must match provider configuration exactly)
fromuser: The From: header username in outbound requests
fromdomain: The domain used in From: header
host: The upstream provider's SIP server address
insecure: Whether to accept requests without authentication verification

Step 1: Locate and Review SIP Trunk Logs

Enable SIP Debug Logging

First, enable full SIP debugging to capture the actual 403 response:

asterisk -rx "sip set debug on"

Generate a test call and watch the console output in real-time:

tail -f /var/log/asterisk/messages | grep -i "sip\|forbidden\|auth"

Capture Full SIP Trace

For detailed analysis, use tcpdump to capture the raw SIP messages:

sudo tcpdump -i any -s 0 -w /tmp/sip_trace.pcap \
  'host sip.provider.com and port 5060'

Run a test call, then stop the capture (Ctrl+C).

Convert to readable format:

sudo tshark -r /tmp/sip_trace.pcap -Y sip -O sip > /tmp/sip_trace.txt

Review the trace for the exact 403 response:

grep -A 5 -B 5 "403\|Forbidden" /tmp/sip_trace.txt

Asterisk Verbose Logging

Enable Asterisk verbose mode to log SIP transactions:

asterisk -rx "core set verbose 10"

This produces output in /var/log/asterisk/messages. Monitor during test calls:

tail -100 /var/log/asterisk/messages | grep -E "INVITE|SIP/2.0 403|Trying|Calling"

Step 2: Validate Credentials Against Provider

Verify Provider-Supplied Values

Contact your SIP trunk provider and confirm:

Account Username: Case-sensitive, no spaces
Password/Secret: Exactly as configured in their system
Outbound Proxy/Host: SIP server address and port
Your IP Address(es): Whitelisted on their system
DID/Extension: Authorized for your account
Authentication Method: Digest, Basic, or IP-based

Example request to provider:

"We're receiving 403 Forbidden errors from sip.provider.com when authenticating with username 'accountname'. Can you confirm: (1) the exact password configured for this account, (2) whether IP whitelisting is enabled, (3) what our outbound IP should be, (4) the correct SIP URI format for requests?"

Test With SIPp (SIP Protocol Tester)

Use the sipp tool to test authentication independently:

sudo apt-get install sipp

Create a test scenario file /tmp/test_sip.xml:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<scenario name="Basic SIP UAC">
  <send retrans="500">
    <![CDATA[
      INVITE sip:test@sip.provider.com SIP/2.0
      Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
      From: <sip:youraccountname@yourdomain.com>;tag=[call_number]
      To: <sip:test@sip.provider.com>
      Call-ID: [call_id]
      CSeq: 1 INVITE
      Contact: <sip:[local_ip]:[local_port]>
      Max-Forwards: 70
      User-Agent: Test SIPp
      Content-Length: 0
    ]]>
  </send>
  <recv response="403" />
</scenario>

Run the test:

sipp -sf /tmp/test_sip.xml -s sip.provider.com -p 5060 -ap youraccountname:yourpassword your_local_ip

This tests basic SIP authentication without Asterisk complexity.

Step 3: Check Credential Configuration in ViciDial

Review SIP Configuration File

Open your trunk definition:

grep -A 20 "\[mytrunksip\]" /etc/asterisk/sip-vicidial.conf

Look for:

username=youraccountname
secret=yourpassword

Common mistakes:

Extra spaces around = sign
Trailing whitespace on password line
Password contains special characters not properly escaped
Wrong username or password copied from wrong provider account

Verify From: Header Construction

The From: header must match provider expectations:

fromuser=youraccountname
fromdomain=sip.provider.com

This constructs: From: "youraccountname" <sip:youraccountname@sip.provider.com>

Provider may require:

Your assigned DID as fromuser
Your domain instead of fromdomain
A specific format like +1234567890@yourdomain.com

Check Extensions Dialplan

Verify your trunk is invoked correctly in /etc/asterisk/extensions-vicidial.conf:

exten => _9XXXXXXXX,1,Dial(SIP/${EXTEN:1}@mytrunksip)
exten => _9XXXXXXXX,n,Hangup()

The @mytrunksip reference must match your peer definition exactly (case-sensitive).

Step 4: Diagnose IP and Network Issues

Verify Outbound IP Address

Your Asterisk server's outbound IP must match what the provider has whitelisted:

curl -s https://api.ipify.org

Or from within Asterisk:

asterisk -rx "sip show settings" | grep "Bindaddr"

Compare this IP against your provider's whitelist.

Test Network Connectivity

Verify basic connectivity to the SIP server:

ping -c 3 sip.provider.com

Test port-level connectivity:

nc -zv sip.provider.com 5060

Check if firewall rules permit SIP traffic:

sudo iptables -L -n | grep 5060

For proper SIP NAT traversal, ensure:

[mytrunksip]
nat=force_rport,comedia
directmedia=no

Verify DNS Resolution

Confirm the provider's hostname resolves correctly:

nslookup sip.provider.com
dig sip.provider.com @8.8.8.8

DNS issues can cause timeouts that look like authentication failures.

Step 5: Resolve Common 403 Scenarios

Scenario A: Credential Mismatch

Symptom: 403 response immediately upon sending INVITE.

Resolution:

Request fresh credentials from provider
Update both username and secret fields:

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

If password contains special characters, escape properly:

secret="pa$$w0rd@2024!"

Reload SIP configuration:

asterisk -rx "sip reload"

Test a call and monitor logs:

asterisk -rx "sip set debug on"
# Make test call
asterisk -rx "sip set debug off"

Scenario B: IP Whitelisting

Symptom: 403 error after successful authentication attempts, only from specific network.

Resolution:

Confirm your public IP:

wget -qO- https://checkip.amazonaws.com

Contact provider to whitelist this IP
If using failover/redundancy, whitelist all potential outbound IPs
Test after provider confirms whitelist update:

asterisk -rx "sip qualify mytrunksip"

Scenario C: Rate Limiting/Blacklisting

Symptom: 403 after initial successful calls, becomes persistent.

Resolution:

Contact provider to check if your IP is temporarily blocked
Check for malformed SIP requests in your logs:

grep "malformed\|invalid\|error" /var/log/asterisk/messages | tail -20

Ensure no SIP scanning attacks from your server:

netstat -tupan | grep 5060

If provider has rate limits, implement call queuing in ViciDial dialplan to space out requests

Scenario D: Account Suspension/Expiration

Symptom: Abrupt 403 errors with no configuration changes.

Resolution:

Log into provider's web portal
Check account status, payment status, and service activation
Verify DID/trunk subscription is current
Request manual account re-activation
Once confirmed active, reload SIP:

asterisk -rx "sip reload"

Scenario E: Inbound Route Mismatch

Symptom: 403 only occurs on inbound calls; outbound works fine.

Resolution:

Inbound calls use different SIP URI matching. Check your inbound context in /etc/asterisk/extensions-vicidial.conf:

[from-trunk]
exten => 5551234567,1,Verbose("Inbound from ${CALLERID(num)}")
exten => 5551234567,n,Dial(Local/5551234567@default)
exten => 5551234567,n,Hangup()

Ensure:

The inbound DID is exactly what the provider sends (with or without +1 prefix)
The extension is properly defined in the context
No invalid characters in the DID

Step 6: Test the Fix

Manual SIP Test Call

Use Asterisk's dial command directly:

asterisk -rx "channel originate SIP/5551234567@mytrunksip Application VoiceMAil"

Monitor the response in real-time:

tail -f /var/log/asterisk/messages | grep -E "INVITE|403|200 OK|Call"

A successful INVITE shows 200 OK response.

Agent Test Call from ViciDial

Log into the ViciDial agent screen at /agc/vicidial.php:

Log in with test agent account
Select a campaign with your fixed trunk
Dial a test number (external cell phone or test service)
Monitor the call completion

Check call logs in the database:

SELECT call_id, caller_id_number, dialed_number, call_status, 
       length_in_sec, call_date FROM vicidial_log 
WHERE dialed_number = '5551234567' 
ORDER BY call_date DESC LIMIT 5;

Look for call_status = 'COMPLETE' or similar success indicators.

Verify SIP Qualify Status

Check if the trunk qualifies (can reach the provider):

asterisk -rx "sip show peers" | grep mytrunksip

Output should show:

mytrunksip/sip.provider.com    sip.provider.com:5060         OK

If showing UNREACHABLE, the trunk cannot reach the provider at all. This may indicate network issues or wrong host address.

Advanced Troubleshooting

Parse Raw SIP Headers

If you have a tcpdump capture, extract the exact failing INVITE:

sudo tshark -r /tmp/sip_trace.pcap -Y "sip.Request.Method == INVITE" \
  -T fields -e sip.From -e sip.To -e sip.Contact -e sip.User-Agent

Compare the From:/To:/Contact: headers against provider requirements.

Check Asterisk SIP Registry

If your trunk uses outbound registration:

asterisk -rx "sip show registry"

Output shows registration status. Registered means the trunk successfully authenticated with the provider for inbound calls.

If Request Sent or Unregistered, the trunk cannot register:

asterisk -rx "sip set debug on"
asterisk -rx "sip register mytrunksip"

Review Authentication Digest Headers

In tcpdump analysis, look for the response to your INVITE. If it's a 407 (Proxy Authentication Required) followed by your 403 response, your credentials are wrong.

The sequence should be:

INVITE (no auth) → 407 Proxy Auth Required
ACK
INVITE (with Authorization header) → 200 OK or 180 Ringing

If the second INVITE still returns 403, credentials are incorrect.

Extract the Authorization header from tcpdump:

tshark -r /tmp/sip_trace.pcap -Y "sip" -T fields -e sip.Authorization

Compare the username in the Authorization header against your configured username.

Preventive Measures and Monitoring

Monitor for 403 Errors Proactively

Create a monitoring script in /usr/local/bin/check_sip_403.sh:

#!/bin/bash

LOG_FILE="/var/log/asterisk/messages"
THRESHOLD=5

# Count 403 errors in last hour
COUNT=$(grep "SIP/2.0 403" $LOG_FILE | \
  awk -v d="$(date -d '1 hour ago' '+%b %d %H')" \
  '$0 ~ d' | wc -l)

if [ $COUNT -gt $THRESHOLD ]; then
  echo "ALERT: $COUNT SIP 403 errors detected in last hour"
  # Send email, page, etc.
  # mail -s "ViciDial SIP 403 Alert" admin@example.com
  exit 1
fi

exit 0

Make executable and add to crontab:

sudo chmod +x /usr/local/bin/check_sip_403.sh

*/5 * * * * /usr/local/bin/check_sip_403.sh

Document Trunk Configuration

Maintain a reference document with:

Trunk Name: mytrunksip
Provider: Provider Name
Host: sip.provider.com:5060
Username: accountname (NOT case-sensitive at provider)
Password: (hash, not plaintext) - updated DATE
From Domain: sip.provider.com
Outbound IPs: 203.0.113.45
Inbound DIDs: 555-123-4567, 555-123-4568
Support Contact: +1-555-0000
Rate Limits: 100 CPS
Last Verified: DATE
Known Issues: None

Implement Health Checks

Add to your monitoring system (Nagios, Zabbix, etc.):

check_sip_qualify() {
  local trunk=$1
  asterisk -rx "sip show peers" | grep -q "$trunk.*OK"
}

check_sip_qualify mytrunksip && echo "OK" || echo "CRITICAL"

Log Rotation Configuration

Ensure Asterisk logs don't fill disk, which can mask 403 errors. Check /etc/logrotate.d/asterisk:

/var/log/asterisk/messages {
    daily
    missingok
    rotate 7
    compress
    delaycompress
    notifempty
    create 0640 asterisk asterisk
    postrotate
        /usr/sbin/asterisk -rx "logger rotate" > /dev/null 2>&1 || true
    endscript
}

Troubleshooting Decision Tree

Is the trunk showing in "sip show peers"?
├─ NO → Check sip-vicidial.conf syntax and reload
├─ YES → Does "sip show registry" show it registered?
    ├─ NO (401 or 407) → Credentials are wrong
    ├─ YES → Are you seeing 403 on INVITE only?
        ├─ YES → IP whitelist or rate limit issue
        └─ NO → Check From: header format

Common ViciDial-Specific Issues

Issue: Multiple Trunks, One Returns 403

ViciDial may route calls through the wrong trunk. Check extensions-vicidial.conf:

exten => _9XXXXXXXX,1,Dial(SIP/${EXTEN:1}@mytrunksip)

If this extension pattern is ambiguous, other patterns might match first. Use more specific patterns:

exten => _91NXXXXXX,1,Dial(SIP/${EXTEN:1}@mytrunksip)
exten => _9011.,1,Dial(SIP/${EXTEN:1}@intl_trunk)

Issue: Campaign Trunk Assignment

In ViciDial, verify campaign uses the correct trunk in database:

SELECT campaign_id, campaign_name, vtiger_id FROM vicidial_campaigns 
WHERE campaign_id = 'TESTCAMP';

SELECT trunk_id, carrier_id FROM vicidial_campaign_carriers 
WHERE campaign_id = 'TESTCAMP';

Wrong trunk assignment will route calls through a trunk with bad credentials.

Issue: Lead Filtering by Trunk

Check if leads are filtered to specific trunks in vicidial_list:

SELECT list_id, carrier_id, count(*) FROM vicidial_list 
WHERE carrier_id IS NOT NULL 
GROUP BY list_id, carrier_id;

If a list requires a specific trunk with 403 errors, leads cannot be called.

Summary

SIP 403 Forbidden errors in ViciDial require systematic diagnosis:

Enable debugging to see the actual error in context
Validate credentials match provider configuration exactly
Verify networking allows packets to reach the provider
Check IP whitelisting with your provider
Test independently using sipp before restarting Asterisk
Monitor proactively with log analysis and SIP qualify checks
Document everything for future troubleshooting

The most common causes are wrong credentials, IP whitelisting issues, and provider account problems. Always contact your SIP provider with specific details:

"SIP 403 Forbidden error from [your outbound IP] to [their SIP host] with username [username] at [specific time]. Can you check authentication logs?"

Keep Asterisk SIP logging enabled in production (sip set debug on in verbosity levels), rotate logs regularly, and set up alerts for repeated 403 errors. This prevents lost calls and identifies problems before they impact your operation.

Asterisk 'Peer Is Not Registered' — SIP Registration Failure Debug

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

Asterisk 'Peer Is Not Registered' — SIP Registration Failure Debug

Master the diagnosis and resolution of SIP registration failures in Asterisk/ViciDial production environments by understanding peer registration mechanics, common misconfiguration patterns, and step-by-step troubleshooting methodology.

Prerequisites

Before you begin this guide, ensure you have:

Asterisk 1.6+, 11.x, 13.x, or 16.x (ViciDial typically runs 11.x or 13.x)
Root or sudo access to the Asterisk server
Knowledge of basic SIP concepts (registrar, registrant, peer, friend)
Access to /etc/asterisk/ configuration directory
Ability to tail logs in real-time: tail -f /var/log/asterisk/messages
Familiarity with asterisk -rx CLI commands
Understanding of your network topology (NAT, firewall, carrier routing)

Understanding SIP Registration in Asterisk

How Asterisk Registration Works

When Asterisk is configured as a SIP registrant (client), it sends a SIP REGISTER request to a remote SIP server (registrar). The registrar acknowledges and stores the binding. Asterisk then periodically re-registers to maintain the binding.

When an external peer attempts to register to Asterisk (Asterisk acting as registrar), Asterisk receives the REGISTER request, validates credentials, and stores the peer location in memory.

The error "Peer is not registered" occurs when:

Asterisk expects a peer to have registered but hasn't
The peer's registration has expired
The peer never completed registration
The peer is configured incorrectly
Network/firewall blocks SIP traffic
DNS resolution fails

Registration State Lifecycle

Peer Configured (type=friend or type=peer)
    ↓
SIP REGISTER Request Sent (or expected)
    ↓
401 Unauthorized / 200 OK Response
    ↓
Credentials Validated / Failed
    ↓
Binding Stored in Memory / Rejected
    ↓
Re-registration Timer Starts (default: 3600s)
    ↓
Expiration / Renewal Cycle

Configuration Fundamentals

SIP Peer vs. Friend vs. User Types

ViciDial typically uses SIP configuration in /etc/asterisk/sip-vicidial.conf. Understanding peer types is critical:

[general]
context=from-internal
recordhistory=yes
bindport=5060
bindaddr=0.0.0.0
srvlookup=yes
transport=udp,tcp
allowguest=no
qualify=yes
qualifyfreq=60

# TYPE 1: PEER (one-way trust, inbound calls only)
[carrier_sip]
type=peer
host=203.0.113.45
port=5060
context=from-pstn
directmedia=no
disallow=all
allow=ulaw,alaw
fromuser=vicidial_account
fromdomain=203.0.113.45

# TYPE 2: USER (deprecated in modern Asterisk, avoid)
[user_extension]
type=user
host=dynamic
context=from-internal

# TYPE 3: FRIEND (peer + user, two-way trust)
[agent_extension]
type=friend
host=dynamic
context=from-internal
defaultuser=1001
secret=MySecurePassword123
directmedia=no
disallow=all
allow=ulaw,alaw
mailbox=1001@default
qualify=yes
qualifyfreq=120

Step 1: Verify Configuration Syntax

Check SIP Configuration for Errors

Invalid syntax prevents Asterisk from loading the peer entirely.

asterisk -rx "sip show peers" 2>&1 | head -20

Expected output:

Name/username             Host                                    Dyn Forcerport ACL Port     Status      
agent_1001               192.168.1.100                            D   No         A  5060     OK (19 ms)
carrier_sip              203.0.113.45                             N   Yes        A  5060     UNREACHABLE

If a peer is missing from this list entirely, it failed to parse.

Reload and Check for Parse Errors

asterisk -rx "sip reload" 2>&1 | grep -i "error\|warning\|parse"
tail -f /var/log/asterisk/messages | grep -i "sip\|error"

Look for lines like:

[2024-01-15 14:32:18] WARNING[12345]: chan_sip.c:30123 in parse_register_line(): Line 145: Bad syntax
[2024-01-15 14:32:18] ERROR[12345]: config.c:4567 in config_text_file_load(): Can't load config file "sip-vicidial.conf"

Common Configuration Syntax Errors

# WRONG: Missing equals sign
[agent_1001]
type friend
secret=password

# WRONG: Invalid values
[agent_1001]
type=invalid_type
qualify=maybe

# WRONG: Commented out required field
[agent_1001]
type=friend
;secret=password

# CORRECT:
[agent_1001]
type=friend
secret=password
qualify=yes

Step 2: Confirm Peer is Loaded and Present

List All Registered and Unregistered Peers

asterisk -rx "sip show peers"

Parse the output methodically:

Dyn = Y/D: Peer expects dynamic (changing) host IP
Host = actual IP or hostname: Current known location
Port: SIP port (default 5060)
Status:
- OK (X ms) = responsive
- UNREACHABLE = can't reach this peer
- UNKNOWN = hasn't registered yet
- Unmonitored = qualify=no

Check Specific Peer Registration Status

asterisk -rx "sip show peer agent_1001"

Output example (peer IS registered):

  Name       : agent_1001
  Secret     : <Set>
  MD5Secret  : <Not set>
  Context    : from-internal
  Language   : en
  AMA flags  : Unknown
  Transfer mode : open
  Dtmfmode   : rfc2833
  Tohost     : 192.168.1.100
  Addr->IP   : 192.168.1.100
  Defname    : agent_1001
  Useragent  : Zoiper 2.52 (VoIP Client)
  Reg. Contact: sip:agent_1001@192.168.1.100:5060

Output example (peer NOT registered):

  Name       : agent_1002
  Secret     : <Set>
  Context    : from-internal
  Host       : dynamic
  Addr->IP   : (null)
  Defname    : agent_1002
  Useragent  : 
  Reg. Contact: <Not set>
  Status     : UNKNOWN

Key indicator: If Addr->IP : (null) and Reg. Contact: <Not set>, the peer has never registered.

Step 3: Check Network Connectivity and Firewall

Verify UDP/TCP Port 5060 is Open

# Check if Asterisk is listening
netstat -tulpn | grep asterisk | grep 5060

Expected output:

udp        0      0 0.0.0.0:5060            0.0.0.0:*                           12345/asterisk
tcp        0      0 0.0.0.0:5060            0.0.0.0:*                           12345/asterisk

Test Firewall from Client

From the SIP client machine:

nc -u -zv <asterisk-server-ip> 5060
nc -zv <asterisk-server-ip> 5060

If both fail, firewall is blocking. Check iptables (or firewalld):

# Check iptables rules
sudo iptables -L -n | grep 5060

# If nothing, add rule (CentOS/RHEL with firewalld):
sudo firewall-cmd --permanent --add-port=5060/udp
sudo firewall-cmd --permanent --add-port=5060/tcp
sudo firewall-cmd --reload

# Or with iptables directly:
sudo iptables -I INPUT -p udp --dport 5060 -j ACCEPT
sudo iptables -I INPUT -p tcp --dport 5060 -j ACCEPT
sudo service iptables save

Test DNS Resolution

nslookup asterisk.example.com
dig asterisk.example.com

If the client uses a hostname to register and DNS fails, registration fails silently.

Step 4: Enable SIP Debugging and Capture Registration Attempts

Enable Verbose SIP Debugging

asterisk -rx "sip set debug on"
tail -f /var/log/asterisk/messages | grep -i "register\|sip"

Or capture to a separate file:

asterisk -rx "sip set debug on peer agent_1001"

Real-World Debug Output: Successful Registration

<--- SIP read from UDP:192.168.1.100:52341 --->
REGISTER sip:asterisk.local SIP/2.0
Via: SIP/2.0/UDP 192.168.1.100:5060;branch=z9hG4bK776asdhds
From: <sip:agent_1001@asterisk.local>;tag=1928301774
To: <sip:agent_1001@asterisk.local>
Call-ID: a84b4c76e66710@192.168.1.100
CSeq: 314159 REGISTER
Contact: <sip:agent_1001@192.168.1.100:5060>
Expires: 3600

Asterisk responds:

----- Transmitting SIP response to UDP:192.168.1.100:52341 -----
SIP/2.0 200 OK
Via: SIP/2.0/UDP 192.168.1.100:5060;branch=z9hG4bK776asdhds
From: <sip:agent_1001@asterisk.local>;tag=1928301774
To: <sip:agent_1001@asterisk.local>;tag=as52a3c4a9
Call-ID: a84b4c76e66710@192.168.1.100
CSeq: 314159 REGISTER
Contact: <sip:agent_1001@192.168.1.100:5060>;expires=3600

Real-World Debug Output: Failed Registration (No Credentials)

<--- SIP read from UDP:192.168.1.100:52341 --->
REGISTER sip:asterisk.local SIP/2.0
...
Contact: <sip:agent_1002@192.168.1.100:5060>
...

[Asterisk checks credentials against sip-vicidial.conf]

----- Transmitting SIP response to UDP:192.168.1.100:52341 -----
SIP/2.0 401 Unauthorized
...
WWW-Authenticate: Digest realm="asterisk.local", nonce="..."

Client should re-send REGISTER with Authorization header.

Disable Debug When Done

asterisk -rx "sip set debug off"

Step 5: Check ViciDial Database Configuration

ViciDial stores extensions and phone registrations in MySQL. Verify the extension is enabled.

Query ViciDial Extensions

mysql -u vicidial -p asterisk -e "
SELECT extension, voicemail_id, full_name, status
FROM vicidial_extensions
WHERE extension='1001';"

Output:

+-----------+---------------+-----------+--------+
| extension | voicemail_id  | full_name | status |
+-----------+---------------+-----------+--------+
| 1001      | 1001          | John Doe  | ACTIVE |
+-----------+---------------+-----------+--------+

Critical: If status is not ACTIVE, the extension is disabled. Check vicidial_users too:

mysql -u vicidial -p asterisk -e "
SELECT user, full_name, status, phone_login_pin
FROM vicidial_users
WHERE user='1001';"

Verify SIP Registration in Database

Check if the peer appears in the registration tracking table:

mysql -u vicidial -p asterisk -e "
SELECT * FROM vicidial_sip_registration
WHERE extension='1001'\G"

If empty, check the log table for failed attempts:

mysql -u vicidial -p asterisk -e "
SELECT event_date, extension, description
FROM vicidial_log
WHERE extension='1001' AND description LIKE '%register%'
ORDER BY event_date DESC LIMIT 10;"

Step 6: Verify Credentials Match

Common Credential Mismatches

The most frequent cause of registration failure is mismatched credentials.

In sip-vicidial.conf:

[agent_1001]
type=friend
defaultuser=agent_1001
secret=MySecurePassword123

Expected client configuration:

Username: agent_1001
Password: MySecurePassword123
Registrar: asterisk.local or IP
Port: 5060

If client uses:

Username: 1001 (without prefix)
Password: MySecurePassword1234 (typo)
Port: 5061 (wrong port)

→ Registration fails silently or returns 401.

Force Credential Check

Temporarily enable authentication debugging:

asterisk -rx "core set debug 5"
tail -f /var/log/asterisk/messages | grep -i "auth\|credential"
asterisk -rx "core set debug 0"  # Disable when done

Step 7: Check Expiration and Re-Registration Timers

Verify Peer Expiration Settings

asterisk -rx "sip show peer agent_1001" | grep -i "expire\|refresh"

Output:

  Expire        : 3600 (sec)
  Refresh Timer : 1800 (sec)
  Reg. Contact  : sip:agent_1001@192.168.1.100:5060

If a peer registered hours ago but hasn't re-registered, the binding expires and "Peer is Not Registered" errors occur.

Set Shorter Re-registration Intervals in sip-vicidial.conf

[agent_1001]
type=friend
secret=password
defaultuser=agent_1001
context=from-internal
qualify=yes
qualifyfreq=60          ; Keep-alive check every 60 seconds
defaultexpire=3600      ; Registration validity: 1 hour
minexpire=120           ; Minimum allowed expiration
maxexpire=7200          ; Maximum allowed expiration

Reload:

asterisk -rx "sip reload"

Monitor Live Registration Status

watch -n 1 "asterisk -rx 'sip show peer agent_1001' | grep -E 'Status|Reg. Contact'"

You should see the status update periodically. If it goes stale, re-registration is failing.

Step 8: Diagnose NAT and External IP Issues

Problem: Peer Behind NAT with Wrong Contact IP

When a peer is behind NAT, the SIP REGISTER Contact header contains the private IP (e.g., 192.168.1.100). Asterisk stores this. When Asterisk tries to send SIP traffic back, it fails because 192.168.1.100 is unreachable from outside the NAT.

Enable Symmetric RTP and IP Checking

[general]
directmedia=no
nat=force_rport
symmetric_rtp=yes

[agent_1001]
type=friend
secret=password
nat=force_rport
directmedia=no

Use STUN for NAT Traversal

Configure STUN server in sip-vicidial.conf:

[general]
externip=203.0.113.50
localnet=192.168.1.0/255.255.255.0

Or use STUN:

[general]
stunaddr=stun.l.google.com:19302
stunrefreshinterval=3600

Check External IP Detection

asterisk -rx "sip show settings" | grep -i "external\|nat\|stun"

Step 9: Examine SIP Request/Response Logs in Asterisk

Check Full Call Trace with Verbose Logging

asterisk -rx "core set verbose 5"
asterisk -rx "sip set debug on"
tail -f /var/log/asterisk/messages | tail -100
asterisk -rx "core set verbose 0" # Disable when done

Parse Key Messages

Look for these indicators in /var/log/asterisk/messages:

# GOOD: Registration accepted
chan_sip.c: Registration accepted for 'agent_1001' <sip:agent_1001@...>

# BAD: Invalid credentials
chan_sip.c: Failed to authenticate user 'agent_1001'

# BAD: Peer not configured
chan_sip.c: No matching SIP user or peer found for 'agent_1001'

# BAD: Expiration
chan_sip.c: Registration of 'agent_1001' expired

Export Full Debug to File

asterisk -rx "sip set debug on" > /tmp/sip_debug.log 2>&1 &
# Wait for activity, then:
asterisk -rx "sip set debug off"
cat /tmp/sip_debug.log | head -200

Step 10: Test with SIP CLI Commands

Send Manual REGISTER Request

Use sipsak (if installed) to simulate a registration:

sipsak -r sip:agent_1001@asterisk.local -u agent_1001:MySecurePassword123

Or install it:

yum install sipsak  # CentOS/RHEL
apt-get install sipsak  # Debian/Ubuntu

Query Asterisk SIP Registry State

asterisk -rx "sip show registry"

This shows outbound registrations (when Asterisk registers to another server):

Host                           Username       Refresh State                Reg.Time
203.0.113.45:5060             vicidial_acc   105 Registered           Wed Jan 15 14:32:18 2024

If a carrier registration shows Request Sent or Auth. Sent, it's stuck in the handshake.

Troubleshooting Checklist

Issue	Symptoms	Solutions
Peer never appears in `sip show peers`	Completely missing from list	Check syntax with `sip reload`, verify peer name, look for parse errors in logs
Peer shows UNKNOWN	Status is UNKNOWN, no registration	Verify client is sending REGISTER, check firewall port 5060/UDP, check credentials
Peer shows UNREACHABLE	Status is UNREACHABLE	Check `qualify=yes`, verify reachability with ping/nc, check firewall ICMP
"Peer is Not Registered" dial error	Error when calling peer	Check if registration expired, verify re-registration interval, check database status
401 Unauthorized response	Debug shows 401 replies	Verify secret matches in config and client, check defaultuser, verify realm
Contact stored as private IP behind NAT	Calls work internally but not externally	Enable `nat=force_rport`, set `externip=`, use `directmedia=no`
Registration works, but qualifications fail	Status changes to UNKNOWN periodically	Check network connectivity, increase `qualifyfreq`, verify UDP path open
Dynamic peer IP never updates	Peer's host keeps old IP after network change	Check `nat=yes`, restart client, check Asterisk can receive OPTIONS ping

Production Best Practices

Recommended sip-vicidial.conf Configuration for Agents

[general]
context=from-internal
recordhistory=yes
bindport=5060
bindaddr=0.0.0.0
srvlookup=yes
transport=udp,tcp
allowguest=no
qualify=yes
qualifyfreq=60
defaultexpire=3600
minexpire=120
maxexpire=7200
externip=203.0.113.50
localnet=192.168.1.0/255.255.255.0
directmedia=no
nat=force_rport
symmetric_rtp=yes
rtptimeout=300
icesupport=yes

[agent_template](!)
type=friend
context=from-internal
disallow=all
allow=ulaw,alaw,gsm
directmedia=no
nat=force_rport
qualify=yes
qualifyfreq=120
defaultexpire=3600
mailbox=${EXTEN}@default

Then per-extension:

[1001](agent_template)
defaultuser=1001
secret=SecurePassword2024
fullname=John Doe

[1002](agent_template)
defaultuser=1002
secret=SecurePassword2024
fullname=Jane Smith

Monitoring Script

Create /usr/local/bin/monitor_sip_registrations.sh:

#!/bin/bash
ASTERISK_CLI="/usr/bin/asterisk -rx"

echo "=== SIP Registration Status ==="
$ASTERISK_CLI "sip show peers" | grep -E "^[a-z0-9_]+" | while read LINE; do
    PEER=$(echo "$LINE" | awk '{print $1}')
    STATUS=$(echo "$LINE" | awk '{print $NF}')

    if [[ "$STATUS" != "OK" ]] && [[ "$STATUS" != "UNKNOWN" ]]; then
        echo "WARNING: $PEER - $STATUS"
    fi
done

echo ""
echo "=== Expired Registrations (older than 1 hour) ==="
mysql -u vicidial -p asterisk -e "
SELECT extension, registration_date, NOW() FROM vicidial_sip_registration
WHERE TIMESTAMPDIFF(HOUR, registration_date, NOW()) > 1;" 2>/dev/null

echo ""
echo "=== Failed Registration Attempts (Last 10) ==="
tail -100 /var/log/asterisk/messages | grep -i "failed.*register\|unauthorized" | tail -10

Run as a cron job:

0 * * * * /usr/local/bin/monitor_sip_registrations.sh >> /var/log/sip_monitor.log 2>&1

Advanced Troubleshooting: Outbound Registration Issues

If Asterisk is trying to register TO an external carrier and shows "Peer is Not Registered":

Check Outbound Registration Config

register => vicidial_account:VerySecurePassword123@203.0.113.45:5060/from-pstn

Verify Outbound Registration Status

asterisk -rx "sip show registry"

If stuck in Request Sent:

Check carrier endpoint is reachable:

   nc -zv 203.0.113.45 5060

Check firewall allows outbound SIP:

   sudo iptables -L -n | grep 5060

Verify carrier accepts registrations from your IP:

   Contact your carrier to whitelist your public IP

Check authentication with carrier:

   asterisk -rx "sip set debug on"
   asterisk -rx "sip reload"
   tail -f /var/log/asterisk/messages | grep -E "register|auth|carrier_sip"

Test with SIPp if available:

   sipp -sf /tmp/register.xml -s vicidial_account@203.0.113.45 203.0.113.45

Summary

Resolving "Peer Is Not Registered" errors in production Asterisk/ViciDial systems requires systematic diagnosis:

Verify configuration syntax — invalid peers won't load at all
Confirm peer exists — check sip show peers output
Test network connectivity — firewall must allow UDP/TCP 5060
Enable debugging — capture SIP REGISTER requests and responses
Check database state — ViciDial extensions must be ACTIVE
Match credentials — secret, defaultuser, and realm must align
Monitor expiration — registrations expire after the configured interval
Handle NAT — enable nat=force_rport, set externip=, disable directmedia
Review logs — parse /var/log/asterisk/messages for authentication/registration failures
Test systematically — isolate variables (network, config, credentials, firewall)

When a peer shows "Peer is Not Registered" in your ViciDial call logs or Asterisk CLI, follow the 10-step process above. Most issues resolve at steps 2–3 (configuration/firewall) or step 6 (credentials). For edge cases, enable SIP debugging and parse the actual REGISTER request/response sequence.

Keep this guide bookmarked. SIP registration is the foundation of ViciDial's agent connectivity. When it breaks, nothing works.