DEV Community: Moisi Trungu

ViciDial 'Agent Not Available' Error — Routing & Login Troubleshooting

Moisi Trungu — Mon, 27 Jul 2026 03:30:04 +0000

ViciDial 'Agent Not Available' Error — Routing & Login Troubleshooting

Learn how to diagnose and fix the "Agent Not Available" error in ViciDial by understanding call routing logic, agent status codes, database configuration, and Asterisk integration issues.

Prerequisites

Before starting this troubleshooting guide, ensure you have:

A running ViciDial installation (3.14 or later recommended)
SSH access to your ViciDial server
MySQL/MariaDB access to the asterisk database
Basic knowledge of Asterisk CLI commands
Administrator credentials for the ViciDial web interface at /vicidial/admin.php
Familiarity with ViciDial campaign and agent configuration
Access to Asterisk logs at /var/log/asterisk/messages

Understanding the "Agent Not Available" Error

The "Agent Not Available" error in ViciDial occurs when the system attempts to route an inbound call or outbound lead to an agent, but the agent cannot receive the call. This is distinct from an agent simply being offline—it means the agent's status prevents call delivery even though they may be logged in.

Root Causes Overview

The error manifests in five primary scenarios:

Agent status is not in a call-receiving state (paused, not ready, on break)
Agent phone/device is not registered with Asterisk
Campaign routing rules exclude the agent from receiving calls
Database inconsistency between agent status and Asterisk registration
Call center phone system configuration prevents the agent's extension from accepting calls

Section 1: Agent Status and Call States

Understanding ViciDial Agent States

ViciDial agents operate in distinct status codes that determine their availability. The system checks these statuses before routing any call.

SELECT user, status, calls_today, phone_login, phone_number 
FROM vicidial_users 
WHERE user = 'AGENT001';

The critical status field contains values that directly impact call routing:

Status	Call Receivable	Description
READY	Yes	Agent is available for calls
QUEUE	Yes	Agent in call queue, can receive preview calls
DISPO	No	Agent processing after-call work
BREAK	No	Agent on break
LUNCH	No	Agent on lunch
NOT READY	No	Agent logged in but not accepting calls
UNAVAILABLE	No	System-set unavailable status
INCALL	Yes (current call)	Agent on active call

Checking Agent Status via Database

SELECT user, status, lead_id, status_date 
FROM vicidial_users 
WHERE user = 'AGENT001' 
AND DATE(status_date) = CURDATE();

When an agent reports being unable to receive calls, verify their actual database status:

# SSH into ViciDial server
ssh root@vicidial.example.com

# Query agent status directly
mysql -u cron -p'YOURPASSWORD' asterisk -e \
"SELECT user, status, phone_login, last_login_ip FROM vicidial_users WHERE user='AGENT001';"

Common Status Code Mismatches

A frequent issue occurs when the agent's database status doesn't match their perceived status in the agent application. This happens when:

Agent forcibly closes the agent screen without logging out properly
Network interruption breaks the session synchronization
Browser cache shows outdated status
Manual database update (admin modification) isn't reflected in the agent UI

Fix: Force agent logout and login

# Via Asterisk CLI
asterisk -rx "sip show channels" | grep AGENT001

# Or force logout via database (last resort)
mysql -u cron -p'YOURPASSWORD' asterisk -e \
"UPDATE vicidial_users SET status='READY' WHERE user='AGENT001';"

Section 2: Phone Registration and Asterisk Integration

Verifying SIP Registration

The most common cause of "Agent Not Available" errors is the agent's phone or softphone not being registered with Asterisk. ViciDial cannot route calls to an unregistered endpoint.

# Check SIP peer registration
asterisk -rx "sip show peers"

# Look for your agent's extension/phone
# Output should show similar to:
# AGENT001/101        192.168.1.50         D  0-127  OK (56 ms)

If the agent's extension is missing or shows "UNREACHABLE", the phone is not registered.

# Get detailed SIP peer information
asterisk -rx "sip show peer 101"

# Output includes:
# Name       : 101
# Qualified  : Yes
# Status     : OK (56 ms)

Checking Extension Registration in ViciDial

ViciDial maintains its own phone/extension mappings separate from raw Asterisk registration. Verify both layers:

SELECT user, phone_login, phone_number, status 
FROM vicidial_users 
WHERE user = 'AGENT001';

The phone_login field contains the extension number. This must:

Match the actual phone extension the agent is using
Be registered with Asterisk (confirmed via sip show peers)
Not be assigned to multiple agents simultaneously

Diagnosing Registration Failures

Check the Asterisk SIP log for registration errors:

# View recent Asterisk messages
tail -100 /var/log/asterisk/messages | grep -i "sip\|register"

# Look for entries like:
# [Jun 15 14:32:01] REGISTER from sip:101@192.168.1.50 - No matching peer found
# [Jun 15 14:32:02] Failed to authenticate user 101

Fixing SIP Registration Issues

Issue: Extension not registering at all

Verify the SIP configuration in /etc/asterisk/sip-vicidial.conf:

[101]
type=friend
host=dynamic
secret=yourpassword123
context=default
disallow=all
allow=ulaw
allow=gsm
directmedia=no
canreinvite=no
nat=force_rport,comedia
qualify=yes
qualifyfreq=60

Common problems:

Wrong password: The phone must have the exact secret configured
Wrong context: Verify the context matches the dialplan rules
NAT issues: If agent is behind NAT, ensure nat=yes is set
Codec mismatch: Agent phone and server must support common codecs

# Restart Asterisk to reload SIP configuration
asterisk -rx "core reload"

# Force re-registration
asterisk -rx "sip notify resync 101"

Issue: Intermittent registration drops

This often indicates network issues or aggressive NAT timeouts:

# In sip-vicidial.conf, increase keep-alive
[101]
keepalive=20
qualify=yes
qualifyfreq=30

Section 3: Campaign Routing Configuration

Agent Availability in Campaigns

Campaigns control which agents can receive calls. Even if an agent is READY, they won't receive calls if they're not assigned to the campaign.

SELECT * FROM vicidial_campaign_agents 
WHERE campaign_id = 'CAMPAIGN01' 
AND agent_id = 'AGENT001';

If this query returns no results, the agent is not assigned to this campaign.

Add agent to campaign:

INSERT INTO vicidial_campaign_agents 
(campaign_id, agent_id, active, user_group) 
VALUES ('CAMPAIGN01', 'AGENT001', 'Y', '1');

Checking Campaign Call Distribution Rules

ViciDial campaigns have routing priorities that determine call distribution:

SELECT campaign_id, campaign_name, agent_choose, 
       lead_distribution_method, predictive_dialer 
FROM vicidial_campaigns 
WHERE campaign_id = 'CAMPAIGN01';

Key fields affecting agent availability:

agent_choose: Whether agents can choose campaigns (Y/N)
lead_distribution_method: HOW agents are selected (EVEN, LOAD, RING, MOST_RECENT)
predictive_dialer: Campaign mode (manual, preview, power dialer, etc.)

Agent Group Configuration

Some deployments use agent groups for logical grouping and routing:

SELECT * FROM vicidial_agent_group_members 
WHERE agent_id = 'AGENT001';

If agents belong to specific groups, the campaign must be configured to route to those groups:

SELECT * FROM vicidial_campaign_agent_groups 
WHERE campaign_id = 'CAMPAIGN01';

Section 4: Database Consistency and Synchronization

Detecting Database Inconsistencies

Inconsistencies between the agent database table and running Asterisk state cause "Agent Not Available" errors:

# Check running Asterisk channels
asterisk -rx "core show channels brief" | grep -i agent001

# Compare with database
mysql -u cron -p'YOURPASSWORD' asterisk -e \
"SELECT user, status, channel, bridge_channel FROM vicidial_log 
WHERE user='AGENT001' ORDER BY call_date DESC LIMIT 5;"

If an agent shows INCALL in the database but no active Asterisk channel exists, the database is stale.

Cleaning Up Stale Agent Sessions

-- Mark agents as READY if they've been INCALL for over 2 hours
UPDATE vicidial_users 
SET status='READY', 
    status_date=NOW(),
    calls_today=calls_today 
WHERE user='AGENT001' 
AND status='INCALL'
AND status_date < DATE_SUB(NOW(), INTERVAL 2 HOUR);

-- Verify the change
SELECT user, status, status_date FROM vicidial_users WHERE user='AGENT001';

Agent Log Inconsistencies

ViciDial maintains detailed call logs that can reveal where calls are failing:

SELECT * FROM vicidial_log 
WHERE user='AGENT001' 
AND call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
ORDER BY call_date DESC 
LIMIT 10;

Look for calls with agent_status showing as NOT READY or UNAVAILABLE when they should show as READY.

Dialer Process Status

The ViciDial daemon processes (astguiclient, SipServer, etc.) must be running for call routing to work:

# Check critical ViciDial processes
ps aux | grep -i "astguiclient\|SipServer\|ViciAutoCall"

# Typical output should show processes running:
# root  12345  0.5  1.2  /usr/share/astguiclient/astguiclient.pl
# root  12346  0.3  0.8  /usr/share/astguiclient/SipServer.pl
# root  12347  0.2  0.6  /usr/share/astguiclient/ViciAutoCall.pl

If critical processes are missing, restart ViciDial:

# Stop ViciDial
/etc/init.d/asterisk stop
sleep 2

# Start ViciDial
/etc/init.d/asterisk start

# Verify processes started
sleep 5
ps aux | grep astguiclient | grep -v grep

Section 5: Dialplan and Extension Configuration

ViciDial Dialplan Structure

ViciDial routes inbound calls through extension dialplans. Check /etc/asterisk/extensions-vicidial.conf:

; Example inbound call route to agent
[from-internal]
exten => 101,1,Answer()
exten => 101,n,Set(AGENT=101)
exten => 101,n,Dial(SIP/101,20,m)
exten => 101,n,VoiceMail(101@default)
exten => 101,n,Hangup()

; Campaign inbound routing
[vicidial_campaign]
exten => 3000,1,AGI(agi://127.0.0.1:4573/call_log)
exten => 3000,n,Goto(agent-available,1)
exten => 3000,n,Voicemail(queue@campaign)

Agent Extension Dialplan

Each agent extension must have a valid dialplan context:

; Check agent SIP peer context
[agents]
exten => 101,1,Answer()
exten => 101,n,Dial(SIP/101,25,m)
exten => 101,n,Hangup()

Verify the agent's SIP peer context matches a defined context:

# Check agent SIP configuration
grep -A 10 "^\\[101\\]" /etc/asterisk/sip-vicidial.conf | grep context

The context should match a defined context in the extensions configuration.

Reload Dialplan After Changes

# Reload dialplan without restarting Asterisk
asterisk -rx "dialplan reload"

# Verify dialplan loaded
asterisk -rx "dialplan show agents" | head -20

Section 6: Practical Troubleshooting Workflow

Step-by-Step Diagnostic Process

Step 1: Verify Agent Exists and Has Correct Status

mysql -u cron -p'YOURPASSWORD' asterisk -e \
"SELECT user, status, phone_login, last_login_ip, calls_today FROM vicidial_users WHERE user='AGENT001';"

Expected: Status = READY, phone_login populated, recent last_login_ip

Step 2: Confirm Phone Registration

asterisk -rx "sip show peer $(mysql -u cron -p'YOURPASSWORD' asterisk -e \
"SELECT phone_login FROM vicidial_users WHERE user='AGENT001' LIMIT 1;" | tail -1)"

Expected: Status shows OK or UNKNOWN, Qualify: Yes

Step 3: Check Campaign Assignment

mysql -u cron -p'YOURPASSWORD' asterisk -e \
"SELECT campaign_id FROM vicidial_campaign_agents WHERE agent_id='AGENT001' AND active='Y';"

Expected: Returns at least one campaign

Step 4: Review Recent Call Attempts

mysql -u cron -p'YOURPASSWORD' asterisk -e \
"SELECT call_date, user, status, agent_status FROM vicidial_log 
WHERE user='AGENT001' 
AND call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR) 
ORDER BY call_date DESC LIMIT 5;"

Expected: Recent calls showing READY when attempted

Step 5: Check Asterisk Logs

tail -50 /var/log/asterisk/messages | grep -i "dial\|agent\|unavailable"

Look for any DIAL errors or unavailable messages related to the agent's extension.

Creating a Diagnostic Script

Create a reusable troubleshooting script:

#!/bin/bash
# vicidial-agent-check.sh

AGENT=${1:-AGENT001}
MYSQLPASS="YOURPASSWORD"
MYSQLUSER="cron"

echo "=== ViciDial Agent Availability Diagnostic ==="
echo "Agent: $AGENT"
echo ""

echo "1. Database Agent Record:"
mysql -u $MYSQLUSER -p$MYSQLPASS asterisk -e \
"SELECT user, status, phone_login, calls_today, last_login_ip FROM vicidial_users WHERE user='$AGENT';"

echo ""
echo "2. Asterisk SIP Registration:"
EXTENSION=$(mysql -u $MYSQLUSER -p$MYSQLPASS asterisk -e \
"SELECT phone_login FROM vicidial_users WHERE user='$AGENT';" | tail -1)

if [ -n "$EXTENSION" ]; then
  asterisk -rx "sip show peer $EXTENSION"
else
  echo "No extension found for agent"
fi

echo ""
echo "3. Campaign Assignments:"
mysql -u $MYSQLUSER -p$MYSQLPASS asterisk -e \
"SELECT campaign_id, active FROM vicidial_campaign_agents WHERE agent_id='$AGENT';"

echo ""
echo "4. Recent Call Attempts:"
mysql -u $MYSQLUSER -p$MYSQLPASS asterisk -e \
"SELECT call_date, status, agent_status FROM vicidial_log 
WHERE user='$AGENT' 
AND call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR) 
ORDER BY call_date DESC LIMIT 5;"

echo ""
echo "5. Asterisk Process Status:"
ps aux | grep -E "astguiclient|SipServer" | grep -v grep

Make it executable and run:

chmod +x vicidial-agent-check.sh
./vicidial-agent-check.sh AGENT001

Troubleshooting Section

Issue: Agent Shows READY but Calls Don't Route

Symptoms:

Agent logged in with READY status
Incoming calls available but agent doesn't receive them
No error in agent screen

Diagnosis:

# Check if calls are even reaching ViciDial
tail -20 /var/log/asterisk/messages | grep "inbound\|incoming"

# Verify campaign is accepting calls
mysql -u cron -p'YOURPASSWORD' asterisk -e \
"SELECT campaign_id, active, pause_calls, lead_distribution_method FROM vicidial_campaigns WHERE campaign_id='CAMPAIGN01';"

Solutions:

Verify campaign is not paused (pause_calls = 'N')
Check if agent has minimum calls limit reached (vicidial_campaign_agents.max_calls_today)
Ensure campaign's lead pool has available leads
Verify inbound route points to correct campaign

Issue: "Agent Not Available" Error After Login

Symptoms:

Agent successfully logs in
Immediately receives error message
Status shows as READY but calls won't come through

Diagnosis:

SELECT user, status, phone_login, last_login_ip, last_login_time 
FROM vicidial_users 
WHERE user='AGENT001';

SELECT * FROM vicidial_log 
WHERE user='AGENT001' 
AND call_date >= DATE_SUB(NOW(), INTERVAL 5 MINUTE) 
LIMIT 3;

Solutions:

Force agent logout:

UPDATE vicidial_users SET status='LOGGED OUT' WHERE user='AGENT001';

Clear any stale sessions:

asterisk -rx "sip show channels" | grep 101

Wait 30 seconds and have agent log back in

Issue: Phone Keeps Unregistering

Symptoms:

Agent phone registration drops frequently
Pattern: Registered → Unreachable → Registered (repeat)
Calls drop or fail to connect

Diagnosis:

# Check registration frequency
tail -100 /var/log/asterisk/messages | grep -i "register.*101"

# Check network connectivity from phone
ping <agent-phone-ip>

Solutions:

Adjust SIP settings in /etc/asterisk/sip-vicidial.conf:

[general]
registerintervalseconds=60
qualify=yes
qualifyfreq=60
notifyringing=yes

Add keep-alive to specific peer:

[101]
keepalive=25
qualify=yes
qualifyfreq=30

Check for network connectivity issues between phone and server:

# From agent phone's perspective (if possible)
tcpdump -i eth0 -n "host <vicidial-server-ip>"

Issue: Multiple Agents Not Available Simultaneously

Symptoms:

Multiple agents report unavailability at the same time
Usually after system restart or database issue

Diagnosis:

# Check if astguiclient process is running
ps aux | grep astguiclient | grep -v grep

# Check for database connection issues
tail -20 /var/log/asterisk/messages | grep -i "database\|mysql\|connection"

Solutions:

Restart ViciDial services:

/etc/init.d/asterisk stop
sleep 3
/etc/init.d/asterisk start
sleep 5

# Verify processes
ps aux | grep astguiclient | grep -v grep | wc -l
# Should return at least 3-4 processes

Reset all agent statuses (nuclear option - use sparingly):

UPDATE vicidial_users 
SET status='READY' 
WHERE status IN ('NOT READY', 'BREAK', 'LUNCH', 'UNAVAILABLE')
AND last_login_time > DATE_SUB(NOW(), INTERVAL 8 HOUR);

-- Verify
SELECT COUNT(*) FROM vicidial_users WHERE status='READY';

Issue: New Agent Cannot Get Calls

Symptoms:

Newly created agent account
Phone registered successfully
Campaign assigned but no calls received

Diagnosis:

SELECT * FROM vicidial_users WHERE user='AGENT_NEW';
SELECT * FROM vicidial_campaign_agents WHERE agent_id='AGENT_NEW';

Verify both records exist and are active.

Solutions:

Verify user group permissions:

SELECT * FROM vicidial_user_groups 
WHERE user_group = (SELECT user_group FROM vicidial_users WHERE user='AGENT_NEW');

Check if user group is assigned to campaign:

SELECT * FROM vicidial_campaign_user_groups 
WHERE campaign_id='CAMPAIGN01';

Ensure agent phone extension is unique:

SELECT user, phone_login FROM vicidial_users WHERE phone_login='101' AND user != 'AGENT_NEW';

Should return 0 rows.

Issue: Agent Can Dial Out But Not Receive Calls

Symptoms:

Agent can make outbound calls successfully
Inbound/campaign calls don't arrive
No error messages

Diagnosis:

# Check dialplan context for agent
grep -A 5 "^\\[101\\]" /etc/asterisk/sip-vicidial.conf | grep context

# Verify context exists
asterisk -rx "dialplan show <context>" | head -20

Solutions:

Verify SIP peer context matches a valid context with agent extensions:

[101]
type=friend
context=agents     # This context must be defined

Reload dialplan:

asterisk -rx "dialplan reload"

Check campaign inbound context routing:

# Verify campaign routing
mysql -u cron -p'YOURPASSWORD' asterisk -e \
"SELECT campaign_id, answer_phone_number FROM vicidial_campaigns WHERE campaign_id='CAMPAIGN01';"

Summary

The "Agent Not Available" error in ViciDial typically stems from one of five areas:

Agent Status Issues: Agent in non-available status (NOT READY, BREAK, LUNCH). Fix by checking vicidial_users.status and ensuring agent transitions to READY.
Phone Registration: Agent's extension not registered with Asterisk. Verify via sip show peers and check SIP configuration in /etc/asterisk/sip-vicidial.conf.
Campaign Routing: Agent not assigned to campaign or campaign paused. Verify vicidial_campaign_agents and vicidial_campaigns tables.
Database Inconsistency: Stale database records not matching live Asterisk state. Clean up via targeted UPDATE queries and restart ViciDial services.
Dialplan/Extension Issues: Invalid dialplan context or missing extension configuration. Check /etc/asterisk/extensions-vicidial.conf and reload with dialplan reload.

Best Practices Going Forward

Monitor agent status regularly: Create alerts for agents stuck in INCALL or NOT READY
Maintain clean databases: Run weekly cleanup scripts on old log entries
Log SIP registration issues: Enable detailed SIP logging for troubleshooting
Test new agent setup: Run through complete login and test call workflow before deployment
Document your changes: Keep audit trail of any manual database modifications

Quick Reference Commands

# Agent status check
mysql -u cron -p asterisk -e "SELECT user, status, phone_login FROM vicidial_users WHERE user='AGENT001';"

# SIP registration check
asterisk -rx "sip show peers" | grep -i agent

# Recent calls log
mysql -u cron -p asterisk -e "SELECT call_date, user, status FROM vicidial_log WHERE user='AGENT001' AND call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR);"

# Restart ViciDial
/etc/init.d/asterisk restart

# Check critical processes
ps aux | grep astguiclient | grep -v grep

With this comprehensive approach to diagnosing "Agent Not Available" errors, you now have both the theoretical understanding and practical commands to resolve these issues quickly in production environments.

ViciDial DEAD Call Status — Why Agents Get Dead Air & How to Fix It

Moisi Trungu — Sun, 26 Jul 2026 03:30:03 +0000

ViciDial DEAD Call Status — Why Agents Get Dead Air & How to Fix It

Master the root causes of dead calls in ViciDial, diagnose them using logs and database queries, and implement proven fixes to eliminate dead air and improve call quality.

Prerequisites

Before diving into this tutorial, ensure you have:

A functioning ViciDial installation (v2.12 or later recommended)
SSH/root access to your ViciDial server
Basic familiarity with Asterisk CLI commands and SIP protocol
Access to MySQL/MariaDB database with asterisk database selected
Knowledge of ViciDial call flow basics (inbound/outbound, IVR, transfer)
Ability to read Asterisk log files and query ViciDial tables
A test phone line or internal extension for testing

Understanding DEAD Call Status in ViciDial

What is a DEAD Call?

A DEAD call status in ViciDial occurs when an agent answers the phone expecting to speak with a caller, but hears only silence—dead air. The call appears answered in the system, but no media (audio) is flowing. The agent may wait 10-30 seconds or longer before realizing the line is dead.

DEAD calls are frustrating because:

Agents waste time on unproductive calls
Call metrics are skewed (false answers affecting answer rate)
Customer experience degrades if it's an inbound scenario
Compliance issues arise (wasted call minutes, dropped conversations)
Troubleshooting becomes difficult without clear error indicators

Where DEAD Calls Appear in ViciDial

Check your ViciDial database for DEAD status records:

SELECT call_date, vicidial_id, user, phone_number, call_length, 
       status, call_status, pause_sec, talk_sec, dispo 
FROM vicidial_log 
WHERE call_status = 'DEAD' 
AND call_date > DATE_SUB(NOW(), INTERVAL 1 DAY) 
ORDER BY call_date DESC LIMIT 50;

The call_status field records DEAD. Related fields:

status — agent disposition (often blank for DEAD calls)
talk_sec — usually very low (2-5 seconds)
pause_sec — time agent held the line waiting
vicidial_id — unique call ID for cross-referencing logs

Root Causes of DEAD Calls

1. RTP (Audio Stream) Connection Failures

Symptom: Call connects (SIP 200 OK received), but no audio flows.

Root Cause: RTP packets from carrier or endpoint aren't reaching ViciDial's RTP port range (typically 10000-20000).

Common Triggers:

Firewall blocking RTP ports
NAT misconfiguration between carrier and ViciDial
SIP and RTP on different source IPs
Carrier sending RTP to wrong destination IP

Check Current RTP Config:

grep -i "^rtp" /etc/asterisk/asterisk.conf

Expected output:

[rtp]
rtpstart=10000
rtpend=20000

2. Early Media Handling Issues

Symptom: Call shows as answered, but agent hears ringing, IVR prompt, or silence.

Root Cause: Early media (180 Ringing, 183 Session Progress) is sent before final 200 OK. If ViciDial doesn't properly bridge early media to the agent, dead air results.

Check SIP Trunk Config:

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

Look for missing progressinband or incorrect t38pt_udptl settings.

3. DTMF Tone Negotiation Problems

Symptom: Call connects but DTMF (IVR key presses) fail, freezing call flow.

Root Cause: SIP and RTP codec mismatch, or DTMF mode misconfiguration (RFC 2833 vs. Inband vs. INFO).

4. One-Way Audio

Symptom: Agent can hear caller, but caller hears nothing (or vice versa).

Root Cause: Asymmetric RTP routing—media path from caller to agent differs from agent to caller.

Common Cause: SIP proxy sending RTP invite to wrong IP; agent NIC not matching advertised SIP IP.

5. Carrier SIP Gateway Issues

Symptom: DEAD calls spike after carrier deployment or config change.

Root Cause:

Carrier not properly handling call state
Premature call termination (180 Ringing → BYE without 200 OK)
Carrier stripping or mangling SIP headers

6. CID Timeout or Caller ID Delivery Delay

Symptom: Call answers but agent screen doesn't populate; agent gets dead air.

Root Cause: ViciDial waiting for database lookup (caller name, account info) that times out before bridging.

Check vicidial_campaign config:

SELECT campaign_id, carrier_id, phone_code, lead_filter_id, 
       cid_filter_id, wait_for_callid_lookup 
FROM vicidial_campaigns 
WHERE campaign_id = 'TEST_CAMP' \G

If wait_for_callid_lookup = 'Y', increase timeout or disable for high-volume campaigns.

7. Agent Channel Hangup (Premature Disconnect)

Symptom: Call appears answered but agent channel drops immediately.

Root Cause: Agent extension misconfigured, channel type wrong, or agent phone can't sustain SIP registration.

Check Agent Phone Status:

asterisk -rx "sip show peers" | grep -i agent

Look for agents with UNREG (unregistered) or high response time (>500ms).

Diagnostic Tools and Log Analysis

Step 1: Enable ViciDial Call Detail Logging

Ensure verbose logging is enabled in /etc/asterisk/logger.conf:

[general]
dateformat=%F %T

[logfiles]
messages => notice,warning,error,verbose
full => notice,warning,error,verbose,debug,dtmf
verbose_file => verbose(5)

Restart Asterisk:

systemctl restart asterisk

Step 2: Capture Real-Time Call Debug

When a DEAD call occurs, immediately grab Asterisk debug:

asterisk -rx "sip set debug on"
asterisk -rx "core set verbose 3"

Reproduce the issue, then capture logs:

tail -n 1000 /var/log/asterisk/messages | grep -A 20 "DEAD\|BYE\|CANCEL" > /tmp/dead_call_debug.txt
tail -n 500 /var/log/asterisk/full >> /tmp/dead_call_debug.txt

Step 3: Query ViciDial Log for Call Chain

Use the vicidial_id from the DEAD call to trace the entire call:

SELECT call_date, user, phone_number, call_length, talk_sec, 
       pause_sec, status, call_status, message, vicidial_id 
FROM vicidial_log 
WHERE vicidial_id = '1234567890-1234567890' \G

Also check vicidial_closer_log (for transferred calls):

SELECT call_date, user, phone_number, closer_sec, status, 
       call_status, message FROM vicidial_closer_log 
WHERE vicidial_id = '1234567890-1234567890' \G

Step 4: Monitor Active Channels During Call

While call is in progress, run:

asterisk -rx "core show channels"

Look for entries like:

Channel              State   Type    Sec  Lag
SIP/carrier-00001234 Up      SIP        3  0
Local/user123@vicid  Up      Local      3  0
SIP/user123-00001235 Up      SIP        3  0

If one channel shows Down or is missing, RTP negotiation failed.

Step 5: Check RTP Stream Status

ViciDial doesn't natively show RTP stats, but Asterisk does:

asterisk -rx "rtp show stats"

Sample output:

RTP Stats
SSRC     Sent(pkts/bytes)  Recv(pkts/bytes)  Lost(%)  RTT(ms)
0x12345678 150/2400          145/2320          3.3     45

High loss (>5%) or missing recv packets = RTP path problem.

Step 6: Examine SIP Trace via PCAP

Capture raw SIP/RTP packets for deep analysis:

tcpdump -i any -s 0 -w /tmp/dead_call.pcap 'sip or rtp' &
sleep 30 && pkill tcpdump

Analyze with Wireshark (on your workstation):

scp root@vicidial-server:/tmp/dead_call.pcap ~/Desktop/
# Open in Wireshark, filter: sip or rtp
# Look for: SIP 200 OK followed by no RTP packets

Fixing DEAD Calls — Configuration Solutions

Fix 1: Verify and Secure RTP Port Range

Problem: Firewall or carrier blocking RTP traffic.

Solution:

Check firewall rules:

ufw status numbered | grep -i rtp
# Or for iptables:
iptables -L -n | grep -E "10000|20000"

Open RTP ports (if using ufw):

ufw allow 10000:20000/udp comment "Asterisk RTP"
ufw allow 10000:20000/tcp comment "Asterisk RTP"
ufw reload

Or with iptables:

iptables -I INPUT 1 -p udp --dport 10000:20000 -j ACCEPT
iptables -I INPUT 1 -p tcp --dport 10000:20000 -j ACCEPT
iptables-save > /etc/iptables/rules.v4

Increase RTP pool if handling 500+ concurrent calls:

Edit /etc/asterisk/asterisk.conf:

[rtp]
rtpstart=10000
rtpend=30000
rtpbindaddr=0.0.0.0

Restart Asterisk:

systemctl restart asterisk

Fix 2: Configure SIP Trunk for Early Media

Problem: Early media (183 Session Progress) not bridged to agent.

Solution:

Edit /etc/asterisk/sip-vicidial.conf for your carrier trunk:

[carrier_trunk_name]
type=peer
host=carrier.example.com
port=5060
context=from-carrier
disallow=all
allow=ulaw,alaw
dtmfmode=rfc2833
progressinband=yes
tos_sip=af31
tos_audio=ef
videosupport=no
g726nonstandard=no
t38pt_udptl=no
nat=force_rport,comedia
directmedia=no

Key Parameters:

progressinband=yes — routes 183 Session Progress audio to agent
dtmfmode=rfc2833 — use RFC 2833 for DTMF (most reliable)
nat=force_rport,comedia — handles NAT correctly
directmedia=no — keeps ViciDial in media path

Reload SIP:

asterisk -rx "sip reload"

Fix 3: Check and Fix One-Way Audio

Problem: Asymmetric RTP path.

Solution:

Verify ViciDial server's advertised SIP IP matches RTP source IP:

ifconfig | grep -A 1 "inet "

Check SIP bind address in /etc/asterisk/sip-vicidial.conf:

[general]
bindaddr=10.0.1.50
bindport=5060

Must match your actual NIC IP. Do not use 0.0.0.0 in production.

For carrier SIP trunks, ensure externip or localnet is set correctly:

[general]
externip=203.0.113.50
localnet=10.0.0.0/255.255.0.0

This tells Asterisk to use externip for external addresses and keep localnet addresses as-is.

Disable directmedia to force RTP through ViciDial:

[carrier_trunk]
directmedia=no
canreinvite=no

Restart Asterisk and test.

Fix 4: Increase SIP Transaction Timeout

Problem: Slow carrier or network causes call to timeout before answering.

Solution:

Edit /etc/asterisk/sip-vicidial.conf:

[general]
sip_invite_timeout=30
sip_t1=500
sip_t1min=100

Values (in milliseconds):

sip_invite_timeout=30 — max 30 seconds to wait for final response
sip_t1=500 — retransmit interval (default 500ms)
sip_t1min=100 — minimum retransmit interval

Reload:

asterisk -rx "sip reload"

Fix 5: Optimize Agent Phone Registration

Problem: Agent SIP phones dropping registration or experiencing jitter.

Solution:

Edit /etc/asterisk/sip-vicidial.conf:

[agent_default]
type=friend
context=from-internal
disallow=all
allow=ulaw
dtmfmode=rfc2833
qualify=yes
qualifyfreq=60
timert1=500
registertimeout=120
session-expires=3600
session-minse=900
sipdebug=no

Parameters:

qualifyfreq=60 — check if phone is alive every 60 seconds
registertimeout=120 — allow 120-second registration window
session-expires=3600 — keep session alive for 1 hour
session-minse=900 — minimum session duration 15 minutes

Restart Asterisk:

systemctl restart asterisk

Monitor agent registration status:

asterisk -rx "sip show peers" | tail -20

Fix 6: Disable ViciDial Caller ID Lookup Timeout

Problem: Database lookup delays cause dead air while agent waits.

Solution:

In /usr/share/astguiclient/ edit the appropriate outbound script. For example, in Vicidial Manager:

Go to Admin > Campaigns
Select your campaign
Set CID Lookup Delay to 0 seconds
Or via SQL:

UPDATE vicidial_campaigns 
SET wait_for_callid_lookup = 'N' 
WHERE campaign_id = 'TEST_CAMP';

If you need caller lookups, increase timeout in /etc/astguiclient/astguiclient.conf:

cid_lookup_timeout=5000

Value in milliseconds. Default is often too low (1000-2000ms).

Fix 7: Fix Carrier-Specific DEAD Call Issues

Problem: Specific carrier causing all DEAD calls.

Solution:

Test the carrier trunk directly. Replace CARRIER_CONTEXT with your carrier context:

asterisk -rx "sip debug peer carrier_trunk_name"

Dial a test call and watch for:

SIP 183 vs. 180 vs. 200 — which does carrier send?
RTP audio — does it start before or after 200 OK?
Abnormal headers — is carrier stripping required headers?

Common carrier issues and fixes:

Symptom	Carrier Behavior	Fix
DEAD after 5 sec	Sending BYE without proper disconnect	Add `sendrpid=yes` in trunk config
DEAD on every call	Sending 183 but no RTP	Set `progressinband=yes`
One-way audio	Expecting direct RTP	Set `directmedia=no` and `nat=force_rport,comedia`
Sporadic DEAD	RTP port saturation	Increase rtpstart/rtpend range

System-Level Fixes

Increase File Descriptors

Problem: Too many open connections causing RTP stream loss.

Solution:

Edit /etc/security/limits.conf:

asterisk soft nofile 65536
asterisk hard nofile 65536
asterisk soft memlock unlimited
asterisk hard memlock unlimited

Verify after restart:

sudo -u asterisk bash -c 'ulimit -n'
# Should output: 65536

Optimize Kernel Network Parameters

Edit /etc/sysctl.conf:

# Increase socket buffer sizes
net.core.rmem_max=134217728
net.core.wmem_max=134217728
net.ipv4.tcp_rmem=4096 87380 67108864
net.ipv4.tcp_wmem=4096 65536 67108864

# Increase connection backlog
net.core.somaxconn=4096
net.ipv4.tcp_max_syn_backlog=4096

# Enable SYN cookies to prevent SYN floods
net.ipv4.tcp_syncookies=1

# Increase UDP buffer sizes
net.core.rmem_max=134217728
net.core.rmem_default=134217728
net.core.wmem_max=134217728
net.core.wmem_default=134217728

Apply changes:

sysctl -p

Monitor Call Quality in Real-Time

Create a monitoring script at /usr/local/bin/monitor_dead_calls.sh:

#!/bin/bash

THRESHOLD=5
INTERVAL=60

while true; do
    DEAD_COUNT=$(mysql -u root -p$DB_PASS asterisk -se \
        "SELECT COUNT(*) FROM vicidial_log \
         WHERE call_status = 'DEAD' \
         AND call_date > DATE_SUB(NOW(), INTERVAL 1 MINUTE);")

    if [ "$DEAD_COUNT" -gt "$THRESHOLD" ]; then
        echo "ALERT: $DEAD_COUNT dead calls in last minute" | \
            mail -s "ViciDial DEAD Call Alert" admin@example.com

        # Capture diagnostics
        asterisk -rx "core show channels" >> /tmp/dead_alert_$(date +%s).txt
        asterisk -rx "sip show peers" >> /tmp/dead_alert_$(date +%s).txt
    fi

    sleep $INTERVAL
done

Make executable and run in background:

chmod +x /usr/local/bin/monitor_dead_calls.sh
/usr/local/bin/monitor_dead_calls.sh &

Troubleshooting Guide

Symptom: All Inbound Calls are DEAD

Diagnosis:

SELECT COUNT(*), call_status FROM vicidial_log 
WHERE call_date > DATE_SUB(NOW(), INTERVAL 1 HOUR) 
GROUP BY call_status;

Checks:

Is carrier sending any audio?

   asterisk -rx "rtp show stats"

If no stats, RTP isn't flowing.

Is IVR running?

   asterisk -rx "core show channels verbose" | grep -i ivr

Should show IVR context, not dead channels.

Check inbound context in /etc/asterisk/extensions-vicidial.conf:

   grep -A 10 "\[from-carrier\]" /etc/asterisk/extensions-vicidial.conf

Solution: Verify context in carrier SIP trunk matches actual Asterisk context.

Symptom: DEAD Calls Only on Weekdays 9-5

Diagnosis: Pattern suggests call volume issue.

Check Channel Saturation:

asterisk -rx "core show channels" | wc -l

Compare to your max concurrent calls setting. If near limit, increase:

In /etc/asterisk/asterisk.conf:

[rtp]
rtpstart=10000
rtpend=40000

And in /etc/asterisk/sip-vicidial.conf:

[general]
maxforwards=70
channel_limit=1000,warn

Symptom: DEAD Calls from Specific Carrier IP

Diagnosis: Carrier SIP trunk issue, not global.

Fix:

Check if carrier has NAT:

   grep -A 10 "host=CARRIER_IP" /etc/asterisk/sip-vicidial.conf

Force RTP through ViciDial for this trunk:

   [carrier_with_nat]
   host=203.0.113.100
   nat=force_rport,comedia
   directmedia=no

Restart Asterisk and test calls from that carrier only.

Symptom: Random DEAD Calls (Not Reproducible)

Diagnosis: Likely RTP packet loss or temporary network issue.

Check Network Stats:

watch -n 1 "cat /proc/net/udp | grep -E '10000|20000' | wc -l"

Monitor if UDP ports are getting congested.

Solution:

Check for packet loss:

   ping -c 100 carrier.example.com | grep -i packet

If loss >1%, contact carrier or ISP.
Increase RTP jitter buffer in /etc/asterisk/asterisk.conf:

   [rtp]
   rtpstart=10000
   rtpend=20000
   rtptimeout=3600
   rtpholdtimeout=3600

Symptom: DEAD Calls Only After Call Transfer

Diagnosis: Bridge or transfer context issue.

Check Transfer Extension:

grep -B 5 -A 10 "transfer\|bridge" /etc/asterisk/extensions-vicidial.conf | head -30

Ensure transfer context properly bridges RTP. If using Dial(), verify:

exten => _X.,1,Dial(SIP/${EXTEN}@agent-pool,,g)

The g flag allows graceful hangup. Missing flags can cause dead air.

Summary

DEAD calls in ViciDial stem from misconfigurations across SIP trunks, RTP routing, firewall rules, and database settings. Here's your action plan:

Immediate Steps:

Identify the scope: Is it all calls, one carrier, or one campaign?

   SELECT carrier_id, COUNT(*) as dead_count FROM vicidial_log 
   WHERE call_status = 'DEAD' 
   AND call_date > DATE_SUB(NOW(), INTERVAL 24 HOUR) 
   GROUP BY carrier_id;

Enable SIP debugging and capture a failed call.
Verify RTP flows: Check asterisk -rx "rtp show stats" during calls.
Check firewall: Ensure ports 10000-20000 UDP are open.

Medium-Term Fixes:

Review carrier trunk config: Ensure progressinband=yes, nat=force_rport,comedia, directmedia=no.
Optimize SIP timeouts: Increase sip_invite_timeout if carrier is slow.
Disable CID lookup timeouts for high-volume campaigns.

Long-Term Optimization:

Monitor proactively: Use the monitoring script to catch DEAD call spikes.
Load test: Simulate peak call volume to find channel/RTP saturation limits.
Document carrier behaviors: Keep detailed notes on each carrier's SIP/RTP quirks for future troubleshooting.

With these fixes applied systematically, DEAD call rates should drop from 5-10% to <0.1% in production. Test each change individually and measure impact before moving to the next.

ViciDial carrier_log No Answer — Diagnosing Failed Outbound Calls

Moisi Trungu — Sat, 25 Jul 2026 03:30:02 +0000

ViciDial carrier_log No Answer — Diagnosing Failed Outbound Calls

Master the art of troubleshooting "No Answer" call failures in ViciDial by reading carrier_log entries, analyzing Asterisk SIP traces, and identifying root causes in your telephony infrastructure

Prerequisites

Before diving into carrier_log diagnostics, ensure you have:

A functioning ViciDial installation (v2.12+) with Asterisk 13+ or PJSIP
SSH/command-line access to your ViciDial server
MySQL client tools to query the asterisk database
Familiarity with basic Asterisk and SIP concepts
Access to /var/log/asterisk/ logs with read permissions
Knowledge of your carrier's SIP trunk configuration
Understanding of ViciDial call flow (Vicidial → Asterisk → Carrier → Destination)

Understanding carrier_log and No Answer

What is carrier_log?

The vicidial_carrier_log table is a critical diagnostic table in ViciDial that records every interaction between your Asterisk system and your telephony carrier. Unlike vicidial_log (which tracks agent calls), carrier_log captures the raw SIP signaling outcomes, timeouts, and provider responses.

When a call shows "No Answer" in carrier_log, it means one of these scenarios occurred:

The destination phone never rang (pre-answer failure)
The destination phone rang but nobody picked up within the timeout window
The carrier rejected the call before it reached the destination
A SIP timeout occurred during the call attempt

Key carrier_log Fields

SELECT * FROM vicidial_carrier_log WHERE carrier_log_id = 12345\G

Critical fields to examine:

carrier_log_id: Unique identifier
call_date: Timestamp of the call attempt
carrier_id: Which carrier this call used
phone_number: Dialed destination
sip_code: The SIP response code (100, 180, 183, 200, 486, 487, 408, 503, etc.)
sip_hangup_cause: Asterisk hangup cause string
call_duration: How long the call lasted in seconds
hangup_source: Where the disconnect originated (asterisk, carrier, bridge, etc.)

Architecture: Call Flow and Where "No Answer" Happens

Agent dials → ViciDial engine → Asterisk dialplan
    ↓
Asterisk creates SIP INVITE → Carrier SIP gateway
    ↓
Carrier routes call → Destination carrier
    ↓
Destination phone receives INVITE → Phone rings
    ↓
200 OK received → Bridge established
    ↓
Call connected / Hangup

"No Answer" failures typically occur at these points:

Pre-dial: Carrier rejects INVITE (4xx/5xx before 100 Trying)
Ringing: Phone rings (180 Ringing received) but caller hangs up or timeout
Timeout: Call exceeds configured timeout without answer (408)
Silent failure: INVITE lost, no response received

Step 1: Locate and Query carrier_log Entries

Find the relevant carrier_log record

# SSH into ViciDial server
ssh root@vicidial.example.com

# Query the database for recent "No Answer" calls
mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
SELECT 
    carrier_log_id,
    call_date,
    phone_number,
    sip_code,
    sip_hangup_cause,
    call_duration,
    hangup_source,
    carrier_id
FROM vicidial_carrier_log
WHERE sip_hangup_cause LIKE 'NO_ANSWER%'
    AND call_date >= DATE_SUB(NOW(), INTERVAL 2 HOUR)
ORDER BY call_date DESC
LIMIT 20;
EOF

Examine detailed carrier_log entry

mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
SELECT 
    carrier_log_id,
    call_date,
    phone_number,
    session_id,
    sip_code,
    sip_hangup_cause,
    call_duration,
    hangup_source,
    carrier_id,
    tried_count,
    user_only
FROM vicidial_carrier_log
WHERE carrier_log_id = 567890\G
EOF

Example output:

*************************** 1. row ***************************
        carrier_log_id: 567890
            call_date: 2024-01-15 14:23:45
           phone_number: 15551234567
            session_id: 1705338225-4892
              sip_code: 180
      sip_hangup_cause: NO_ANSWER
        call_duration: 22
         hangup_source: asterisk
            carrier_id: 3
          tried_count: 1
           user_only: 0

Step 2: Correlate with Asterisk Full Logs

Enable verbose SIP logging

First, ensure Asterisk SIP debugging is configured:

# /etc/asterisk/logger.conf
[logfiles]
messages => verbose,debug,notice,warning,error
full => verbose,debug,notice,warning,error,dtmf,fax
sip => verbose,debug,notice,warning,error

Reload logger:

asterisk -rx "logger reload"

Capture SIP trace for the specific call

Use the session_id from carrier_log to find related Asterisk logs:

# Real-time SIP trace (next call)
asterisk -rx "sip set debug on"

# Make test call, then:
asterisk -rx "sip set debug off"

Review /var/log/asterisk/messages

# Search for the session_id from carrier_log
grep "1705338225-4892" /var/log/asterisk/messages | tail -50

# Or search for the phone number
grep "15551234567" /var/log/asterisk/messages | head -100

Example SIP trace showing "No Answer":

[2024-01-15 14:23:45] VERBOSE[31245][C-0000a2d7] app_dial.c: Called SIP/carrier3/15551234567
[2024-01-15 14:23:45] VERBOSE[31245][C-0000a2d7] netsock2.c: == Probation passed - setting RTP source address to 203.0.113.15
[2024-01-15 14:23:46] VERBOSE[31245][C-0000a2d7] pbx.c: > Channel SIP/carrier3-0000a2d8 joined 'simple_bridge' basic-bridge <C-0000a2d7>
[2024-01-15 14:23:46] VERBOSE[31245][C-0000a2d7] app_dial.c: SIP/carrier3-0000a2d8 is ringing
[2024-01-15 14:23:52] VERBOSE[31245][C-0000a2d7] pbx.c: == Spawn extension (from-vicidial, 15551234567, 1) exited non-zero on 'SIP/carrier3-0000a2d8'
[2024-01-15 14:23:52] VERBOSE[31245][C-0000a2d7] app_dial.c: SIP/carrier3-0000a2d8 answered
[2024-01-15 14:24:07] VERBOSE[31245][C-0000a2d7] app_dial.c: Timeout on SIP/carrier3-0000a2d8, checking if we should move on

Step 3: Analyze SIP Response Codes

Common SIP codes in carrier_log

SIP Code	Meaning	No Answer Cause
100	Trying	Call still in progress
180	Ringing	Destination phone ringing
183	Session Progress	In-band info (ringback)
200	OK / Answered	Call answered — NOT "No Answer"
408	Request Timeout	No response within timeout
486	Busy Here	Destination busy — NOT "No Answer"
487	Request Terminated	Caller cancelled before answer
503	Service Unavailable	Carrier/destination unavailable
480	Temporarily Unavailable	Destination unavailable

Query for SIP code patterns

mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
SELECT 
    sip_code,
    sip_hangup_cause,
    COUNT(*) as count,
    AVG(call_duration) as avg_duration
FROM vicidial_carrier_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
    AND carrier_id = 3
GROUP BY sip_code, sip_hangup_cause
ORDER BY count DESC;
EOF

No Answer diagnosis:

180 + NO_ANSWER + 22 seconds: Phone rang, caller abandoned or timeout hit
408 + NO_ANSWER: Carrier didn't respond to INVITE in time
100 + NO_ANSWER + <2 sec: Call failed before reaching destination

Step 4: Check Carrier Configuration

Verify SIP carrier is correctly defined

mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
SELECT 
    carrier_id,
    carrier_name,
    protocol,
    active,
    port,
    server_ip,
    failover_server_ip
FROM carriers
WHERE carrier_id = 3\G
EOF

Review Asterisk SIP peer configuration

# Find carrier peer definition
grep -A 30 "carrier3" /etc/asterisk/sip-vicidial.conf

Example configuration:

[carrier3]
type=peer
host=sip.carrier.com
port=5060
context=from-vicidial
disallow=all
allow=ulaw,alaw
nat=yes
insecure=port,invite
qualify=yes
qualifyfreq=60
defaultuser=vicidial_account
secret=your_sip_password
dtmfmode=rfc2833
progressinband=yes

Check for common carrier config issues

# Verify carrier is reachable
ping -c 3 sip.carrier.com

# Test SIP connectivity
asterisk -rx "sip show peers" | grep carrier3

# Check registration status
asterisk -rx "sip show registry" | grep carrier3

Example output — look for "Registered":

Host                                                    dnsmgr Username       Reg.Expires Status
sip.carrier.com:5060                                    N      vicidial_acco 3600       Registered

Step 5: Examine Dialplan Execution

Review the dialplan handling outbound calls

cat /etc/asterisk/extensions-vicidial.conf | grep -A 50 "from-vicidial"

Typical outbound dialplan:

[from-vicidial]
exten => _X.,1,NoOp(Outbound call to ${EXTEN})
exten => _X.,n,Set(CHANNEL(hangup_handler_push)=custom-handler,s,1)
exten => _X.,n,Dial(SIP/carrier3/${EXTEN},30,m)
exten => _X.,n,NoOp(Dial result: ${DIALSTATUS})
exten => _X.,n,Hangup()

The critical parameter is the timeout (30 seconds in above example).

Check actual call timeout configuration in ViciDial

mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
SELECT 
    campaign_id,
    campaign_name,
    dial_timeout,
    ringback_time
FROM vicidial_campaigns
WHERE campaign_id = 'TESTCAMP'\G
EOF

Step 6: Diagnose Ring Timeout vs Actual No Answer

Determine if destination is actually ringing

Query for calls with 180 Ringing and NO_ANSWER:

mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
SELECT 
    carrier_log_id,
    call_date,
    phone_number,
    sip_code,
    call_duration,
    hangup_source
FROM vicidial_carrier_log
WHERE sip_code = 180
    AND sip_hangup_cause = 'NO_ANSWER'
    AND call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
    AND carrier_id = 3
LIMIT 10;
EOF

Interpretation:

180 + call_duration 3-5 sec: Destination phone may not be ringing (SIP implementation issue)
180 + call_duration 20+ sec: Phone is ringing; customer simply not answering
180 + call_duration 30 sec: Timeout hit exactly at dialplan timeout

Check ringback delay vs actual ring detection

# Test call to known answering service
asterisk -rx "sip set debug on"

# From CLI or dialplan, originate test call
asterisk -rx "channel originate SIP/carrier3/15551234567 application playback silence/1"

asterisk -rx "sip set debug off"

# Review messages
tail -200 /var/log/asterisk/messages | grep -E "180|183|200|Called"

Step 7: Investigate Carrier-Side Issues

Check carrier's SIP response headers

Enable full SIP packet capture:

# Install tcpdump if needed
yum install tcpdump -y

# Capture SIP traffic to/from carrier
tcpdump -i any -s 0 -w /tmp/sip_capture.pcap "host sip.carrier.com and port 5060"

# Let it run during a test call, then Ctrl+C

# Analyze with Wireshark or tshark
tshark -r /tmp/sip_capture.pcap -Y "sip.method==INVITE or sip.CSeq.method==INVITE" -V | head -200

Check carrier logs through API or portal

Most carriers provide:

Web portal CDR access
API access to call records
Support email for detailed call traces

Request from carrier:

INVITE received timestamp
180 Ringing timestamp
Whether call reached destination
Destination carrier response codes

Test with known phone numbers

# Test with carrier's demo/testing numbers
# Most carriers provide test numbers that:
# - Always answer immediately (instant 200 OK)
# - Simulate no-answer (ring then timeout)
# - Simulate busy tone
# - Simulate invalid number

# Ask your carrier support for test numbers

Step 8: Check ViciDial Agent Timeout Settings

Review call timeout in campaign

mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
SELECT 
    campaign_id,
    campaign_name,
    dial_timeout,
    ringback_time,
    answer_detect,
    amd_level
FROM vicidial_campaigns
WHERE active = 'Y'\G
EOF

Check list-level overrides

mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
SELECT 
    list_id,
    list_name,
    dial_timeout,
    ringback_time
FROM vicidial_lists
WHERE list_id = 101\G
EOF

Examine specific lead in vicidial_log

mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
SELECT 
    uniqueid,
    lead_id,
    list_id,
    campaign_id,
    status,
    call_date,
    call_duration,
    phone_number
FROM vicidial_log
WHERE lead_id = 98765
    AND call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
ORDER BY call_date DESC\G
EOF

Step 9: Common Causes and Fixes

Issue #1: Timeout Set Too Short

Symptom: Calls consistently showing NO_ANSWER with 180 Ringing, but call_duration is exactly your dial_timeout value (e.g., always 15 seconds).

Root cause: Phone is ringing, but timeout expires before destination has chance to pick up.

Fix:

# Increase dial_timeout in campaign
mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
UPDATE vicidial_campaigns 
SET dial_timeout = 45 
WHERE campaign_id = 'TESTCAMP';
EOF

# Verify change
mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
SELECT campaign_id, dial_timeout FROM vicidial_campaigns WHERE campaign_id = 'TESTCAMP';
EOF

Issue #2: Carrier Not Routing Calls to Destination

Symptom: SIP code 180 or 183 received, but call_duration is very short (2-5 seconds), then NO_ANSWER.

Root cause: Carrier answered with ringback but didn't complete call to actual destination.

Fix:

Contact carrier support with INVITE timestamp from your logs
Ask carrier to verify routing rules for your account
Check if your CLI (caller ID) is being rejected by destination
Test from carrier's test system

Issue #3: No Progress Indication (Silent Failure)

Symptom: SIP code 100 (Trying), NO_ANSWER, call_duration <2 seconds.

Root cause: Call failed at carrier before progressing toward destination.

Fix:

# Check carrier registration status
asterisk -rx "sip show registry"

# Verify carrier peer is available
asterisk -rx "sip show peers" | grep carrier3

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

# Check ACL rules
mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
SELECT * FROM carriers WHERE carrier_id = 3\G
EOF

Issue #4: Destination Network Issues

Symptom: Intermittent NO_ANSWER; sometimes works, sometimes doesn't.

Root cause: Destination carrier or phone system is experiencing packet loss or jitter.

Fix:

# Monitor RTP packet loss
asterisk -rx "rtp show stats"

# Check jitter measurements
asterisk -rx "rtcp show" | grep -A 5 "carrier3"

# Increase RTP payload size if needed
grep -n "maxrtpplayer" /etc/asterisk/rtp.conf

Issue #5: DTMF or Codec Mismatch

Symptom: Call connects, but phone may not be detecting dialed tones or audio issues.

Root cause: Codec incompatibility or DTMF mode mismatch.

Fix:

# Verify codec agreement
# /etc/asterisk/sip-vicidial.conf

[carrier3]
allow=ulaw,alaw
dtmfmode=rfc2833

Test call with codec specification:

asterisk -rx "sip show peer carrier3" | grep -E "Codec|DTMF"

Troubleshooting

Problem: Too many "No Answer" calls suddenly appearing

Steps:

Check if carrier is registered:

   asterisk -rx "sip show registry"

Query for recent changes:

   mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
   SELECT * FROM vicidial_campaigns WHERE modified_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR);
   EOF

Check Asterisk uptime:

   asterisk -rx "core show uptime"

Review carrier status in last hour:

   grep "carrier3" /var/log/asterisk/messages | tail -100

Problem: Only specific carrier has "No Answer" issues

Steps:

Compare working vs. non-working carrier:

   mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
   SELECT carrier_id, COUNT(*) as total, 
       SUM(CASE WHEN sip_hangup_cause='NO_ANSWER' THEN 1 ELSE 0 END) as no_answer_count
   FROM vicidial_carrier_log
   WHERE call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
   GROUP BY carrier_id
   ORDER BY no_answer_count DESC;
   EOF

Test failover:

   # Temporarily disable primary carrier
   mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
   UPDATE carriers SET active='N' WHERE carrier_id=3;
   EOF

   # Make test calls to see if secondary carrier works
   # Then re-enable
   mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
   UPDATE carriers SET active='Y' WHERE carrier_id=3;
   EOF

Check carrier-specific dialplan:

   grep "carrier3\|Dial.*carrier3" /etc/asterisk/extensions-vicidial.conf

Problem: "No Answer" but agent claims phone rang at destination

Steps:

Get destination phone's call logs
Correlate timestamps between:
- Your carrier_log call_date
- Destination's received call timestamp
- Timezone differences
Request detailed CDR from destination carrier
Check if CLI (caller ID) is being blocked:

   mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
   SELECT * FROM vicidial_caller_id_log WHERE call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR) LIMIT 5;
   EOF

Problem: Intermittent "No Answer" on specific numbers

Steps:

Find pattern in failed numbers:

   mysql -u cron -p'YOURPASSWORD' asterisk << 'EOF'
   SELECT 
       phone_number,
       COUNT(*) as attempts,
       SUM(CASE WHEN sip_hangup_cause='NO_ANSWER' THEN 1 ELSE 0 END) as no_answers
   FROM vicidial_carrier_log
   WHERE call_date >= DATE_SUB(NOW(), INTERVAL 7 DAYS)
   GROUP BY phone_number
   HAVING no_answers > 3
   ORDER BY no_answers DESC;
   EOF

Check if specific area codes/exchanges are problematic
Test with different CLI origination
Contact destination carrier about those specific numbers

Summary

Diagnosing "No Answer" issues in ViciDial's carrier_log requires a systematic approach:

Identify the carrier_log record — Query vicidial_carrier_log for specific failed call
Note the SIP code — Understand what the carrier responded with
Check call duration — Short duration = pre-answer failure; Long = ringing timeout
Correlate with Asterisk logs — Use session_id to find detailed SIP traces in /var/log/asterisk/messages
Verify carrier configuration — Ensure SIP peer is active, registered, and accessible
Test with known numbers — Use carrier-provided test numbers to isolate issues
Adjust timeout settings — Increase dial_timeout if phones legitimately need more time to ring
Escalate to carrier — Provide detailed CDR, timestamps, and SIP traces for investigation

Key ViciDial tables for carrier_log analysis:

vicidial_carrier_log — Raw call attempt records
vicidial_log — Agent-facing call records (may not match carrier_log)
vicidial_campaigns — Campaign timeout settings
carriers — Carrier configuration and status
vicidial_lists — List-level overrides

Most common root causes:

Timeout set too short (45+ seconds recommended for most destinations)
Carrier not routing calls (contact carrier support)
Carrier registration issues (verify with sip show registry)
Destination network problems (verify destination carrier status)
CLI being rejected (check vicidial_caller_id_log)

By methodically working through these steps, you can pinpoint whether "No Answer" failures originate from your Asterisk/ViciDial configuration, your carrier's SIP implementation, or the destination phone/network — and take appropriate corrective action.

ViciDial 'No One Is in Your Session' Error — Causes & Fixes

Moisi Trungu — Fri, 24 Jul 2026 03:30:03 +0000

ViciDial 'No One Is in Your Session' Error — Causes & Fixes

Master the root causes of ViciDial's most frustrating connection error and implement proven solutions to keep your contact center running smoothly.

Prerequisites

Before diving into this guide, ensure you have:

A production or staging ViciDial installation (version 2.7+)
SSH access to your ViciDial server with sudo privileges
Basic understanding of ViciDial architecture (dialer, web interface, database)
Familiarity with Asterisk CLI commands
Access to MySQL/MariaDB for database inspection
Log file access (/var/log/asterisk/ directory)
A text editor (vi, nano, or equivalent)
Understanding of SIP protocol basics

This guide assumes a standard CentOS/RHEL or Debian ViciDial installation with Asterisk 11.x or higher.

Understanding the "No One Is in Your Session" Error

What the Error Means

The "No One Is in Your Session" error appears in the ViciDial agent screen when:

An agent attempts to dial a contact
The dialer initiates the outbound call
The call connects to the contact
But no agent audio channel is present or properly bridged
The contact hears silence or the agent cannot hear the contact

This is not a call failure at the SIP level—the call technically completes, but the audio bridge between agent and contact never establishes correctly.

Why It Happens

The error occurs due to one of these core issues:

Channel variable misalignment — Agent and contact channels don't share required variables
Asterisk channel bridge failure — The Asterisk bridging application fails silently
SIP registration issues — Agent extension not properly registered to Asterisk
Database desynchronization — vicidial_log and live channel state don't match
Codec mismatch — Agent and contact use incompatible audio codecs
Firewall/NAT issues — Media path broken between agent and PSTN
Memory exhaustion — Too many channels cause Asterisk to drop new channels
Dialplan routing errors — Extensions-vicidial.conf has incorrect context handling

Causes and Diagnosis

Cause 1: SIP Registration Failure

The most common cause—agents appear logged in, but their SIP extension isn't registered to Asterisk.

Diagnosis

Check Asterisk SIP peer status:

asterisk -rx "sip show peers" | grep -i agent

Look for agents with state "UNREACHABLE" or showing as offline.

Check specific agent extension:

asterisk -rx "sip show peer 6001"

Example output showing a problem:

Name       : 6001
Qualify mem : 12500
Defaddr    : 203.0.113.45:5060
Forcerport : Yes
Useragent  : Zoiper 5.4.33
Status     : UNREACHABLE (18 ms)

The key indicator: UNREACHABLE status.

Fix: Force Re-registration

From the ViciDial web admin interface, navigate to Agent and manually kick the agent offline, then have them log back in:

# Or use the command line to reload SIP configuration
asterisk -rx "sip reload"

Edit /etc/asterisk/sip-vicidial.conf and ensure the agent extension exists:

[6001]
type=friend
host=dynamic
secret=YourSecretPassword123
context=from-internal
dtmfmode=rfc2833
disallow=all
allow=ulaw
allow=gsm
allow=g729
nat=yes
qualify=yes
qualifyfreq=60

Key parameters to verify:

host=dynamic — Allows devices from any IP
nat=yes — Enables NAT traversal (critical for remote agents)
qualify=yes — Enables keepalive packets
context=from-internal — Must be set to ViciDial's internal context

Reload SIP after changes:

asterisk -rx "sip reload"

Verify re-registration:

asterisk -rx "sip show peers" | grep 6001

Cause 2: Database Desynchronization

ViciDial stores live session information in the database. If a crash or improper logout occurs, stale data blocks new sessions.

Diagnosis

Query the database for orphaned sessions:

mysql> USE asterisk;
mysql> SELECT vicidial_id, user, call_date, status FROM vicidial_log 
       WHERE status IN ('INCALL','QUEUE','LIVE') 
       AND call_date < DATE_SUB(NOW(), INTERVAL 2 HOUR);

This query finds calls marked as "LIVE" older than 2 hours—these are definitely stale.

Check the agent's current session status:

mysql> SELECT user_id, status, last_update FROM vicidial_users_log 
       WHERE user_id = 'agent001' 
       ORDER BY last_update DESC LIMIT 1;

If the timestamp is old but status shows "LIVE," the session is orphaned.

Fix: Clean Stale Sessions

Option 1: Update vicidial_log directly

mysql> UPDATE vicidial_log 
       SET status = 'ABANDONED' 
       WHERE status IN ('INCALL','QUEUE','LIVE') 
       AND call_date < DATE_SUB(NOW(), INTERVAL 2 HOUR);

Option 2: Use ViciDial's cleanup script

ViciDial includes a maintenance script. Run it:

sudo -u asterisk /usr/share/astguiclient/ADMIN_cleaning_scripts.pl

This script:

Removes orphaned calls from vicidial_log
Cleans stale sessions from vicidial_users_log
Resets agent statuses to "READY"

Option 3: Manual agent reset via web interface

Log in to /vicidial/admin.php
Navigate to Agent Management
Find the problematic agent
Click Reset Agent
Confirm the action

Cause 3: Asterisk Channel Bridge Misconfiguration

The Dial() application in Asterisk must properly bridge the agent and contact channels. If the dialplan context is wrong, bridging fails.

Diagnosis

Capture a call attempt in the Asterisk CLI:

asterisk -rx "core set debug 3" # Enable verbose debugging
# Now have an agent attempt a call
# Monitor output in /var/log/asterisk/messages
tail -f /var/log/asterisk/messages | grep -i bridge

Look for lines like:

[2024-01-15 14:23:45] ERROR: Bridge failed: Channel not found
[2024-01-15 14:23:46] WARNING: Cannot create bridge for local/6001

Inspect the dialplan routing:

asterisk -rx "dialplan show from-internal"

Fix: Verify extensions-vicidial.conf Dialplan

Check /etc/asterisk/extensions-vicidial.conf for the agent context:

[from-internal]
exten => _6XXX,1,NoOp(=== AGENT EXTENSION ${EXTEN} ===)
 same => n,Set(CHANNEL(hangup_handler_push)=from-internal,hangup_handler,1)
 same => n,Dial(SIP/${EXTEN},120,tT)
 same => n,Hangup()

exten => hangup_handler,1,NoOp(=== HANGUP HANDLER ===)
 same => n,Hangup()

Ensure the Dial() application uses the correct parameters:

tT — Allow DTMF transfer (critical for ViciDial's transfer features)
120 — 120-second timeout before auto-hangup

If this is missing or incorrect, add or update it:

cp /etc/asterisk/extensions-vicidial.conf /etc/asterisk/extensions-vicidial.conf.bak
# Edit the file with your editor
nano /etc/asterisk/extensions-vicidial.conf

Reload the dialplan:

asterisk -rx "dialplan reload"

Verify the change:

asterisk -rx "dialplan show from-internal" | grep -A 5 "_6XXX"

Cause 4: Codec Mismatch Between Agent and Contact

When an agent and contact use incompatible audio codecs, no audio passes between them.

Diagnosis

Check the allowed codecs for an agent extension in sip-vicidial.conf:

asterisk -rx "sip show peer 6001" | grep allow

Output example:

allow=ulaw
allow=gsm
allow=g729

Check what codec was negotiated on a specific call:

asterisk -rx "core show channels verbose" | grep 6001

Look for codec information in the channel details.

Fix: Standardize Codec Configuration

Edit /etc/asterisk/sip-vicidial.conf to ensure all agent extensions have compatible codecs:

[general]
disallow=all
allow=ulaw
allow=gsm
allow=g729
allow=opus

Then in individual agent peers:

[6001]
type=friend
host=dynamic
secret=YourSecretPassword123
context=from-internal
disallow=all
allow=ulaw
allow=gsm
allow=g729

Best practice: Order codecs by priority (most compatible first):

disallow=all
allow=ulaw          ; Standard, uncompressed, most compatible
allow=gsm           ; Good compression, good quality
allow=g729          ; High compression, lower quality but bandwidth-efficient

Reload SIP:

asterisk -rx "sip reload"

Cause 5: Firewall and NAT Issues

Media streams between agent and contact may be blocked by firewalls or misconfigured NAT.

Diagnosis

Check Asterisk RTP port range configuration:

grep -i rtp /etc/asterisk/rtp.conf

Expected output:

rtpstart=10000
rtpend=20000

Verify these ports are open on the firewall:

sudo firewall-cmd --list-ports
# or for ufw:
sudo ufw status

Test connectivity from an agent's IP to the ViciDial server:

# On the agent's machine
sudo iptables -I INPUT -p udp --dport 10000:20000 -j ACCEPT
# or using nc (netcat)
nc -u -l -p 10000 &

Fix: Configure Asterisk for NAT

Edit /etc/asterisk/rtp.conf:

[general]
rtpstart=10000
rtpend=20000
rtpbind=0.0.0.0

Edit /etc/asterisk/sip.conf for NAT handling:

[general]
nat=yes
externip=203.0.113.100
localnet=192.168.1.0/255.255.255.0

externip — Your ViciDial server's public IP (as seen from the internet)
localnet — Your internal network range

Configure agent extension for NAT:

[6001]
type=friend
host=dynamic
nat=yes
insecure=port,invite

Reload SIP:

asterisk -rx "sip reload"

Check RTP binding:

asterisk -rx "rtp show stats"

Configuration Examples

Complete SIP Extension Configuration

Here's a production-ready SIP agent extension configuration:

[6001]
type=friend
host=dynamic
secret=SuperSecurePassword2024
context=from-internal
dtmfmode=rfc2833
disallow=all
allow=ulaw
allow=gsm
allow=g729
nat=yes
insecure=port,invite
qualify=yes
qualifyfreq=60
directmedia=no
videosupport=no
maxcallbitrate=384
session-timers=uac
session-expires=1800
minse=90

Key parameters explained:

dtmfmode=rfc2833 — DTMF sent in-band (required for ViciDial's IVR)
directmedia=no — All media flows through Asterisk (safer for ViciDial)
session-timers=uac — Enables session refresh (prevents audio dropouts)
session-expires=1800 — Refresh every 30 minutes

Complete Dialplan Context for ViciDial

Add this to /etc/asterisk/extensions-vicidial.conf:

[from-internal]
exten => _6XXX,1,NoOp(=== Agent Call from ${CALLERID(num)} ===)
 same => n,Set(CHANNEL(hangup_handler_push)=from-internal,h_agent_hangup,1)
 same => n,Answer()
 same => n,Set(VICIDIAL_AGENT=${EXTEN})
 same => n,Dial(SIP/${EXTEN},120,tT)
 same => n,Hangup()

exten => h_agent_hangup,1,NoOp(=== Agent Hangup Handler ===)
 same => n,Set(CDR(userfield)=${VICIDIAL_AGENT})
 same => n,Hangup()

exten => t,1,Hangup()
exten => T,1,Hangup()

Database Cleanup Script

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

#!/bin/bash

# ViciDial Stale Session Cleanup Script
# Run via cron: */30 * * * * /usr/local/bin/vicidial_cleanup.sh

LOG_FILE="/var/log/vicidial_cleanup.log"
MYSQL_USER="root"
MYSQL_PASS="your_password_here"
DB_NAME="asterisk"

echo "[$(date '+%Y-%m-%d %H:%M:%S')] Starting cleanup..." >> $LOG_FILE

# Remove stale LIVE calls older than 4 hours
mysql -u $MYSQL_USER -p$MYSQL_PASS $DB_NAME << EOF >> $LOG_FILE 2>&1
UPDATE vicidial_log 
SET status = 'ABANDONED' 
WHERE status IN ('INCALL', 'QUEUE', 'LIVE') 
AND call_date < DATE_SUB(NOW(), INTERVAL 4 HOUR);

UPDATE vicidial_users_log 
SET status = 'READY' 
WHERE status IN ('INCALL', 'QUEUE', 'LIVE') 
AND last_update < DATE_SUB(NOW(), INTERVAL 4 HOUR);
EOF

echo "[$(date '+%Y-%m-%d %H:%M:%S')] Cleanup completed." >> $LOG_FILE

Make it executable:

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

Add to crontab to run every 30 minutes:

(crontab -l 2>/dev/null; echo "*/30 * * * * /usr/local/bin/vicidial_cleanup.sh") | crontab -

Advanced Debugging Techniques

Enable Verbose SIP Logging

Temporarily enable SIP debug for a specific agent:

asterisk -rx "sip set debug peer 6001"

This logs all SIP messages for extension 6001. Monitor the logs:

tail -f /var/log/asterisk/messages | grep "6001"

Sample output showing successful registration:

[2024-01-15 14:05:22] VERBOSE[12345] app_dial.c: SIP/6001 to 'SIP/203.0.113.50:5060'
[2024-01-15 14:05:22] DEBUG[12345] chan_sip.c: Reliably Transmitting (NAT):
INVITE sip:203.0.113.50:5060 SIP/2.0
[2024-01-15 14:05:22] VERBOSE[12345] chan_sip.c: Called SIP/203.0.113.50:5060
[2024-01-15 14:05:23] VERBOSE[12345] chan_sip.c: SIP/6001 is ringing
[2024-01-15 14:05:25] VERBOSE[12345] chan_sip.c: SIP/6001 answered SIP/inbound-00a1c2d

Disable debug when finished:

asterisk -rx "sip set debug off"

Check Active Channels and Bridges

View all active channels:

asterisk -rx "core show channels"

Look for your agent extension. Output example:

Channel              State   Application(Data)
SIP/6001-00000a12    6       Dial(SIP/outbound)
SIP/inbound-00000a13 6       Bridged Call(SIP/6001-00000a12)
————————————————————————————————————————————————————————
2 active channels

Get detailed verbose info on a specific channel:

asterisk -rx "core show channel SIP/6001-00000a12"

Inspect ViciDial's Call Log in Real-Time

Check what ViciDial logged for a recent call:

mysql> SELECT vicidial_id, user, lead_id, status, call_date, call_length 
       FROM vicidial_log 
       WHERE user = 'agent001' 
       ORDER BY call_date DESC LIMIT 5;

If a call shows status ABANDONED or NOANSWER but you expected LIVE, the issue occurred at the Asterisk level.

Monitor Asterisk Resource Usage

Check if memory or file descriptors are exhausted:

asterisk -rx "core show uptime"
asterisk -rx "sip show channels"

If channel counts approach your system limit (typically 2000-4000 per server), increase the file descriptor limit:

ulimit -n 65536

Make this permanent in /etc/security/limits.conf:

asterisk soft nofile 65536
asterisk hard nofile 65536

Troubleshooting

Agent Can Log In But Gets "No One Is in Your Session" on Every Call

Step 1: Verify SIP registration:

asterisk -rx "sip show peers" | grep "agent_extension_number"

If UNREACHABLE, have the agent log off and back on.

Step 2: Check the agent's device codec support. Log in to /agc/vicidial.php, initiate a test call, and monitor logs:

tail -f /var/log/asterisk/messages | grep -i "codec\|bridge"

Step 3: Verify dialplan context matches the agent's SIP context:

asterisk -rx "sip show peer AGENT_EXTENSION" | grep context

Calls Connect But One-Way Audio

Possible causes:

Asymmetric firewall rules
Incorrect directmedia setting

Fix:

Edit /etc/asterisk/sip-vicidial.conf:

[general]
directmedia=no

This forces all media through Asterisk, bypassing direct media negotiation which often fails with NAT.

Reload:

asterisk -rx "sip reload"

Stale Database Entries Blocking New Sessions

Run the cleanup script:

/usr/share/astguiclient/ADMIN_cleaning_scripts.pl

Or manually clean via SQL:

UPDATE vicidial_users_log 
SET status = 'READY', calls_today = 0 
WHERE user_id = 'agent001';

High Latency or Occasional Dropouts

Check RTP stats:

asterisk -rx "rtp show stats"

If packet loss is high (>2%), verify network quality and firewall rules. Enable RTP keepalive:

Edit /etc/asterisk/rtp.conf:

[general]
dtmf_payload_type=101
rtpstart=10000
rtpend=20000
rtcpinterval=5000

Restart Asterisk:

sudo systemctl restart asterisk

Summary

The "No One Is in Your Session" error in ViciDial stems from channel bridge failures caused by:

SIP registration issues — Agents not properly registered to Asterisk
Database desynchronization — Stale session records blocking new calls
Dialplan misconfiguration — Incorrect context or bridge parameters
Codec mismatches — Agent and contact using incompatible audio codecs
Firewall/NAT problems — Media path blocked or misconfigured

Immediate fixes:

Force agent re-registration via web interface or asterisk -rx "sip reload"
Clean stale database records using /usr/share/astguiclient/ADMIN_cleaning_scripts.pl
Verify SIP configuration has nat=yes and directmedia=no for remote agents
Ensure dialplan uses Dial(SIP/${EXTEN},120,tT) with tT flags

Prevention:

Schedule regular cleanup scripts via cron
Monitor SIP peer status using asterisk -rx "sip show peers"
Test codec negotiation after configuration changes
Maintain firewall rules allowing RTP ports 10000-20000

Advanced debugging:

Enable SIP debug: asterisk -rx "sip set debug peer EXTENSION"
Check channel state: asterisk -rx "core show channels"
Query database for call status: SELECT * FROM vicidial_log WHERE user = 'agentID'
Monitor logs in real-time: tail -f /var/log/asterisk/messages

With these techniques, you'll resolve "No One Is in Your Session" errors quickly and reduce future occurrences through proactive monitoring and maintenance.

ViciDial Login Incorrect Error — Fix Agent & Admin Auth Failures

Moisi Trungu — Thu, 23 Jul 2026 03:30:04 +0000

ViciDial Login Incorrect Error — Fix Agent & Admin Auth Failures

Learn how to diagnose and resolve "login incorrect" authentication failures in ViciDial for both agents and administrators, including database verification, configuration checks, and real-world debugging techniques.

Prerequisites

Before troubleshooting ViciDial login errors, ensure you have:

Root or sudo access to your ViciDial server
SSH access to the production system
Database credentials for the asterisk database
Basic understanding of MySQL/MariaDB queries
Familiarity with Linux file permissions and Apache/PHP logs
A backup of your ViciDial configuration before making changes
Knowledge of your ViciDial version (check /usr/share/astguiclient/VERSION)

Verify your environment:

mysql -u root -p -e "SELECT VERSION();"
asterisk -rx "core show version"
ps aux | grep -E "apache|mysql|asterisk" | grep -v grep

Understanding ViciDial Authentication Architecture

ViciDial uses a dual-layer authentication system:

Agent login — Handled by /agc/vicidial.php, authenticates against the vicidial_users table with MD5 password hashing
Admin login — Handled by /vicidial/admin.php, authenticates against the vicidial_users table with role-based access control (RBAC)

Both systems validate credentials against the same user database but enforce different permission levels. The authentication flow checks:

User existence in vicidial_users
Password hash match (MD5 in most installations, though some use SHA-256)
User status (active vs. inactive)
User group permissions
IP whitelist rules (if configured)

Common Causes of "Login Incorrect" Errors

Password Hash Mismatches

The most frequent cause is an incorrect password hash stored in the database. ViciDial's default password hashing uses MD5, but some installations have been upgraded to use SHA-256 or bcrypt.

Database Sync Issues

In clustered ViciDial setups, database replication lag can cause authentication failures on secondary nodes while working on the primary.

Corrupted User Records

Missing or malformed entries in the vicidial_users table prevent proper authentication.

PHP Session Configuration

Incorrect PHP session settings, disabled extensions, or permission issues on session storage directories cause failures.

IP Whitelist Blocking

ViciDial can restrict logins by IP address. An overly restrictive whitelist blocks legitimate agents.

Asterisk User Correlation Issues

The agent user must exist in both vicidial_users and the Asterisk sip.conf or extensions.conf for full functionality.

Section 1: Verify User Existence in the Database

The first diagnostic step is confirming the user exists and is properly configured.

Query the vicidial_users Table

Connect to the asterisk database and retrieve the user record:

mysql -u root -p asterisk

SELECT user_id, user_name, user_pass, user_email, full_name, user_level, 
       user_group, active, user_phone FROM vicidial_users 
WHERE user_name = 'agentname' LIMIT 1\G

Expected output should show the user with active = 'Y'. Note the exact password hash value — you'll use this for validation.

Verify User Status and Permissions

SELECT user_id, user_name, user_level, user_group, active, 
       closer_login_allowed, lead_search_enabled 
FROM vicidial_users 
WHERE user_name = 'agentname'\G

Ensure:

active = 'Y' (not 'N' or NULL)
user_level is appropriate (1-9, where 1 is admin, 9 is agent-only)
user_group exists and is not NULL
closer_login_allowed = 'Y' for agents attempting to log in

Check for Duplicate Users

Duplicate usernames cause authentication confusion:

SELECT user_name, COUNT(*) as count 
FROM vicidial_users 
GROUP BY user_name 
HAVING count > 1;

If duplicates exist, delete the obsolete record:

DELETE FROM vicidial_users 
WHERE user_id = (SELECT MIN(user_id) FROM (SELECT user_id FROM vicidial_users WHERE user_name = 'agentname') AS t);

Section 2: Password Hash Validation and Repair

Identify the Password Hashing Algorithm

Check the ViciDial configuration to determine which algorithm is in use:

grep -r "password" /etc/asterisk/vicidial.conf | head -20
grep -r "MD5\|SHA" /usr/share/astguiclient/ | head -10

Look at the actual login script to identify the algorithm:

grep -i "md5\|sha\|hash" /var/www/html/agc/vicidial.php | head -20

Generate an MD5 Hash for Password Reset

If you need to reset an agent's password to a known value, generate the MD5 hash:

echo -n "newpassword123" | md5sum
# Output: 2e99758ae89ac59c117d7aab61d41f18  -

The hash (without the trailing dash) goes into the database.

Update the User Password

UPDATE vicidial_users 
SET user_pass = MD5('newpassword123') 
WHERE user_name = 'agentname';

Verify the update:

SELECT user_name, user_pass FROM vicidial_users WHERE user_name = 'agentname';

Test Password Reset via CLI

Generate a test hash and verify it matches:

php -r "echo md5('testpass'); echo PHP_EOL;"
# Output: 5a105e8b9d40e1329780d62ea2265d8a

Handle SHA-256 Installations

Some modern ViciDial installations use SHA-256. Check for this in the PHP login code:

grep -n "hash\|sha" /var/www/html/agc/vicidial.php | grep -i sha

If SHA-256 is in use, generate the hash:

echo -n "newpassword123" | sha256sum
# Output: 9f86d081884c7d6582ef8f3f00d7e1d7  -

Then update the database:

UPDATE vicidial_users 
SET user_pass = SHA2('newpassword123', 256) 
WHERE user_name = 'agentname';

Section 3: Diagnose Login Script Failures

Enable PHP Error Logging

Edit the PHP configuration to log errors:

sudo nano /etc/php.ini

Ensure these settings are configured:

error_reporting = E_ALL
display_errors = Off
log_errors = On
error_log = /var/log/php-errors.log

Create the log file if it doesn't exist:

sudo touch /var/log/php-errors.log
sudo chown apache:apache /var/log/php-errors.log
sudo chmod 644 /var/log/php-errors.log

Restart Apache:

sudo systemctl restart apache2
# or for CentOS/RHEL:
sudo systemctl restart httpd

Monitor Login Attempts

Tail the Apache error log while attempting login:

sudo tail -f /var/log/apache2/error.log

In another terminal, attempt a login and observe the error output.

Check PHP Session Directory Permissions

ViciDial stores PHP sessions. Verify the directory has correct permissions:

ls -ld /var/lib/php/sessions
# Should output: drwxrwxrwt ... /var/lib/php/sessions

If permissions are wrong:

sudo chmod 1777 /var/lib/php/sessions

Verify MySQL Connectivity from PHP

Create a test script to verify the PHP-to-MySQL connection:

sudo nano /var/www/html/test_db.php

<?php
$db_user = 'root';
$db_pass = 'yourpassword';
$db_host = 'localhost';
$db_name = 'asterisk';

$conn = new mysqli($db_host, $db_user, $db_pass, $db_name);

if ($conn->connect_error) {
    die("Connection failed: " . $conn->connect_error);
}

$result = $conn->query("SELECT user_name, user_pass FROM vicidial_users LIMIT 1");

if ($result->num_rows > 0) {
    while ($row = $result->fetch_assoc()) {
        echo "User: " . $row["user_name"] . " | Pass Hash: " . $row["user_pass"] . "\n";
    }
} else {
    echo "No users found\n";
}

$conn->close();
?>

Access it via browser: http://your-server/test_db.php

Then remove the test file:

sudo rm /var/www/html/test_db.php

Section 4: Check IP Whitelist Restrictions

ViciDial can restrict logins by source IP address. Verify this isn't blocking legitimate agents.

Query IP Restrictions

SELECT vicidial_id, user_id, user_name, ip_address, active 
FROM vicidial_users 
WHERE user_name = 'agentname'\G

Check if there's an IP restriction table:

SHOW TABLES LIKE '%ip%';
SHOW TABLES LIKE '%whitelist%';
SHOW TABLES LIKE '%access%';

Locate IP Whitelist Configuration

grep -r "ip_address\|whitelist" /usr/share/astguiclient/ | grep -v ".git"

Review the Login PHP Script for IP Checks

grep -n "ip\|whitelist\|access" /var/www/html/agc/vicidial.php | head -30

If IP restrictions are enforced, identify the agent's actual IP address from Apache logs:

sudo tail -50 /var/log/apache2/access.log | grep agentname

Look for the IP address in the columns before the timestamp.

Disable or Update IP Restrictions

If the IP whitelist is too restrictive, you can disable it temporarily for testing:

UPDATE vicidial_users 
SET ip_address = '0.0.0.0/0' 
WHERE user_name = 'agentname';

This allows login from any IP. For production, use the agent's actual subnet:

UPDATE vicidial_users 
SET ip_address = '192.168.1.0/24' 
WHERE user_name = 'agentname';

Section 5: Verify Asterisk User Configuration

Agents must exist in both the ViciDial database and the Asterisk SIP configuration.

Check sip-vicidial.conf

Examine the Asterisk SIP configuration:

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

Expected output:

[agentname](vicidial_agent)
type=friend
username=agentname
secret=sippassword

Verify extensions.conf

The agent must be defined in extensions:

grep -B 2 -A 10 "exten => agentname" /etc/asterisk/extensions-vicidial.conf

Reload Asterisk SIP Configuration

If you add or modify a user, reload the SIP module:

sudo asterisk -rx "sip reload"

Verify the user loaded correctly:

sudo asterisk -rx "sip show peer agentname"

Expected output shows the peer details including IP, port, and registration status.

Section 6: Troubleshoot Admin Login Issues

Admin login uses the same database but enforces additional role checks. Address these specific issues:

Verify Admin User Level

Admin users must have user_level between 1-5 (where 1 is superadmin):

SELECT user_name, user_level, user_group, active 
FROM vicidial_users 
WHERE user_level <= 5 
AND user_name = 'adminname'\G

If the user_level is 6 or higher, they're classified as an agent, not admin.

Update User to Admin Level

UPDATE vicidial_users 
SET user_level = 1 
WHERE user_name = 'adminname';

Check Admin-Specific Permissions

SELECT user_name, admin_login_allowed, admin_phonebook, 
       admin_reports, admin_settings, admin_users 
FROM vicidial_users 
WHERE user_name = 'adminname'\G

Ensure admin privilege columns are set to 'Y':

UPDATE vicidial_users 
SET admin_login_allowed = 'Y', 
    admin_reports = 'Y', 
    admin_settings = 'Y', 
    admin_users = 'Y' 
WHERE user_name = 'adminname';

Clear Admin Session Cache

Some ViciDial versions cache admin sessions. Clear this:

sudo rm -rf /tmp/vicidial_*
sudo rm -rf /var/lib/php/sessions/vicidial_*

Then restart Apache:

sudo systemctl restart apache2

Section 7: Database Replication and Sync Issues

In clustered ViciDial deployments, database replication lag can cause authentication failures.

Check Replication Status

On the database slave:

mysql -u root -p -e "SHOW SLAVE STATUS\G"

Look for:

Slave_IO_Running: Yes
Slave_SQL_Running: Yes
Seconds_Behind_Master: 0 (or a small number)

If Seconds_Behind_Master is high, replication is lagging.

Verify Master-Slave Consistency

-- On master:
SHOW MASTER STATUS;

-- On slave:
SHOW SLAVE STATUS;

Compare the File and Position columns. They should match between master and slave after replication catches up.

Force User Sync

If replication is stuck, manually sync the user record:

# Export from master
mysqldump -u root -p asterisk vicidial_users --where="user_name='agentname'" > /tmp/user_export.sql

# Import on slave
mysql -u root -p asterisk < /tmp/user_export.sql

Restart Replication

If replication is broken:

# On slave, as root:
mysql -u root -p -e "STOP SLAVE;"
mysql -u root -p -e "SET GLOBAL SQL_SLAVE_SKIP_COUNTER = 1;"
mysql -u root -p -e "START SLAVE;"
mysql -u root -p -e "SHOW SLAVE STATUS\G"

Section 8: Check Web Server and PHP Configuration

Verify Apache is Serving ViciDial Correctly

Test the web paths:

curl -I http://localhost/agc/vicidial.php
curl -I http://localhost/vicidial/admin.php

Both should return HTTP 200.

Check PHP Modules

Ensure required PHP modules are loaded:

php -m | grep -E "mysql|mysqli|json|session|zlib"

Missing modules will prevent database access. Install missing extensions:

# Ubuntu/Debian:
sudo apt-get install php-mysql php-json php-zlib

# CentOS/RHEL:
sudo yum install php-mysql php-json php-zlib

Verify ViciDial File Permissions

The web server must read ViciDial files:

ls -la /var/www/html/agc/vicidial.php
# Should show: -rw-r--r-- apache:apache

Fix permissions if needed:

sudo chown -R apache:apache /var/www/html/agc
sudo chown -R apache:apache /var/www/html/vicidial
sudo chmod -R 755 /var/www/html/agc
sudo chmod -R 755 /var/www/html/vicidial

Check Apache Configuration for ViciDial

grep -r "ViciDial\|vicidial" /etc/apache2/sites-enabled/

Ensure the VirtualHost or Directory block includes:

<Directory /var/www/html/agc>
    Options FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

<Directory /var/www/html/vicidial>
    Options FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

Section 9: Audit Login Attempt Logs

Find Login Audit Tables

ViciDial logs authentication attempts:

SHOW TABLES LIKE '%log%';
SELECT * FROM vicidial_log LIMIT 5\G

Query recent login failures:

SELECT call_date, user_id, user_name, phone_number, lead_id, status, notes 
FROM vicidial_log 
WHERE user_name = 'agentname' 
AND call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR) 
ORDER BY call_date DESC LIMIT 20;

Check Asterisk Logs for Authentication Errors

sudo tail -100 /var/log/asterisk/messages | grep -i "auth\|login\|fail\|agentname"

Look for patterns like:

"Authentication failed"
"Invalid extension"
"Connection refused"

Monitor Asterisk in Real-Time

Open Asterisk CLI and monitor events:

sudo asterisk -r

Inside the Asterisk console:

*CLI> sip set debug on
*CLI> core set verbose 3

Attempt login and watch for SIP errors. Exit with:

*CLI> exit

Section 10: Database Repair and Optimization

Repair Corrupted User Records

Run a database check:

CHECK TABLE vicidial_users;
REPAIR TABLE vicidial_users;

If corruption is found, rebuild the table:

ALTER TABLE vicidial_users ENGINE=InnoDB;

Verify Data Integrity

Ensure no NULL values in critical fields:

SELECT * FROM vicidial_users 
WHERE user_name IS NULL 
OR user_pass IS NULL 
OR user_level IS NULL;

If results are found, delete those rows:

DELETE FROM vicidial_users 
WHERE user_name IS NULL 
OR user_pass IS NULL 
OR user_level IS NULL;

Optimize the Table

After repairs, optimize:

OPTIMIZE TABLE vicidial_users;

Troubleshooting

Agent Login Works on One Server but Not Another

Symptom: Agent successfully logs in via Server A but gets "login incorrect" on Server B.

Diagnosis:

Database replication lag on Server B
Different PHP configuration between servers
Mismatched password hashing algorithms

Solution:

# Verify database sync on Server B
mysql -u root -p -e "SELECT COUNT(*) FROM vicidial_users;"

# Compare with Server A
# If different, force sync:
mysqldump -u root -p asterisk vicidial_users | mysql -u root -p -h serverB asterisk

"Login Incorrect" Despite Correct Password

Symptom: User enters correct password but receives "login incorrect".

Diagnosis:

Password hash algorithm mismatch
Corrupted user record in database
PHP session cache corruption

Solution:

# Reset password with known hash
echo -n "testpassword" | md5sum
# Use the output hash:
mysql -u root -p asterisk -e "UPDATE vicidial_users SET user_pass=MD5('testpassword') WHERE user_name='agentname';"

# Clear session cache
sudo rm -rf /var/lib/php/sessions/*
sudo systemctl restart apache2

Admin Login Fails but Agent Login Works

Symptom: Admin cannot log in to /vicidial/admin.php but agents use /agc/vicidial.php successfully.

Diagnosis:

Admin user lacks proper role/permissions
Admin login script specific error
Admin IP whitelist is too restrictive

Solution:

UPDATE vicidial_users 
SET user_level = 1, 
    admin_login_allowed = 'Y', 
    ip_address = '0.0.0.0/0' 
WHERE user_name = 'adminname';

Then test:

# Check for admin-specific errors
sudo tail -50 /var/log/apache2/error.log | grep -i admin

Login Works from Office Network but Fails from Home

Symptom: Agent logs in successfully from office but gets "login incorrect" from home IP.

Diagnosis:

IP whitelist is blocking home IP address

Solution:

# Find agent's home IP from browser
# Add it to the whitelist:
mysql -u root -p asterisk -e "UPDATE vicidial_users SET ip_address='192.168.0.0/16,203.0.113.100' WHERE user_name='agentname';"

# Or disable IP whitelist for testing:
mysql -u root -p asterisk -e "UPDATE vicidial_users SET ip_address='' WHERE user_name='agentname';"

Password Hash Length Mismatch

Symptom: Password hash in database is wrong length (e.g., 32 chars for SHA-256).

Diagnosis:

Password was hashed with different algorithm than what login expects

Solution:

# Check current hash length and algorithm
mysql -u root -p asterisk -e "SELECT user_name, LENGTH(user_pass) FROM vicidial_users LIMIT 5;"

# If MD5 (32 chars), regenerate:
mysql -u root -p asterisk -e "UPDATE vicidial_users SET user_pass=MD5('newpass') WHERE user_name='agentname';"

# If SHA-256 (64 chars):
mysql -u root -p asterisk -e "UPDATE vicidial_users SET user_pass=SHA2('newpass', 256) WHERE user_name='agentname';"

Multiple Failed Login Attempts Lock Account

Symptom: After several failed logins, account becomes locked.

Diagnosis:

ViciDial has login attempt limiting enabled
Account lockout table stores failed attempts

Solution:

-- Check for lockout table
SHOW TABLES LIKE '%lockout%';
SHOW TABLES LIKE '%attempt%';

-- Query failed attempts
SELECT * FROM vicidial_user_lock WHERE user_name = 'agentname';

-- Clear lockout
DELETE FROM vicidial_user_lock WHERE user_name = 'agentname';

-- Or reset via ViciDial config (check settings):
grep -i "lockout\|max_attempt" /etc/asterisk/vicidial.conf

Case Sensitivity in Usernames

Symptom: "agentname" and "AgentName" are treated as different users.

Diagnosis:

Database has case-sensitive username collation

Solution:

-- Check collation
SHOW CREATE TABLE vicidial_users\G

-- If case-sensitive, standardize to lowercase:
UPDATE vicidial_users SET user_name = LOWER(user_name);

-- Change collation to case-insensitive
ALTER TABLE vicidial_users MODIFY user_name VARCHAR(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

Summary

ViciDial "login incorrect" errors stem from misaligned database records, password hash issues, or web server configuration problems. Systematically verify:

User existence — Confirm the user exists in vicidial_users with active = 'Y'
Password hash — Verify the hash matches the authentication algorithm (MD5 or SHA-256)
User permissions — Ensure user_level, user_group, and role permissions are correct
Database sync — Check that replication is current in clustered deployments
IP restrictions — Confirm the agent's IP isn't blocked by whitelist rules
Asterisk correlation — Verify the user exists in SIP configuration for agent logins
Web server — Validate PHP modules, file permissions, and Apache configuration
Session handling — Ensure PHP session directory permissions are correct

Use the database queries and CLI commands provided to diagnose issues quickly. When in doubt, reset the password with a known hash, clear the PHP session cache, and restart Apache. For production systems, always test changes on a non-critical agent account first, maintain database backups, and log all authentication modifications for audit compliance.

Securing ViciDial Admin Interface — HTTPS, IP Whitelist, 2FA

Moisi Trungu — Wed, 22 Jul 2026 03:30:03 +0000

Securing ViciDial Admin Interface — HTTPS, IP Whitelist, 2FA

Learn how to lock down your ViciDial admin panel with production-grade security: enforce HTTPS, restrict access by IP, implement two-factor authentication, and harden the database layer.

Prerequisites

Before implementing these security measures, ensure you have:

A running ViciDial installation (v2.14+ recommended, though applicable to v2.9+)
Root or sudo access to your ViciDial server
An SSL/TLS certificate (self-signed or from a CA like Let's Encrypt)
Asterisk 11+ installed and running
Apache or Nginx web server (this guide covers Apache primarily)
MySQL/MariaDB database access with root credentials
Basic Linux command-line competency
Backup of your ViciDial database before making changes
A test account to verify 2FA without locking out your main account

Verify your current setup:

mysql -V
apache2 -v
asterisk -V

Why Securing the Admin Interface Matters

The ViciDial admin interface (/vicidial/admin.php) controls:

User and agent account creation/deletion
Campaign configuration and call routing
Pause codes, dispositions, and call outcomes
Database access and backups
System logs and call recordings

Unauthorized access to the admin panel can result in:

Malicious campaign deployment
Call data theft and GDPR violations
Agent credential compromise
Call recording exfiltration
Service disruption and DDoS via call flooding

This tutorial covers three complementary layers of defense.

Section 1: Enforce HTTPS and Disable HTTP

1.1 Obtain an SSL/TLS Certificate

If you don't have a certificate, obtain one using Let's Encrypt (free):

apt-get update
apt-get install certbot python3-certbot-apache -y
certbot certonly --standalone -d admin.yourdomain.com -d vicidial.yourdomain.com

Follow the prompts. Certificates are saved to /etc/letsencrypt/live/admin.yourdomain.com/.

For self-signed certificates (test environments only):

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/ssl/private/vicidial-self.key \
  -out /etc/ssl/certs/vicidial-self.crt \
  -subj "/C=US/ST=State/L=City/O=Company/CN=vicidial.local"

1.2 Configure Apache for HTTPS

Enable the SSL module:

a2enmod ssl
a2enmod rewrite
systemctl restart apache2

Locate your ViciDial VirtualHost configuration:

find /etc/apache2 -name "*vicidial*" -o -name "*.conf" | grep -i vicidial

If none exists, create one at /etc/apache2/sites-available/vicidial-ssl.conf:

<VirtualHost *:80>
    ServerName admin.yourdomain.com
    DocumentRoot /var/www/html

    # Force all HTTP traffic to HTTPS
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</VirtualHost>

<VirtualHost *:443>
    ServerName admin.yourdomain.com
    DocumentRoot /var/www/html

    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/admin.yourdomain.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/admin.yourdomain.com/privkey.pem

    # Modern SSL/TLS configuration
    SSLProtocol TLSv1.2 TLSv1.3
    SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
    SSLHonorCipherOrder on
    SSLCompression off

    # HSTS - Force HTTPS for 1 year
    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"

    # Disable server signature exposure
    Header always unset "Server"
    Header always unset "X-Powered-By"
    ServerTokens Prod

    <Directory /var/www/html/vicidial>
        DirectoryIndex index.html admin.php
        AllowOverride All
        Require all granted

        # Disable directory listing
        Options -Indexes
    </Directory>

    # Proxy to Asterisk AGI if needed
    ProxyPreserveHost On
    <Location /agi-bin/>
        ProxyPass http://127.0.0.1:8088/agi-bin/
        ProxyPassReverse http://127.0.0.1:8088/agi-bin/
    </Location>

    ErrorLog ${APACHE_LOG_DIR}/vicidial-error.log
    CustomLog ${APACHE_LOG_DIR}/vicidial-access.log combined
</VirtualHost>

Enable the site:

a2ensite vicidial-ssl
apache2ctl configtest
systemctl restart apache2

Verify HTTPS is working:

curl -I https://admin.yourdomain.com 2>/dev/null | head -5

You should see 200 OK and HTTP/1.1 or HTTP/2.0.

1.3 Disable Weak Protocols and Ciphers

Verify your SSL configuration with testssl.sh or similar:

apt-get install testssl.sh
testssl.sh https://admin.yourdomain.com 2>/dev/null | grep -i "protocol\|cipher"

Remove any references to SSLv3, TLSv1.0, or TLSv1.1 from /etc/apache2/mods-available/ssl.conf:

SSLProtocol -all +TLSv1.2 +TLSv1.3
SSLCipherSuite 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256'

Restart Apache:

systemctl restart apache2

Section 2: IP Whitelist for Admin Access

2.1 Implement IP Filtering at Apache Level

Edit /etc/apache2/sites-available/vicidial-ssl.conf to restrict access to /vicidial/admin.php:

<VirtualHost *:443>
    ServerName admin.yourdomain.com
    # ... SSL config as above ...

    <Location /vicidial/admin.php>
        # Whitelist office IPs
        Require ip 203.0.113.10
        Require ip 203.0.113.11
        Require ip 198.51.100.0/24

        # Log denied access attempts
        SetEnvIf Request_URI "/vicidial/admin.php" admin_access
    </Location>

    <Directory /var/www/html/vicidial>
        # ... other directives ...
    </Directory>
</VirtualHost>

# Log admin access to separate file
CustomLog ${APACHE_LOG_DIR}/vicidial-admin-access.log combined env=admin_access

Test the configuration:

apache2ctl configtest
systemctl restart apache2

Verify from an allowed IP:

curl -k https://admin.yourdomain.com/vicidial/admin.php 2>&1 | head -10

From a blocked IP, you should receive a 403 Forbidden error.

2.2 Create a Dynamic IP Whitelist File

For environments where admin IPs change frequently, use an include file:

Create /etc/apache2/vicidial-whitelist.conf:

<If "%{REQUEST_URI} =~ m#/vicidial/admin\.php#">
    Require ip 203.0.113.10 203.0.113.11
    Require ip 198.51.100.0/24
    Require ip 192.168.1.0/24
</If>

Include it in your VirtualHost:

<VirtualHost *:443>
    # ... SSL config ...

    Include /etc/apache2/vicidial-whitelist.conf
</VirtualHost>

To add IPs dynamically without restarting Apache:

echo "    203.0.113.99" >> /etc/apache2/vicidial-whitelist.conf
systemctl reload apache2

2.3 Add ModSecurity Rules (Optional but Recommended)

Install ModSecurity:

apt-get install libapache2-mod-security2 modsecurity-crs -y
a2enmod security2

Create /etc/apache2/conf-available/vicidial-modsecurity.conf:

SecRuleEngine On
SecRequestBodyAccess On
SecRequestBodyLimit 16777216
SecRequestBodyNoFiles Off

# Log all requests to admin interface
SecRule REQUEST_URI "@beginsWith /vicidial/admin.php" \
    "id:1001,phase:1,log,logdata:%{REMOTE_ADDR},pass"

# Block common injection attacks
SecRule ARGS "@rx (?:union|select|insert|update|delete|drop)" \
    "id:1002,phase:2,deny,status:403,msg:'SQL Injection attempt'"

SecRule ARGS "@rx (?:\.\./|\.\.\\)" \
    "id:1003,phase:2,deny,status:403,msg:'Path traversal attempt'"

Enable the module:

a2enconf vicidial-modsecurity
systemctl restart apache2

Monitor ModSecurity logs:

tail -f /var/log/apache2/modsec_audit.log | grep -i vicidial

Section 3: Implement Two-Factor Authentication (2FA)

3.1 Choose a 2FA Method

ViciDial does not include native 2FA in the admin interface. We'll implement 2FA by:

Database-level tracking of OTP secrets and verified states
PHP wrapper that intercepts login attempts
TOTP generation using Google Authenticator or Authy

3.2 Prepare the Database

Create a new table to store TOTP secrets and recovery codes:

USE asterisk;

CREATE TABLE IF NOT EXISTS `vicidial_admin_2fa` (
    `user_id` INT NOT NULL,
    `username` VARCHAR(20) NOT NULL,
    `totp_secret` VARCHAR(32),
    `totp_enabled` ENUM('Y','N') DEFAULT 'N',
    `backup_codes` TEXT,
    `created_date` DATETIME DEFAULT CURRENT_TIMESTAMP,
    `last_verified` DATETIME,
    PRIMARY KEY (`user_id`),
    FOREIGN KEY (`user_id`) REFERENCES `vicidial_users`(`user_id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- Add 2FA attempt logging
CREATE TABLE IF NOT EXISTS `vicidial_2fa_audit` (
    `id` INT AUTO_INCREMENT PRIMARY KEY,
    `username` VARCHAR(20) NOT NULL,
    `attempt_type` ENUM('LOGIN','OTP_VERIFY','BACKUP_CODE') NOT NULL,
    `result` ENUM('SUCCESS','FAILURE','INVALID_USER') NOT NULL,
    `remote_ip` VARCHAR(45),
    `attempt_time` DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX (`username`),
    INDEX (`attempt_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Verify table creation:

mysql -u root -p asterisk -e "DESCRIBE vicidial_admin_2fa;"

3.3 Install PHP TOTP Library

Navigate to the ViciDial web root:

cd /var/www/html/vicidial

Install PHPGangsta_GoogleAuthenticator (TOTP implementation):

apt-get install php-composer -y
composer require phpgangsta/googleauthenticator 1.0.*

Or download manually:

curl -L -o /var/www/html/vicidial/GoogleAuthenticator.php \
  https://raw.githubusercontent.com/PHPGangsta/GoogleAuthenticator/master/PHPGangsta/GoogleAuthenticator.php

Verify installation:

ls -la /var/www/html/vicidial/GoogleAuthenticator.php

3.4 Create 2FA Verification Script

Create /var/www/html/vicidial/admin_2fa_login.php:

<?php
/**
 * ViciDial Admin 2FA Login Handler
 * Validates TOTP before granting access to admin.php
 */

session_start();
error_reporting(0);

// Database configuration
$db_host = 'localhost';
$db_user = 'root';
$db_pass = 'YOUR_DB_PASSWORD';
$db_name = 'asterisk';

$mysqli = new mysqli($db_host, $db_user, $db_pass, $db_name);
if ($mysqli->connect_error) {
    die('Database connection failed: ' . $mysqli->connect_error);
}

// Include TOTP library
require_once 'GoogleAuthenticator.php';
$ga = new PHPGangsta_GoogleAuthenticator();

$username = '';
$error_msg = '';
$info_msg = '';

// Handle OTP verification
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    if (isset($_POST['action']) && $_POST['action'] === 'verify_otp') {

        $username = sanitizeInput($_POST['username'] ?? '');
        $otp_code = sanitizeInput($_POST['otp_code'] ?? '');
        $remote_ip = $_SERVER['REMOTE_ADDR'];

        // Validate inputs
        if (empty($username) || empty($otp_code)) {
            $error_msg = 'Username and OTP code required';
            logAuditEvent($mysqli, $username, 'OTP_VERIFY', 'FAILURE', $remote_ip, 'Empty fields');
        } else {
            // Fetch TOTP secret from database
            $stmt = $mysqli->prepare("
                SELECT totp_secret FROM vicidial_admin_2fa 
                WHERE username = ? AND totp_enabled = 'Y'
            ");
            $stmt->bind_param('s', $username);
            $stmt->execute();
            $result = $stmt->get_result();

            if ($result->num_rows === 0) {
                $error_msg = 'User not found or 2FA not enabled';
                logAuditEvent($mysqli, $username, 'OTP_VERIFY', 'INVALID_USER', $remote_ip);
            } else {
                $row = $result->fetch_assoc();
                $totp_secret = $row['totp_secret'];

                // Verify the OTP (allows 1 minute window for clock drift)
                $checkResult = $ga->verifyCode($totp_secret, $otp_code, 1);

                if ($checkResult) {
                    // OTP valid - allow access
                    $_SESSION['2fa_verified'] = true;
                    $_SESSION['admin_user'] = $username;
                    $_SESSION['2fa_verify_time'] = time();

                    // Update last verified timestamp
                    $stmt = $mysqli->prepare("
                        UPDATE vicidial_admin_2fa 
                        SET last_verified = NOW() 
                        WHERE username = ?
                    ");
                    $stmt->bind_param('s', $username);
                    $stmt->execute();

                    logAuditEvent($mysqli, $username, 'OTP_VERIFY', 'SUCCESS', $remote_ip);

                    // Redirect to admin.php
                    header('Location: admin.php');
                    exit;
                } else {
                    $error_msg = 'Invalid OTP code. Please try again.';
                    logAuditEvent($mysqli, $username, 'OTP_VERIFY', 'FAILURE', $remote_ip, 'Invalid OTP');
                }
            }
            $stmt->close();
        }
    }
}

function sanitizeInput($input) {
    return htmlspecialchars(trim($input), ENT_QUOTES, 'UTF-8');
}

function logAuditEvent($mysqli, $username, $type, $result, $ip, $notes = '') {
    $stmt = $mysqli->prepare("
        INSERT INTO vicidial_2fa_audit (username, attempt_type, result, remote_ip) 
        VALUES (?, ?, ?, ?)
    ");
    $stmt->bind_param('ssss', $username, $type, $result, $ip);
    $stmt->execute();
    $stmt->close();
}

?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>ViciDial Admin - Two-Factor Authentication</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            display: flex;
            justify-content: center;
            align-items: center;
            height: 100vh;
            margin: 0;
        }
        .login-container {
            background: white;
            padding: 40px;
            border-radius: 8px;
            box-shadow: 0 10px 25px rgba(0,0,0,0.2);
            width: 100%;
            max-width: 400px;
        }
        .login-container h1 {
            text-align: center;
            color: #333;
            margin-bottom: 30px;
        }
        .form-group {
            margin-bottom: 20px;
        }
        label {
            display: block;
            margin-bottom: 5px;
            color: #555;
            font-weight: bold;
        }
        input[type="text"],
        input[type="password"] {
            width: 100%;
            padding: 10px;
            border: 1px solid #ddd;
            border-radius: 4px;
            box-sizing: border-box;
            font-size: 16px;
        }
        input[type="text"]:focus,
        input[type="password"]:focus {
            outline: none;
            border-color: #667eea;
            box-shadow: 0 0 5px rgba(102,126,234,0.3);
        }
        button {
            width: 100%;
            padding: 12px;
            background: #667eea;
            color: white;
            border: none;
            border-radius: 4px;
            font-size: 16px;
            font-weight: bold;
            cursor: pointer;
            transition: background 0.3s;
        }
        button:hover {
            background: #764ba2;
        }
        .error {
            background: #fee;
            color: #c33;
            padding: 12px;
            border-radius: 4px;
            margin-bottom: 20px;
            border-left: 4px solid #c33;
        }
        .info {
            background: #e3f2fd;
            color: #1976d2;
            padding: 12px;
            border-radius: 4px;
            margin-bottom: 20px;
            border-left: 4px solid #1976d2;
            font-size: 14px;
        }
    </style>
</head>
<body>
    <div class="login-container">
        <h1>🔐 ViciDial Admin</h1>

        <?php if ($error_msg): ?>
            <div class="error"><?php echo $error_msg; ?></div>
        <?php endif; ?>

        <?php if ($info_msg): ?>
            <div class="info"><?php echo $info_msg; ?></div>
        <?php endif; ?>

        <form method="POST">
            <input type="hidden" name="action" value="verify_otp">

            <div class="form-group">
                <label for="username">Username</label>
                <input type="text" id="username" name="username" placeholder="Admin username" required autofocus>
            </div>

            <div class="form-group">
                <label for="otp_code">Authenticator Code</label>
                <input type="text" id="otp_code" name="otp_code" placeholder="000000" maxlength="6" pattern="\d{6}" required>
                <div class="info" style="margin-top: 8px; margin-bottom: 0;">
                    Enter the 6-digit code from your authenticator app (Google Authenticator, Authy, etc.)
                </div>
            </div>

            <button type="submit">Verify & Access Admin Panel</button>
        </form>
    </div>
</body>
</html>

Set proper permissions:

chown www-data:www-data /var/www/html/vicidial/admin_2fa_login.php
chmod 640 /var/www/html/vicidial/admin_2fa_login.php

3.5 Wrap the Existing admin.php to Enforce 2FA

Create a backup of the original admin.php:

cp /var/www/html/vicidial/admin.php /var/www/html/vicidial/admin.php.bak

Create /var/www/html/vicidial/admin_2fa_check.php (new wrapper):

<?php
/**
 * 2FA Check Wrapper for ViciDial Admin
 * Must be included at the top of admin.php
 */

session_start();

$config = array(
    'db_host' => 'localhost',
    'db_user' => 'root',
    'db_pass' => 'YOUR_DB_PASSWORD',
    'db_name' => 'asterisk',
    '2fa_enabled' => true,  // Set to false to disable 2FA globally
    '2fa_session_timeout' => 3600  // 1 hour in seconds
);

// List of admin usernames that MUST use 2FA
$mandatory_2fa_users = array(
    'admin',
    'root',
    'superadmin'
);

// Check if user is already verified in this session
if (isset($_SESSION['2fa_verified']) && isset($_SESSION['admin_user'])) {
    // Check session timeout
    if (isset($_SESSION['2fa_verify_time'])) {
        if ((time() - $_SESSION['2fa_verify_time']) < $config['2fa_session_timeout']) {
            // Session still valid - continue to admin.php
            return true;
        } else {
            // Session expired - force re-authentication
            session_destroy();
            header('Location: admin_2fa_login.php');
            exit;
        }
    }
}

// User not yet verified - redirect to 2FA login
if ($config['2fa_enabled']) {
    // Check if accessing admin.php directly
    if (basename($_SERVER['PHP_SELF']) === 'admin.php') {
        header('Location: admin_2fa_login.php');
        exit;
    }
}

Now, modify the original /var/www/html/vicidial/admin.php to include the 2FA check at the very top (after <?php):

<?php
// Add this immediately after opening PHP tag
require_once('admin_2fa_check.php');

// ... rest of original admin.php code ...

Or, create a new admin.php that acts as a wrapper:

<?php
require_once('admin_2fa_check.php');
include('admin.php.bak');
?>

3.6 Generate QR Codes for User Enrollment

Create /var/www/html/vicidial/setup_2fa.php (accessible only to logged-in admins):

<?php
session_start();
error_reporting(0);

$db_host = 'localhost';
$db_user = 'root';
$db_pass = 'YOUR_DB_PASSWORD';
$db_name = 'asterisk';

$mysqli = new mysqli($db_host, $db_user, $db_pass, $db_name);

require_once 'GoogleAuthenticator.php';
$ga = new PHPGangsta_GoogleAuthenticator();

// Only accessible via POST with proper session
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    die('Invalid request');
}

// Generate new TOTP secret
$secret = $ga->createSecret();
$username = sanitizeInput($_POST['username'] ?? '');

if (!$username) {
    die('Username required');
}

// Generate QR code URL
$qr_url = $ga->getQRCodeGoogleUrl('ViciDial Admin', $secret);

// Generate backup codes (10 codes)
$backup_codes = array();
for ($i = 0; $i < 10; $i++) {
    $backup_codes[] = bin2hex(random_bytes(4));
}
$backup_codes_json = json_encode($backup_codes);

// Store in database (not yet enabled until user confirms)
$stmt = $mysqli->prepare("
    INSERT INTO vicidial_admin_2fa (username, totp_secret, backup_codes, totp_enabled)
    VALUES (?, ?, ?, 'N')
    ON DUPLICATE KEY UPDATE
        totp_secret = VALUES(totp_secret),
        backup_codes = VALUES(backup_codes),
        totp_enabled = 'N'
");
$stmt->bind_param('sss', $username, $secret, $backup_codes_json);
$stmt->execute();
$stmt->close();

// Return JSON response
header('Content-Type: application/json');
echo json_encode(array(
    'success' => true,
    'qr_code_url' => $qr_url,
    'secret' => $secret,
    'backup_codes' => $backup_codes
));

function sanitizeInput($input) {
    return htmlspecialchars(trim($input), ENT_QUOTES, 'UTF-8');
}
?>

3.7 Enable 2FA for Specific Users

Run this SQL to enable 2FA for critical admin accounts:

UPDATE vicidial_admin_2fa 
SET totp_enabled = 'Y' 
WHERE username IN ('admin', 'superadmin');

-- View current 2FA status
SELECT username, totp_enabled, last_verified, created_date 
FROM vicidial_admin_2fa 
ORDER BY created_date DESC;

Monitor 2FA login attempts:

mysql -u root -p asterisk -e "
SELECT username, attempt_type, result, remote_ip, attempt_time 
FROM vicidial_2fa_audit 
WHERE attempt_time >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
ORDER BY attempt_time DESC;
"

Section 4: Harden Database and Related Access

4.1 Restrict MySQL Access

By default, MySQL listens on all interfaces. Restrict it to localhost:

Edit /etc/mysql/mysql.conf.d/mysqld.cnf:

[mysqld]
bind-address = 127.0.0.1
skip-external-locking

# Disable DNS resolution (faster, more secure)
skip-name-resolve

# Disable file-based access
skip-load-data-local-infile

Restart MySQL:

systemctl restart mysql

4.2 Create Least-Privilege Database User

Instead of using root for the web application, create a dedicated user:

-- Create new user for web app
CREATE USER 'vicidial_web'@'localhost' IDENTIFIED BY 'COMPLEX_PASSWORD_HERE';

-- Grant minimal privileges
GRANT SELECT, INSERT, UPDATE ON asterisk.* TO 'vicidial_web'@'localhost';
GRANT SELECT ON asterisk.vicidial_users TO 'vicidial_web'@'localhost';
GRANT SELECT ON asterisk.vicidial_admin_2fa TO 'vicidial_web'@'localhost';
GRANT INSERT ON asterisk.vicidial_2fa_audit TO 'vicidial_web'@'localhost';

-- Apply changes
FLUSH PRIVILEGES;

-- Verify
SELECT user, host, authentication_string FROM mysql.user WHERE user = 'vicidial_web';
SHOW GRANTS FOR 'vicidial_web'@'localhost';

Update your PHP scripts to use this user instead of root.

4.3 Log All Admin Database Queries

Enable query logging for the asterisk database:

SET GLOBAL general_log = 'ON';
SET GLOBAL log_output = 'TABLE';

Query log is stored in mysql.general_log table. To export:

mysql -u root -p asterisk -e "
SELECT event_time, user_host, command_type, argument 
FROM mysql.general_log 
WHERE db = 'asterisk' AND command_type IN ('Query', 'Execute')
LIMIT 100;
" > /var/log/vicidial-db-queries.log

To disable general log (after investigation):

SET GLOBAL general_log = 'OFF';

Section 5: Monitoring and Logging

5.1 Configure Centralized Logging

Create /var/www/html/vicidial/log_admin_events.php:


php
<?php
/**
 * Log all admin access events to file and database
 */

function logAdminEvent($event_type, $username, $action, $details = array()) {
    $log_file = '/var/log/vicidial/admin-events.log';

    // Ensure log directory exists
    if (!is_dir('/var/log/vicidial')) {
        mkdir('/var/log/vicidial', 0750, true);
        chown('/var/log/vicidial', 'www-data');
    }

    $timestamp = date('Y-m-d H:i:s');
    $remote_ip = $_SERVER['REMOTE_ADDR'];
    $user_agent = substr($_SERVER['HTTP_USER_AGENT'] ?? 'Unknown', 0, 100);

    $log_entry = sprintf(
        "[%s] Type:%s | User:%s | Action:%s | IP:%s | UA:%s | Details:%s\n",
        $timestamp,
        $event_type,
        $username,
        $action,
        $remote_ip,
        $user_agent,
        json_encode($details)
    );

    // Write to file
    file_put_contents($log_file, $log_entry, FILE_APPEND | LOCK_EX);

    // Also log to syslog
    openlog('vicidial-admin', LOG_PID | LOG_PERROR, LOG_LOCAL0);
    sys

ViciDial Time Zone Routing — Call at the Right Local Time

Moisi Trungu — Tue, 21 Jul 2026 03:30:02 +0000

ViciDial Time Zone Routing — Call at the Right Local Time

Master ViciDial's timezone routing capabilities to deliver calls to the right prospect at the right local time, increasing answer rates and compliance with do-not-call regulations.

Introduction

Time zone routing in ViciDial is one of the most underutilized yet powerful features for improving contact center efficiency. Whether you're running a multi-state sales operation, managing customer support across regions, or navigating strict calling hour restrictions, intelligent timezone-aware call delivery directly impacts your metrics.

This tutorial covers the practical implementation of time zone routing in ViciDial/Asterisk production environments—from database configuration and campaign setup through real-time call routing logic and validation.

Prerequisites

Before implementing timezone routing, ensure you have:

ViciDial 2.13+ installed and fully functional (2.14.1+ recommended for latest timezone fixes)
Asterisk 13+ with proper TLS/SIP configuration
MariaDB/MySQL root or administrative access
SSH access to your ViciDial server with sudo privileges
Existing campaigns configured with at least one carrier/trunk
Basic understanding of ViciDial admin interface, MySQL, and Asterisk dialplan
Timezone database files at /usr/share/zoneinfo/ (standard on Linux)
Test phone numbers across multiple time zones for validation

Understanding ViciDial's Time Zone Architecture

How ViciDial Handles Time Zones

ViciDial stores timezone information at multiple levels:

Server timezone — System timezone on the ViciDial machine
Campaign timezone — Default timezone for a campaign
Lead timezone — Individual prospect timezone (overrides campaign setting)
Carrier timezone — Routing rules per carrier
Agent timezone — Desktop agent location (for callback scenarios)

The ViciDial database uses the vicidial_campaigns table to store campaign-level timezone settings, and vicidial_list table stores lead-specific timezone data. When a call is queued, the dialer checks these values against the current time to determine if a call should be placed or held.

Core Database Tables

Three tables handle timezone logic:

vicidial_campaigns.campaign_timezone (varchar 45)
vicidial_campaigns.lead_filter_level (int, affects timezone logic)
vicidial_list.lead_timezone (varchar 45)

The dialer processes leads in order, but only initiates calls when the prospect's local time falls within allowed calling hours.

Configuring Campaign-Level Time Zone Settings

Step 1: Set Default Campaign Timezone

Access your ViciDial admin interface and navigate to Campaigns → Edit Campaign. Or directly update the database:

UPDATE vicidial_campaigns 
SET campaign_timezone = 'America/New_York' 
WHERE campaign_id = 'TEST_CAMP';

Valid timezone strings use the IANA timezone database format. Common examples:

America/New_York
America/Chicago
America/Denver
America/Los_Angeles
America/Anchorage
Pacific/Honolulu
Europe/London
Europe/Paris
Asia/Tokyo
Australia/Sydney

Step 2: Configure Calling Hours

Calling hours are stored in the vicidial_campaigns table in two fields:

start_call_hour (integer 0-23)
end_call_hour (integer 0-23)

Set these to your business hours in the campaign timezone:

UPDATE vicidial_campaigns 
SET start_call_hour = 9, 
    end_call_hour = 20 
WHERE campaign_id = 'TEST_CAMP';

This restricts all calls to 9:00 AM – 8:00 PM prospect local time.

Step 3: Enable Hour-Based Lead Filtering

The lead_filter_level controls how aggressively the dialer filters calls by time:

UPDATE vicidial_campaigns 
SET lead_filter_level = 1 
WHERE campaign_id = 'TEST_CAMP';

Values:

0 — No time-based filtering (call anytime)
1 — Filter by start/end hours only
2 — Filter by hours + respect timezone (recommended)
3 — Strict mode (filter even if uncertain)

For production multi-timezone campaigns, use level 2.

Lead-Level Timezone Assignment

Bulk Assign Timezones

If your leads import without timezone data, assign them based on area codes or geographic data:

-- Assign New York timezone to 212 area code
UPDATE vicidial_list 
SET lead_timezone = 'America/New_York' 
WHERE phone_number LIKE '212%' 
AND campaign_id = 'TEST_CAMP';

-- Assign Pacific timezone to 415 area code
UPDATE vicidial_list 
SET lead_timezone = 'America/Los_Angeles' 
WHERE phone_number LIKE '415%' 
AND campaign_id = 'TEST_CAMP';

Import Timezones from CSV

When importing leads via ViciDial's upload interface, include a lead_timezone column:

phone_number,first_name,last_name,lead_timezone
5551234567,John,Doe,America/New_York
7075551234,Jane,Smith,America/Los_Angeles
3125559876,Bob,Johnson,America/Chicago

The ViciDial upload processor automatically populates the lead_timezone field.

Verify Timezone Data

Check that timezones are properly assigned:

SELECT lead_id, phone_number, lead_timezone, 
       DATE_FORMAT(NOW(), '%H:%i:%s') AS 'Server_Time'
FROM vicidial_list 
WHERE campaign_id = 'TEST_CAMP' 
LIMIT 10;

Sample output:

| lead_id | phone_number | lead_timezone       | Server_Time |
|---------|--------------|---------------------|-------------|
| 1       | 5551234567   | America/New_York    | 14:30:45    |
| 2       | 7075556789   | America/Los_Angeles | 14:30:45    |

Advanced Carrier and Trunk Routing

Route Calls by Time Zone and Carrier

For operations with geographically distributed carriers, route calls through region-specific trunks to minimize latency and comply with local regulations:

Edit your Asterisk extensions file at /etc/asterisk/extensions-vicidial.conf:

[from-vicidial-dialer]
exten => _X.,1,NoOp(ViciDial Call Router - Timezone Aware)
exten => _X.,n,Set(TIMEZONE=${DB(vicidial/lead/${LEADID}/timezone)})
exten => _X.,n,GotoIf($["${TIMEZONE}" = "America/New_York"]?route_ny)
exten => _X.,n,GotoIf($["${TIMEZONE}" = "America/Los_Angeles"]?route_la)
exten => _X.,n,GotoIf($["${TIMEZONE}" = "America/Chicago"]?route_chi)
exten => _X.,n,Goto(route_default)

exten => _X.,n(route_ny),Set(OUTBOUND_ROUTE=NY_CARRIER)
exten => _X.,n,Set(OUTBOUND_TRUNK=SIP/ny-carrier-trunk)
exten => _X.,n,Goto(dial_lead)

exten => _X.,n(route_la),Set(OUTBOUND_ROUTE=LA_CARRIER)
exten => _X.,n,Set(OUTBOUND_TRUNK=SIP/la-carrier-trunk)
exten => _X.,n,Goto(dial_lead)

exten => _X.,n(route_chi),Set(OUTBOUND_ROUTE=CHI_CARRIER)
exten => _X.,n,Set(OUTBOUND_TRUNK=SIP/chi-carrier-trunk)
exten => _X.,n,Goto(dial_lead)

exten => _X.,n(route_default),Set(OUTBOUND_ROUTE=DEFAULT)
exten => _X.,n,Set(OUTBOUND_TRUNK=SIP/default-carrier)
exten => _X.,n,Goto(dial_lead)

exten => _X.,n(dial_lead),NoOp(Dialing ${EXTEN} via ${OUTBOUND_TRUNK})
exten => _X.,n,Dial(${OUTBOUND_TRUNK}/${EXTEN},45,tT)
exten => _X.,n,Hangup()

exten => h,1,NoOp(Call ended)

Reload Asterisk after changes:

sudo asterisk -rx "dialplan reload"

Implementing Do-Not-Call Hour Compliance

Set Compliant Calling Windows

The most critical use case is respecting local calling hour laws. Update campaigns to enforce compliance:

-- Sales campaign: 9 AM - 8 PM prospect time
UPDATE vicidial_campaigns 
SET start_call_hour = 9, 
    end_call_hour = 20,
    campaign_timezone = 'America/New_York',
    lead_filter_level = 2,
    allow_inbound_call_queue = '0'
WHERE campaign_id = 'SALES_USA';

-- Support campaign: 8 AM - 6 PM
UPDATE vicidial_campaigns 
SET start_call_hour = 8, 
    end_call_hour = 18,
    campaign_timezone = 'America/Chicago',
    lead_filter_level = 2
WHERE campaign_id = 'SUPPORT_USA';

Validate Time Zone Logic

Run this query to identify leads that would be called outside allowed hours:

SELECT 
  vl.lead_id,
  vl.phone_number,
  vl.lead_timezone,
  vc.start_call_hour,
  vc.end_call_hour,
  CONVERT_TZ(NOW(), @@session.time_zone, CONCAT('+00:00')) AS utc_now,
  CONVERT_TZ(NOW(), @@session.time_zone, CONCAT(vl.lead_timezone)) AS prospect_local_time
FROM vicidial_list vl
JOIN vicidial_campaigns vc ON vl.campaign_id = vc.campaign_id
WHERE vl.campaign_id = 'SALES_USA'
  AND vl.status = 'NEW'
LIMIT 20;

This identifies prospects and their current local times relative to calling hour restrictions.

Practical Example: Multi-Region Campaign

Complete Configuration Walkthrough

Scenario: Running a sales campaign across all US time zones with region-specific carriers.

1. Create Campaign with Timezone Settings

INSERT INTO vicidial_campaigns (
  campaign_id,
  campaign_name,
  campaign_timezone,
  start_call_hour,
  end_call_hour,
  lead_filter_level,
  active,
  allow_inbound_call_queue
) VALUES (
  'MULTI_US',
  'Multi-Region USA Sales',
  'America/Chicago',
  9,
  20,
  2,
  'Y',
  'N'
);

2. Assign Timezones to Leads

-- Batch assign by area code pattern
UPDATE vicidial_list SET lead_timezone = 'America/New_York' 
WHERE phone_number REGEXP '^(201|202|203|212|215|516|718|845|914)' 
  AND campaign_id = 'MULTI_US';

UPDATE vicidial_list SET lead_timezone = 'America/Chicago' 
WHERE phone_number REGEXP '^(217|312|618|630|708|773|815)' 
  AND campaign_id = 'MULTI_US';

UPDATE vicidial_list SET lead_timezone = 'America/Denver' 
WHERE phone_number REGEXP '^(303|719|720|970)' 
  AND campaign_id = 'MULTI_US';

UPDATE vicidial_list SET lead_timezone = 'America/Los_Angeles' 
WHERE phone_number REGEXP '^(209|213|310|408|415|510|619|650|707|714|760|805|818|916|949)' 
  AND campaign_id = 'MULTI_US';

3. Verify Distribution

SELECT 
  lead_timezone,
  COUNT(*) AS lead_count,
  MIN(phone_number) AS sample_number
FROM vicidial_list
WHERE campaign_id = 'MULTI_US'
GROUP BY lead_timezone
ORDER BY lead_timezone;

Expected output:

| lead_timezone       | lead_count | sample_number |
|---------------------|------------|---------------|
| America/Chicago     | 1250       | 3125551001    |
| America/Denver      | 450        | 3035551234    |
| America/Los_Angeles | 2100       | 4155559876    |
| America/New_York    | 1800       | 2125554321    |

Monitoring and Logging

Check Active Call Distribution by Timezone

Real-time view of which timezones are currently receiving calls:

SELECT 
  vl.lead_timezone,
  COUNT(vcl.uniqueid) AS active_calls,
  MIN(DATE_FORMAT(vcl.call_date, '%H:%i:%s')) AS earliest_call
FROM vicidial_closer_log vcl
JOIN vicidial_list vl ON vcl.lead_id = vl.lead_id
WHERE vcl.call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
  AND vcl.campaign_id = 'MULTI_US'
GROUP BY vl.lead_timezone
ORDER BY active_calls DESC;

Audit Call Attempts Against Calling Hours

Identify any calls placed outside compliant windows:

SELECT 
  vl.lead_id,
  vl.phone_number,
  vl.lead_timezone,
  vcl.call_date,
  vc.start_call_hour,
  vc.end_call_hour,
  HOUR(CONVERT_TZ(vcl.call_date, @@session.time_zone, vl.lead_timezone)) AS call_hour_local,
  CASE 
    WHEN HOUR(CONVERT_TZ(vcl.call_date, @@session.time_zone, vl.lead_timezone)) >= vc.start_call_hour
      AND HOUR(CONVERT_TZ(vcl.call_date, @@session.time_zone, vl.lead_timezone)) < vc.end_call_hour 
    THEN 'COMPLIANT'
    ELSE 'NON-COMPLIANT'
  END AS compliance_status
FROM vicidial_closer_log vcl
JOIN vicidial_list vl ON vcl.lead_id = vl.lead_id
JOIN vicidial_campaigns vc ON vl.campaign_id = vc.campaign_id
WHERE vcl.campaign_id = 'MULTI_US'
  AND vcl.call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
HAVING compliance_status = 'NON-COMPLIANT'
ORDER BY vcl.call_date DESC;

Enable Timezone Logging in Asterisk

Add verbose logging to track timezone decisions in the dialer:

Edit /etc/asterisk/logger.conf:

[logfiles]
messages => notice,warning,error,verbose(3)

Then view logs in real-time:

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

Advanced: Custom Timezone Logic with AGI

For sophisticated routing beyond standard campaigns, implement an Asterisk Gateway Interface (AGI) script:

#!/usr/bin/perl
# /usr/share/astguiclient/agi-bin/timezone-router.agi

use strict;
use DBI;
use DateTime::TimeZone;
use DateTime;

my %ENV = ();
while(<STDIN>) {
    chomp;
    last unless length($_);
    if (/^([\w\d_]*):\s?(.*)$/) {
        $ENV{$1} = $2;
    }
}

sub agi_output {
    my $string = shift;
    print STDOUT "$string\n";
    warn "$string\n";
}

my $lead_id = $ARGV[0] // 0;
my $phone = $ARGV[1] // '';

# Connect to ViciDial database
my $dbh = DBI->connect('DBI:mysql:asterisk:localhost', 'cron', 'cron') 
    or die "Cannot connect: $DBI::errstr";

# Fetch lead timezone
my $sth = $dbh->prepare('SELECT lead_timezone FROM vicidial_list WHERE lead_id = ?');
$sth->execute($lead_id);
my ($tz_name) = $sth->fetchrow();
$sth->finish();

unless ($tz_name) {
    agi_output("SET VARIABLE TIMEZONE_VALID 0");
    $dbh->disconnect();
    exit(0);
}

# Get current time in prospect timezone
my $tz = DateTime::TimeZone->new(name => $tz_name);
my $now = DateTime->now(time_zone => $tz);
my $hour = $now->hour();
my $dow = $now->day_of_week(); # 1=Monday, 7=Sunday

# Fetch campaign calling hours
$sth = $dbh->prepare('
    SELECT start_call_hour, end_call_hour 
    FROM vicidial_campaigns 
    WHERE campaign_id = (SELECT campaign_id FROM vicidial_list WHERE lead_id = ?)
');
$sth->execute($lead_id);
my ($start_hour, $end_hour) = $sth->fetchrow();
$sth->finish();

# Check if within calling hours
my $can_call = 0;
if (defined $start_hour && defined $end_hour) {
    $can_call = 1 if ($hour >= $start_hour && $hour < $end_hour);
}

agi_output("SET VARIABLE LEAD_TIMEZONE $tz_name");
agi_output("SET VARIABLE PROSPECT_LOCAL_HOUR $hour");
agi_output("SET VARIABLE CAN_CALL $can_call");
agi_output("SET VARIABLE CALL_START_HOUR $start_hour") if defined $start_hour;

$dbh->disconnect();
exit(0);

Execute from dialplan:

exten => _X.,1,AGI(agi-bin/timezone-router.agi,${LEADID},${EXTEN})
exten => _X.,n,GotoIf($[${CAN_CALL} = 1]?proceed:blocked)
exten => _X.,n(proceed),Dial(SIP/default-carrier/${EXTEN},45,tT)
exten => _X.,n(blocked),Busy()

Troubleshooting

Problem: Calls Being Placed Outside Calling Hours

Symptom: ViciDial is calling prospects outside configured windows.

Root Cause: lead_filter_level is set to 0 or timezone data is missing.

Solution:

# Check current filter level
mysql -u cron -pcron asterisk -e "
SELECT campaign_id, lead_filter_level 
FROM vicidial_campaigns 
WHERE campaign_id = 'TEST_CAMP';"

# Update to enforce filtering
mysql -u cron -pcron asterisk -e "
UPDATE vicidial_campaigns 
SET lead_filter_level = 2 
WHERE campaign_id = 'TEST_CAMP';"

# Verify all leads have timezone data
mysql -u cron -pcron asterisk -e "
SELECT COUNT(*) as leads_without_tz 
FROM vicidial_list 
WHERE campaign_id = 'TEST_CAMP' 
AND lead_timezone IS NULL;"

If leads lack timezone, assign defaults:

UPDATE vicidial_list 
SET lead_timezone = 'America/New_York' 
WHERE campaign_id = 'TEST_CAMP' 
AND lead_timezone IS NULL;

Problem: Dialer Skipping Too Many Leads

Symptom: Dialer queue moving slowly; many leads skipped.

Root Cause: Timezone filtering is too restrictive or timezone database is outdated.

Solution:

Check for daylight saving time transitions:

# List recent timezone changes
zdump -v /etc/localtime | grep "2024" | tail -5

Update timezone database if stale:

sudo apt-get update
sudo apt-get install --only-upgrade tzdata
sudo systemctl restart asterisk

Verify dialer is using correct server timezone:

# Check server timezone
timedatectl

# Verify MySQL timezone
mysql -u cron -pcron asterisk -e "SELECT @@session.time_zone, @@global.time_zone;"

Set explicit timezone in MySQL:

SET GLOBAL time_zone = 'UTC';
SET SESSION time_zone = 'UTC';

Problem: Inconsistent Results Between Predictions and Actual Call Times

Symptom: Query predicts calls should be blocked, but they're being placed anyway.

Root Cause: Server timezone differs from database timezone assumptions.

Solution:

Normalize to UTC in all queries:

SELECT 
  vl.lead_id,
  vl.phone_number,
  vl.lead_timezone,
  vc.start_call_hour,
  vc.end_call_hour,
  -- Convert server time to UTC first, then to prospect timezone
  CONVERT_TZ(NOW(), @@session.time_zone, 'UTC') AS utc_time,
  DATE_FORMAT(
    CONVERT_TZ(
      CONVERT_TZ(NOW(), @@session.time_zone, 'UTC'), 
      'UTC', 
      vl.lead_timezone
    ), 
    '%H'
  ) AS prospect_hour_24
FROM vicidial_list vl
JOIN vicidial_campaigns vc ON vl.campaign_id = vc.campaign_id
WHERE vl.campaign_id = 'TEST_CAMP'
LIMIT 5;

Problem: Timezone in Asterisk Logs Shows as UTC, Not Prospect Time

Symptom: CDR timestamps don't reflect prospect local time.

Solution: This is expected behavior. ViciDial stores all times in server time (usually UTC) and converts during reporting. To see prospect time in logs, add a custom variable:

exten => _X.,1,Set(PROSPECT_TZ_TIME=${DB(vicidial/lead/${LEADID}/local_time)})
exten => _X.,n,NoOp(Calling ${EXTEN} in ${PROSPECT_TZ_TIME})

Problem: CONVERT_TZ() Returns NULL

Symptom: MySQL CONVERT_TZ function returning NULL in queries.

Root Cause: MySQL timezone tables not populated.

Solution:

# Load timezone data into MySQL
mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql

# Restart MySQL
sudo systemctl restart mysql

# Verify load
mysql -u cron -pcron asterisk -e "SELECT COUNT(*) FROM mysql.time_zone;"

Should return a count > 500. If it's still NULL, ensure database has proper permissions:

sudo mysql_upgrade -u root -p

Summary

Implementing timezone routing in ViciDial requires attention to five key layers:

Campaign Configuration — Set campaign_timezone, calling hours, and lead_filter_level to 2
Lead Data — Populate lead_timezone accurately via import or bulk update
Database Timezone — Ensure MySQL and server timezones are properly synchronized
Dialplan Logic — Route calls through appropriate carriers and apply AGI scripts for complex rules
Monitoring — Audit compliance and validate calls align with configured windows

Key takeaways:

Always use lead_filter_level = 2 for production multi-timezone campaigns
Populate lead_timezone at import time; use area code patterns as fallback
Test timezone logic with direct SQL queries before enabling on live campaigns
Monitor dialer logs hourly during daylight saving transitions
Implement compliance audits weekly to catch misconfigured leads

With proper configuration, ViciDial's timezone routing increases answer rates by 15-25% while ensuring 100% compliance with calling hour regulations across all US time zones and international markets.

Asterisk Music on Hold — Custom Audio & Per-Queue MOH

Moisi Trungu — Mon, 20 Jul 2026 03:30:03 +0000

Asterisk Music on Hold — Custom Audio & Per-Queue MOH

Master custom music on hold setup, per-queue MOH routing, and troubleshooting for high-volume ViciDial production systems

Prerequisites

Before implementing custom MOH in Asterisk/ViciDial, verify:

Asterisk version 11+ (tested on 13.x, 16.x, 18.x)
ViciDial 2.14+ running on CentOS 7/8 or Ubuntu 18.04+
Root or sudo access to the Asterisk server
Audio files in WAV or MP3 format (MOH files must be 8 kHz, 16-bit mono for optimal performance)
Sufficient disk space in /var/lib/asterisk/moh/ (typically 500 MB–2 GB depending on queue count)
Asterisk service control: systemctl restart asterisk or /etc/init.d/asterisk restart
Database credentials for ViciDial (root or dedicated asterisk user)
Understanding of Asterisk dialplan basics and conf file syntax

Run asterisk -rx "core show version" to confirm Asterisk is running and accessible.

Understanding Asterisk Music on Hold Architecture

How MOH Works in Asterisk

Music on Hold is triggered when a call enters a queue, is placed on hold, or meets a Wait() application. Asterisk uses:

MOH Classes — defined in musiconhold.conf, each with a directory or file
MOH Selection — via dialplan (SetMusicOnHold()) or queue configuration
MOH Playback — native playback to calling party via audio stream
MOH Generators — optional generator for on-the-fly tone/silence generation

Default MOH directory: /var/lib/asterisk/moh/

ViciDial-Specific MOH Integration

ViciDial uses MOH at these points:

Queue hold — when agent is unavailable or queue is full
Callback queues — while customer waits for agent callback
IVR prompts — background music during menu selection
Transfer hold — during blind/attended transfers

Core MOH Configuration Files

Primary Configuration: musiconhold.conf

Located at /etc/asterisk/musiconhold.conf, this is the master MOH configuration.

[general]
; Default class if none specified
default=default

; Directory scanning mode - rescan disk for new files automatically
; Useful for dynamic queue changes
moh_quiet=yes

[default]
; Standard MP3 playback with quieting
mode=files
directory=/var/lib/asterisk/moh/default
; Quieting level (0-100)
quiet=100

[on-hold]
mode=files
directory=/var/lib/asterisk/moh/on-hold
quiet=100

[queue-sales]
mode=files
directory=/var/lib/asterisk/moh/sales
quiet=100

[queue-support]
mode=files
directory=/var/lib/asterisk/moh/support
quiet=100

[queue-billing]
mode=files
directory=/var/lib/asterisk/moh/billing
quiet=100

[silence]
; Silent MOH - useful for internal transfers
mode=silence

[tone]
; Audible ringback tone
mode=files
directory=/var/lib/asterisk/moh/tone
quiet=0

Key Parameters:

mode=files — use audio files from directory
mode=mp3 — legacy; use files instead
mode=silence — no audio, prevents dead-air
directory= — absolute path to MOH files
quiet=100 — reduce volume (0=loud, 100=silent); use 60–80 for balanced audio
application= — for generator-based MOH (DAHDI, SIP)

Extensions Dialplan: extensions-vicidial.conf

Add MOH selection logic to your dialplan:

[from-internal]
; Example: set MOH before queue
exten => 100,1,NoOp(Incoming call from ${CALLERID(num)})
exten => 100,n,SetMusicOnHold(queue-sales)
exten => 100,n,Queue(sales-queue,t)
exten => 100,n,Hangup()

exten => 101,1,NoOp(Support queue)
exten => 101,n,SetMusicOnHold(queue-support)
exten => 101,n,Queue(support-queue,t)
exten => 101,n,Hangup()

Queue Configuration: queues.conf

ViciDial typically manages queues via database, but direct queues.conf configuration is still used:

[sales-queue]
strategy=linear
timeout=30
retry=5
maxlen=0
; Music on hold class for this queue
musiconhold=queue-sales
; Announce position every 60 seconds
announce-frequency=60
announce-round-seconds=10
setinterfacevar=yes
setqueuevar=yes

[support-queue]
strategy=linear
timeout=30
retry=5
maxlen=0
musiconhold=queue-support
announce-frequency=120

[callback-queue]
strategy=linear
timeout=300
retry=10
maxlen=100
musiconhold=on-hold

Setting Up Per-Queue Music on Hold

Step 1: Create Per-Queue MOH Directories

Establish separate directories for each queue:

mkdir -p /var/lib/asterisk/moh/{default,sales,support,billing,vip}
chown -R asterisk:asterisk /var/lib/asterisk/moh/
chmod 755 /var/lib/asterisk/moh/*

Step 2: Prepare and Validate Audio Files

Audio files must meet specific requirements:

For WAV files:

ffmpeg -i original-music.mp3 -acodec pcm_s16le -ar 8000 -ac 1 /var/lib/asterisk/moh/sales/music.wav

For MP3 files (if using mp3 mode):

ffmpeg -i original-music.mp3 -acodec libmp3lame -ar 8000 -ac 1 -b:a 32k /var/lib/asterisk/moh/sales/music.mp3

Batch conversion for directory:

#!/bin/bash
SOURCE_DIR="/tmp/moh-source"
DEST_DIR="/var/lib/asterisk/moh/sales"

for file in ${SOURCE_DIR}/*; do
  filename=$(basename "$file" | cut -d. -f1)
  ffmpeg -i "$file" -acodec pcm_s16le -ar 8000 -ac 1 "${DEST_DIR}/${filename}.wav"
done

chown -R asterisk:asterisk ${DEST_DIR}
chmod 644 ${DEST_DIR}/*

Validate audio format:

sox /var/lib/asterisk/moh/sales/music.wav -n stat
# Output should show: Sample Rate 8000, Channels 1

Step 3: Update musiconhold.conf with Queue-Specific Entries

[queue-sales]
mode=files
directory=/var/lib/asterisk/moh/sales
quiet=70

[queue-support]
mode=files
directory=/var/lib/asterisk/moh/support
quiet=70

[queue-billing]
mode=files
directory=/var/lib/asterisk/moh/billing
quiet=70

[queue-vip]
mode=files
directory=/var/lib/asterisk/moh/vip
quiet=60

Step 4: Configure Queues with MOH Class Assignment

Edit or create /etc/asterisk/queues.conf:

[general]
shared_lastcall=yes
monitor-type=MixMonitor

[sales-queue]
strategy=linear
timeout=30
retry=5
musiconhold=queue-sales
autofill=yes
setinterfacevar=yes
setqueuevar=yes
announce-frequency=60
announce-round-seconds=10

[support-queue]
strategy=linear
timeout=30
retry=5
musiconhold=queue-support
autofill=yes
setinterfacevar=yes
setqueuevar=yes

[billing-queue]
strategy=ring
timeout=45
retry=10
musiconhold=queue-billing
maxlen=50

[callback-queue]
strategy=linear
timeout=300
retry=15
musiconhold=queue-sales
maxlen=100
joined-sound=queue-youare

Step 5: Reload and Test MOH

After configuration changes, reload Asterisk:

asterisk -rx "reload musiconhold"
asterisk -rx "reload queues"
asterisk -rx "reload res_musiconhold"

Verify MOH classes are loaded:

asterisk -rx "moh show classes"

Expected output:

Class: queue-sales
   Mode: files
   Directory: /var/lib/asterisk/moh/sales
   Quieting: 70

Class: queue-support
   Mode: files
   Directory: /var/lib/asterisk/moh/support
   Quieting: 70

Class: queue-billing
   Mode: files
   Directory: /var/lib/asterisk/moh/billing
   Quieting: 70

ViciDial Database Configuration

Integrating MOH with ViciDial Queue Tables

ViciDial stores queue configuration in the asterisk database. Use these tables:

Table: vicidial_queues

SELECT * FROM vicidial_queues WHERE queue_name='sales-queue'\G

Key fields:

queue_id — unique identifier
queue_name — queue name (matches Asterisk queue)
queue_maxlen — max queue depth
queue_timeout — agent ring timeout
queue_strategy — linear, ring, weighted_random
music_on_hold — MOH class name

Update ViciDial Queue MOH via SQL:

UPDATE vicidial_queues SET music_on_hold='queue-sales' WHERE queue_name='sales-queue';
UPDATE vicidial_queues SET music_on_hold='queue-support' WHERE queue_name='support-queue';
UPDATE vicidial_queues SET music_on_hold='queue-billing' WHERE queue_name='billing-queue';
COMMIT;

Verify via ViciDial web UI:
Navigate to /vicidial/admin.php → Queues → Edit each queue → Set "Music on Hold" dropdown to desired class.

Database Sync Script

Create a script to sync MOH settings from database to dialplan:

#!/bin/bash
# /usr/local/bin/sync-moh-to-dialplan.sh

MYSQL_USER="root"
MYSQL_PASS="your_password"
MYSQL_DB="asterisk"
OUTFILE="/etc/asterisk/queues-vicidial.conf"

cat > ${OUTFILE} << 'EOF'
[general]
shared_lastcall=yes
monitor-type=MixMonitor

EOF

mysql -u${MYSQL_USER} -p${MYSQL_PASS} ${MYSQL_DB} << 'SQLEOF' | while read queue_name moh_class; do
SELECT queue_name, COALESCE(music_on_hold, 'default') FROM vicidial_queues WHERE active='Y' ORDER BY queue_name;
SQLEOF

cat >> ${OUTFILE} << QEOF
[${queue_name}]
strategy=linear
timeout=30
retry=5
musiconhold=${moh_class}
autofill=yes
setinterfacevar=yes
setqueuevar=yes
QEOF

done

chown asterisk:asterisk ${OUTFILE}
asterisk -rx "reload queues"

Schedule with cron:

0 */4 * * * /usr/local/bin/sync-moh-to-dialplan.sh

Advanced MOH Techniques

Dynamic MOH Selection via Channel Variables

Use SetMusicOnHold() in dialplan to override queue-level MOH:

[from-vicidial]
exten => _X.,1,NoOp(Dynamic MOH selection)
exten => _X.,n,Set(CALLER_LANG=${CALLERID(name):0:2})
exten => _X.,n,GotoIf($["${CALLER_LANG}"="ES"]?spanish:english)
exten => _X.,n(english),SetMusicOnHold(queue-sales)
exten => _X.,n,Goto(queue-main)
exten => _X.,n(spanish),SetMusicOnHold(queue-sales-spanish)
exten => _X.,n(queue-main),Queue(sales-queue,t)
exten => _X.,n,Hangup()

Custom Voicemail Greeting Integration

Combine MOH with IVR greetings:

[from-queue-announcement]
exten => s,1,NoOp(Queue announcement with MOH)
exten => s,n,SetMusicOnHold(queue-sales)
exten => s,n,Playback(queue/position-in-queue)
exten => s,n,Playback(queue/est-wait-time)
exten => s,n,Queue(sales-queue,t)
exten => s,n,Hangup()

Silence on Hold for Internal Transfers

For agent-to-agent transfers, use silent MOH:

[agent-transfer]
exten => *1,1,NoOp(Blind transfer to ${ARG1})
exten => *1,n,SetMusicOnHold(silence)
exten => *1,n,Blind Transfer(${ARG1})
exten => *1,n,Hangup()

Conditional MOH Based on Queue Depth

[from-vicidial]
exten => 100,1,NoOp(Queue ${QUEUENAME} check)
exten => 100,n,Queue(sales-queue,t)
exten => 100,n,GotoIf($["${QUEUE_MEMBER_COUNT}">"5"]?busy:available)
exten => 100,n(available),SetMusicOnHold(queue-sales)
exten => 100,n,Goto(end)
exten => 100,n(busy),SetMusicOnHold(queue-vip)
exten => 100,n(end),Hangup()

Looped MOH with Periodic Announcements

Create a custom application that plays MOH, then an announcement, repeatedly:

[queue-with-announcements]
exten => s,1,NoOp(MOH + periodic announcement)
exten => s,n,SetMusicOnHold(queue-sales)
exten => s,n,WaitExten(30)
exten => s,n,Playback(queue/estimated-wait)
exten => s,n,WaitExten(30)
exten => s,n,Queue(sales-queue,t)
exten => s,n,Hangup()

Monitoring and Performance Tuning

Check MOH Playback in Real-Time

View active calls using MOH:

asterisk -rx "core show calls" | grep -i "music\|Queue"

Sample output:

SIP/2001-00000001     Queue(sales-queue,t)    0:00:15
SIP/2002-00000002     Queue(support-queue,t)  0:00:42

Monitor MOH File Usage

Track which MOH classes are actively used:

asterisk -rx "moh show classes"
asterisk -rx "core show channels concise" | awk -F'!' '{print $10}' | sort | uniq -c

Audio Quality Diagnostics

Verify audio playback quality:

sox /var/lib/asterisk/moh/sales/music.wav -n remix - | sox - -n stat
# Check: RMS amplitude, Peak amplitude, Crest factor

Optimize quiet Parameter

Test MOH with different quieting levels:

# Lower quiet value = louder
# Higher quiet value = quieter
# Typical range: 60-80

[queue-sales]
quiet=70  # Balanced
quiet=40  # Louder
quiet=100 # Quieter/silence preservation

CPU Usage Monitoring

MOH playback CPU impact is minimal, but monitor with:

top -b -n 1 | grep asterisk
ps aux | grep asterisk | grep -v grep

Troubleshooting

MOH Not Playing When Call Enters Queue

Symptom: Dead silence on hold instead of music.

Diagnosis:

asterisk -rx "moh show classes"

If MOH classes don't appear or are empty:

Check musiconhold.conf syntax:

   asterisk -m -c "moh reload" 2>&1 | grep -i error

Verify audio files exist and are readable:

   ls -la /var/lib/asterisk/moh/queue-sales/
   chown -R asterisk:asterisk /var/lib/asterisk/moh/
   chmod 755 /var/lib/asterisk/moh/*
   chmod 644 /var/lib/asterisk/moh/*/*

Reload MOH module:

   asterisk -rx "module reload res_musiconhold.so"
   asterisk -rx "reload musiconhold"

MOH Class Not Found for Queue

Symptom: Asterisk CLI shows error: Unable to locate MOH class queue-sales

Solution:

Verify queue name matches musiconhold.conf:

   SELECT queue_name, music_on_hold FROM vicidial_queues;

Check queues.conf has matching musiconhold entry:

   grep -A 5 "^\[sales-queue\]" /etc/asterisk/queues.conf | grep musiconhold

Reload both configs:

   asterisk -rx "reload musiconhold"
   asterisk -rx "reload queues"

Audio Distortion or Quality Issues

Symptom: MOH playback sounds garbled, clipped, or distorted.

Solutions:

Check audio file format:

   ffprobe -v error -show_entries stream=sample_rate,channels,codec_name \
     -of default=noprint_wrappers=1 /var/lib/asterisk/moh/sales/music.wav
   # Should output: sample_rate=8000, channels=1

Re-encode to correct format:

   ffmpeg -i /var/lib/asterisk/moh/sales/music.wav -acodec pcm_s16le \
     -ar 8000 -ac 1 /var/lib/asterisk/moh/sales/music-fixed.wav
   mv /var/lib/asterisk/moh/sales/music-fixed.wav \
     /var/lib/asterisk/moh/sales/music.wav

Adjust quiet parameter (reduce to increase volume):

   [queue-sales]
   quiet=50  # Increase volume (was 70)

Check Asterisk log for codec errors:

   tail -100 /var/log/asterisk/messages | grep -i "moh\|music\|codec"

Wrong MOH Playing for Queue

Symptom: Queue plays default MOH instead of queue-specific MOH.

Diagnosis:

Verify queue configuration in database:

   SELECT queue_name, music_on_hold FROM vicidial_queues WHERE queue_name='sales-queue';

Check dialplan override:

   grep -n "SetMusicOnHold" /etc/asterisk/extensions-vicidial.conf

Verify queues.conf musiconhold assignment:

   grep -A 10 "^\[sales-queue\]" /etc/asterisk/queues.conf

Force reload:

   asterisk -rx "reload musiconhold"
   asterisk -rx "reload queues"
   asterisk -rx "reload res_musiconhold.so"

MOH Stops After Few Seconds

Symptom: Music plays briefly, then cuts out; silence follows.

Causes:

Audio file too short or corrupt:

   sox /var/lib/asterisk/moh/sales/music.wav -n stat
   # Check duration; should be 2+ minutes

Directory permission issue:

   ls -la /var/lib/asterisk/moh/sales/
   # Should show: drwxr-xr-x asterisk:asterisk

Asterisk process permissions:

   ps aux | grep asterisk | grep -v grep
   # Should run as asterisk user

Fix:

chown -R asterisk:asterisk /var/lib/asterisk/moh/
chmod -R 755 /var/lib/asterisk/moh/
systemctl restart asterisk

High CPU Usage with MOH

Symptom: Asterisk CPU usage spikes when MOH is active.

Solutions:

Use MP3 or WAV, not generator-based MOH:

   [queue-sales]
   mode=files  # Not mode=mp3 or mode=DAHDI

Verify audio codec is efficient:

   ffprobe /var/lib/asterisk/moh/sales/music.wav
   # Should show PCM 8-bit or 16-bit, 8000 Hz

Reduce number of concurrent MOH streams if necessary:

   asterisk -rx "moh show files"

Logs Not Showing MOH Activity

Enable MOH debug logging:

asterisk -rx "core set debug 3"
asterisk -rx "core set verbose 3"
tail -f /var/log/asterisk/messages | grep -i moh

Check for specific errors:

grep -i "moh\|music\|hold" /var/log/asterisk/messages | tail -50

Summary

Implementing custom per-queue Music on Hold in Asterisk/ViciDial requires:

Audio Preparation: Convert media to 8 kHz, 16-bit mono WAV files for optimal quality and compatibility
Directory Structure: Organize MOH files in /var/lib/asterisk/moh/ with separate subdirectories per queue
Configuration: Define MOH classes in musiconhold.conf and assign to queues via queues.conf or ViciDial database
Dialplan Integration: Use SetMusicOnHold() for dynamic selection and combine with queue applications
Database Sync: Link ViciDial vicidial_queues table music_on_hold field to Asterisk configurations
Validation & Testing: Reload modules, verify with CLI commands, test with live calls
Monitoring: Use asterisk -rx commands to monitor active MOH playback and troubleshoot issues
Performance: Ensure proper file permissions, audio quality, and system resource allocation

Key commands for day-to-day operations:

# Reload after configuration changes
asterisk -rx "reload musiconhold"
asterisk -rx "reload queues"

# Verify MOH is loaded
asterisk -rx "moh show classes"

# Monitor active queues with MOH
asterisk -rx "core show calls" | grep Queue

# Restart Asterisk if issues persist
systemctl restart asterisk

With proper setup, ViciDial agents and customers will experience professional, branded music on hold tailored to each queue, improving perceived call quality and reducing perceived wait times.

ViciDial Recording Storage — NFS, S3 & Archival Strategies

Moisi Trungu — Sun, 19 Jul 2026 03:30:03 +0000

ViciDial Recording Storage — NFS, S3 & Archival Strategies

Master efficient recording storage architectures for ViciDial and Asterisk systems, comparing NFS block storage, S3 cloud solutions, and long-term archival strategies with production-tested configurations.

Prerequisites

Before implementing the strategies in this tutorial, you should have:

A running ViciDial installation (version 2.14+) with Asterisk 13+
Root or sudo access to your ViciDial servers
Basic understanding of Linux filesystems, NFS, and AWS S3 (or compatible service)
Database access to the asterisk database and vicidial_log table
Familiarity with Asterisk configuration files and the dialplan
At least 100GB of free storage for testing configurations
Network bandwidth planning completed for your expected call volume

This tutorial assumes CentOS 7/8 or Ubuntu 18.04+ operating systems. Commands should be adapted for your specific distribution.

Understanding ViciDial Recording Architecture

How ViciDial Records Calls

ViciDial uses Asterisk's native recording capabilities to capture calls. When a call is bridged between an agent and a customer, Asterisk writes audio data to disk in real-time. The recording process is controlled by the dialplan and ViciDial application logic.

Call recordings are stored in raw Asterisk format (typically WAV or GSM) and are referenced in the vicidial_log table with the field recording_id. Each call record contains a unique identifier linking to its corresponding audio file.

Key recording-related fields in vicidial_log:

recording_id — Unique identifier for the recording file
call_date — Timestamp of the call
length_in_sec — Duration of the recorded call
status — Call status (SALE, CANCEL, DNC, etc.)

Storage Sizing Calculations

For production planning, use these baseline figures:

GSM codec: ~10-12 KB per second (monaural, 8kHz)
WAV codec: ~32 KB per second (stereo, 16-bit, 8kHz)
MP3 (128kbps): ~16 KB per second

For a 100-agent center with average call length of 8 minutes:

Daily recordings = 100 agents × 80 calls/day × 480 seconds × 11 KB/sec
                 = 100 × 80 × 480 × 11 KB = 42,240,000 KB ≈ 40 GB/day
Monthly storage = 40 GB × 30 = 1.2 TB
Annual storage = 1.2 TB × 12 = 14.4 TB

This calculation shows why storage strategy is critical for scaling operations.

Recording Path Configuration in ViciDial

Default Recording Directory Structure

ViciDial records calls to /var/spool/asterisk/monitor/ by default. This directory is defined in the dialplan and should match your storage backend.

Verify current recording path in your extensions-vicidial.conf:

grep -n "monitor\|recording" /etc/asterisk/extensions-vicidial.conf | head -20

Standard ViciDial recording command in the dialplan:

exten => 8600,1,MixMonitor(${MIXMON_FILENAME}${MIXMON_FORMAT},b)
exten => 8600,n,Return()

Configuring Custom Recording Paths

To use a custom path, modify your ViciDial configuration. Edit the system settings table:

UPDATE vicidial_system_settings 
SET recording_directory = '/data/recordings' 
WHERE setting_name = 'asterisk_home';

Then verify Asterisk has permissions:

sudo chown -R asterisk:asterisk /data/recordings
sudo chmod 755 /data/recordings
ls -ld /data/recordings

Create subdirectories by date for better organization:

#!/bin/bash
# Create daily recording directories
for i in {0..30}; do
  date_dir=$(date -d "-$i days" +%Y/%m/%d)
  mkdir -p /data/recordings/$date_dir
  chown asterisk:asterisk /data/recordings/$date_dir
done

NFS-Based Recording Storage

When to Use NFS

NFS (Network File System) is ideal when:

You have multiple Asterisk servers sharing a single recording repository
Your network has low latency and high bandwidth (gigabit or better)
You want simple, proven file-level storage without cloud complexity
HIPAA or data residency requirements mandate on-premises storage

NFS is not recommended for:

High-latency or unreliable networks (use local storage or S3)
Single-server installations (use local storage instead)
Extreme scale (1000+ agents) without clustering NFS via Ceph

NFS Server Setup

Install NFS on your storage server:

# CentOS/RHEL
sudo yum install nfs-utils
sudo systemctl enable nfs-server
sudo systemctl start nfs-server

# Ubuntu/Debian
sudo apt-get install nfs-kernel-server
sudo systemctl enable nfs-server
sudo systemctl start nfs-server

Create the recording directory:

sudo mkdir -p /mnt/recordings
sudo chown nobody:nogroup /mnt/recordings
sudo chmod 755 /mnt/recordings

Configure NFS exports in /etc/exports:

/mnt/recordings 192.168.1.0/24(rw,sync,no_subtree_check,no_root_squash,atime=off)

The parameters explained:

rw — Read and write access
sync — Force synchronous writes (safer, slightly slower)
no_subtree_check — Improves performance, safe for most setups
no_root_squash — Allow root on client to write as root on server
atime=off — Disable access time updates (significant performance gain)

Apply the exports:

sudo exportfs -a
sudo exportfs -v

NFS Client Configuration on Asterisk Servers

Install NFS client:

# CentOS/RHEL
sudo yum install nfs-utils

# Ubuntu/Debian
sudo apt-get install nfs-common

Create mount point:

sudo mkdir -p /var/spool/asterisk/monitor

Mount the NFS share:

sudo mount -t nfs -o rw,sync,hard,intr,rsize=8192,wsize=8192 \
  192.168.1.50:/mnt/recordings /var/spool/asterisk/monitor

Mount options explained:

hard — Keep retrying if server is unavailable (don't give up)
intr — Allow interrupting hung NFS calls with Ctrl+C
rsize/wsize — Read/write buffer sizes (8KB good for voice; larger for throughput)

Verify the mount:

mount | grep monitor
df -h /var/spool/asterisk/monitor

Make the mount persistent by adding to /etc/fstab:

192.168.1.50:/mnt/recordings /var/spool/asterisk/monitor nfs \
rw,sync,hard,intr,rsize=8192,wsize=8192,_netdev 0 0

Use _netdev to ensure NFS mounts after network is up.

NFS Performance Tuning

Monitor NFS performance:

# Install nfs-utils if not present
sudo yum install nfs-utils

# Check NFS statistics
nfsstat -c | head -20

# Monitor NFS operations per second
iostat -x 1 5 | grep nfs

For high-volume recording scenarios, increase buffer sizes on both server and client:

On NFS server (/etc/nfs.conf or kernel parameters):

# Edit /etc/sysctl.conf on the NFS server
net.core.rmem_max = 134217728
net.core.wmem_max = 134217728
net.ipv4.tcp_rmem = 4096 87380 67108864
net.ipv4.tcp_wmem = 4096 65536 67108864

# Apply settings
sudo sysctl -p

On NFS client mount options, use larger buffers:

sudo mount -t nfs -o rw,sync,hard,intr,rsize=32768,wsize=32768 \
  192.168.1.50:/mnt/recordings /var/spool/asterisk/monitor

Test throughput with dd:

# Write test
dd if=/dev/zero of=/var/spool/asterisk/monitor/test-write bs=1M count=1000 oflag=direct
# Expected: 100+ MB/s on gigabit Ethernet

# Read test
dd if=/var/spool/asterisk/monitor/test-write of=/dev/null bs=1M
rm /var/spool/asterisk/monitor/test-write

S3-Based Recording Storage

Why S3 for ViciDial

Amazon S3 or compatible services (MinIO, DigitalOcean Spaces, Wasabi) offer:

Virtually unlimited scalability
Automatic replication and durability (99.999999999%)
Pay-as-you-go pricing
Geographic redundancy without hardware
Built-in archival to Glacier for cost reduction

Trade-offs:

Network latency for write operations
Per-request costs (though minimal)
Requires cloud account or private S3 setup
Slight complexity in failover and hybrid scenarios

S3 Bucket Configuration

Create an S3 bucket for ViciDial recordings:

# Using AWS CLI v2
aws s3 mb s3://vicidial-recordings-prod --region us-east-1

# Enable versioning for protection against accidental deletes
aws s3api put-bucket-versioning \
  --bucket vicidial-recordings-prod \
  --versioning-configuration Status=Enabled

# Set lifecycle policy to archive old recordings
aws s3api put-bucket-lifecycle-configuration \
  --bucket vicidial-recordings-prod \
  --lifecycle-configuration file://lifecycle.json

Create lifecycle.json:

{
  "Rules": [
    {
      "Id": "Archive old recordings to Glacier",
      "Status": "Enabled",
      "Prefix": "recordings/",
      "Transitions": [
        {
          "Days": 90,
          "StorageClass": "GLACIER"
        }
      ],
      "Expiration": {
        "Days": 2555
      }
    }
  ]
}

This policy:

Moves recordings to Glacier after 90 days (cost reduction from $0.023/GB to $0.004/GB)
Deletes after 7 years (adjust based on compliance requirements)

Using S3fuse or S3FS

S3FS mounts S3 as a filesystem. Install on Asterisk server:

# CentOS/RHEL
sudo yum install epel-release
sudo yum install s3fs-fuse

# Ubuntu/Debian
sudo apt-get install s3fs

Create credentials file:

# Store AWS credentials (never commit to version control)
echo "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" > ~/.s3fs-credentials
chmod 600 ~/.s3fs-credentials

Mount S3 bucket:

# Create mount point
sudo mkdir -p /var/spool/asterisk/monitor

# Mount S3 bucket
s3fs vicidial-recordings-prod /var/spool/asterisk/monitor \
  -o passwd_file=~/.s3fs-credentials \
  -o use_cache=/tmp \
  -o allow_other \
  -o mp_umask=002 \
  -o multithreaded \
  -o parallel_count=20 \
  -o multipart_size=64

Parameters explained:

allow_other — Allow processes other than owner to access
multithreaded — Enable parallel uploads
parallel_count — Number of parallel upload threads
multipart_size — Size of multipart uploads in MB

Verify mount:

mount | grep s3fs
df -h /var/spool/asterisk/monitor
echo "test" > /var/spool/asterisk/monitor/test.txt
aws s3 ls s3://vicidial-recordings-prod/test.txt

Warning: S3FS has latency. For active recording paths, use local storage + asynchronous upload instead.

Recommended Approach: Local + S3 Upload

Use local storage for recording, then upload asynchronously to S3:

#!/bin/bash
# /usr/local/sbin/upload-recordings-to-s3.sh
# Run via cron every 5 minutes

RECORDING_DIR="/var/spool/asterisk/monitor"
S3_BUCKET="s3://vicidial-recordings-prod"
AWS_PROFILE="vicidial-prod"
LOG_FILE="/var/log/s3-upload.log"

# Find recordings older than 1 minute (completed calls)
find $RECORDING_DIR -name "*.wav" -type f -mmin +1 | while read recording; do
  # Skip if already uploaded (check for .uploaded marker)
  if [[ -f "${recording}.uploaded" ]]; then
    continue
  fi

  # Determine S3 path based on date
  file_date=$(stat -c %y "$recording" | cut -d' ' -f1 | tr '-' '/')
  s3_path="${S3_BUCKET}/recordings/${file_date}/$(basename $recording)"

  # Upload to S3
  if aws s3 cp "$recording" "$s3_path" --profile=$AWS_PROFILE >> "$LOG_FILE" 2>&1; then
    # Mark as uploaded
    touch "${recording}.uploaded"

    # Optionally delete local copy after 7 days
    find $RECORDING_DIR -name "*.uploaded" -mtime +7 | while read marker; do
      rm "${marker%.*}" "$marker"
    done
  fi
done

echo "[$(date)] Upload cycle complete" >> "$LOG_FILE"

Add to crontab:

*/5 * * * * /usr/local/sbin/upload-recordings-to-s3.sh

This approach:

Keeps recording writes fast (local disk)
Asynchronously uploads to S3 without blocking
Maintains local copies for immediate playback
Can delete after 7 days to save local storage

S3-Compatible Services (MinIO)

For on-premises S3 storage, use MinIO:

# Install MinIO on a dedicated server
wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio
sudo mv minio /usr/local/bin/

# Create data directory
sudo mkdir -p /mnt/minio-data
sudo chown minio:minio /mnt/minio-data

# Start MinIO
MINIO_ROOT_USER=admin MINIO_ROOT_PASSWORD=securepassword \
  /usr/local/bin/minio server /mnt/minio-data

Access MinIO console at http://minio-server:9001 and configure like S3.

Recording Archival and Retention Strategies

Database-Driven Archival

Track recordings in the database and implement retention policies programmatically.

Query active recordings:

SELECT 
  call_id,
  recording_id,
  call_date,
  status,
  LENGTH(call_date) as duration_days,
  TIMESTAMPDIFF(DAY, call_date, NOW()) as age_days
FROM vicidial_log
WHERE recording_id IS NOT NULL
  AND recording_id != ''
  AND call_date > DATE_SUB(NOW(), INTERVAL 90 DAY)
ORDER BY call_date DESC
LIMIT 100;

Create a retention policy based on status:

-- Archive recordings for closed campaigns after 30 days
CREATE PROCEDURE archive_old_recordings()
BEGIN
  DECLARE done INT DEFAULT FALSE;
  DECLARE rec_id VARCHAR(100);
  DECLARE cur CURSOR FOR
    SELECT DISTINCT recording_id
    FROM vicidial_log
    WHERE recording_id IS NOT NULL
      AND recording_id != ''
      AND TIMESTAMPDIFF(DAY, call_date, NOW()) > 30
      AND campaign_id IN (SELECT campaign_id FROM vicidial_campaigns WHERE active='N');

  DECLARE CONTINUE HANDLER FOR NOT FOUND SET done = TRUE;

  OPEN cur;

  read_loop: LOOP
    FETCH cur INTO rec_id;
    IF done THEN
      LEAVE read_loop;
    END IF;

    -- Log archival action
    INSERT INTO vicidial_log_archive (recording_id, archived_date, archive_location)
    VALUES (rec_id, NOW(), 'S3');

  END LOOP;

  CLOSE cur;
END;

Execute archival:

mysql -u vicidialuser -p asterisk -e "CALL archive_old_recordings();"

Implementing Deletion Policies

Create a safe deletion script that confirms recordings still exist before removal:

#!/bin/bash
# /usr/local/sbin/purge-old-recordings.sh
# Delete recordings older than retention period

RETENTION_DAYS=365
RECORDING_DIR="/var/spool/asterisk/monitor"
DB_USER="vicidialuser"
DB_PASS="PASSWORD"
DB_NAME="asterisk"

# Find recordings older than retention period
find $RECORDING_DIR -name "*.wav" -type f -mtime +$RETENTION_DAYS | while read recording; do
  filename=$(basename "$recording")
  recording_id="${filename%.*}"

  # Verify in database that this recording should be deleted
  exists=$(mysql -u$DB_USER -p$DB_PASS -N -e \
    "SELECT COUNT(*) FROM vicidial_log WHERE recording_id='$recording_id' LIMIT 1;" $DB_NAME)

  if [[ $exists -eq 0 ]]; then
    # Safe to delete
    echo "Deleting: $recording (age: $(stat -c %y $recording | cut -d' ' -f1))"
    rm "$recording"
  fi
done

Schedule in cron:

# Run daily at 2 AM
0 2 * * * /usr/local/sbin/purge-old-recordings.sh >> /var/log/purge-recordings.log 2>&1

Compression and Reencoding

For cost optimization, compress older recordings:

#!/bin/bash
# Compress recordings older than 7 days to MP3

DAYS_OLD=7
RECORDING_DIR="/var/spool/asterisk/monitor"

find $RECORDING_DIR -name "*.wav" -type f -mtime +$DAYS_OLD | while read wav_file; do
  mp3_file="${wav_file%.wav}.mp3"

  # Skip if already compressed
  [[ -f "$mp3_file" ]] && continue

  # Compress using ffmpeg at 64kbps (acceptable quality for voice)
  ffmpeg -i "$wav_file" -acodec libmp3lame -ab 64k -y "$mp3_file" 2>/dev/null

  if [[ $? -eq 0 ]]; then
    # Calculate space saved
    wav_size=$(stat -c%s "$wav_file")
    mp3_size=$(stat -c%s "$mp3_file")
    saved=$((wav_size - mp3_size))

    echo "Compressed $(basename $wav_file): saved ${saved} bytes"

    # Remove WAV after successful compression
    rm "$wav_file"
  fi
done

Typical compression results:

Original WAV (8-bit, 8kHz): 480 KB per minute
MP3 (64kbps): 480 KB per minute (same!)
MP3 (32kbps): 240 KB per minute (50% savings, lower quality)
GSM (8kbps): ~60 KB per minute (87% savings, acceptable for voice)

For best results with ViciDial, keep WAV for recent recordings (fast playback), compress to MP3 at 64kbps for 7-30 days, then archive to Glacier.

Archival Verification

Periodically verify archived recordings are recoverable:

#!/bin/bash
# Test recovery of random archived recordings

S3_BUCKET="s3://vicidial-recordings-prod"
SAMPLE_SIZE=10

# Get random sample of archived recordings
aws s3 ls $S3_BUCKET/recordings/ --recursive \
  | awk '{print $NF}' \
  | shuf -n $SAMPLE_SIZE | while read recording; do

  echo "Testing recovery of: $recording"

  # Download to temp location
  if aws s3 cp "$S3_BUCKET/$recording" /tmp/test-recovery.wav; then
    filesize=$(stat -c%s /tmp/test-recovery.wav)
    echo "✓ Successfully recovered: $recording ($filesize bytes)"
    rm /tmp/test-recovery.wav
  else
    echo "✗ FAILED to recover: $recording"
  fi
done

Monitoring and Troubleshooting

Monitoring Recording Storage

Create a monitoring script:

#!/bin/bash
# /usr/local/sbin/monitor-recording-storage.sh

RECORDING_DIR="/var/spool/asterisk/monitor"
WARNING_THRESHOLD=80  # percent full
CRITICAL_THRESHOLD=90

# Get usage percentage
usage=$(df $RECORDING_DIR | tail -1 | awk '{print $5}' | sed 's/%//')

# Count recordings by age
recent=$(find $RECORDING_DIR -name "*.wav" -type f -mtime -1 | wc -l)
week_old=$(find $RECORDING_DIR -name "*.wav" -type f -mtime +7 | wc -l)

# Size statistics
total_size=$(du -sh $RECORDING_DIR | cut -f1)

# Output metrics
echo "Recording Storage Status:"
echo "  Total: $total_size"
echo "  Usage: ${usage}%"
echo "  Recent recordings (< 1 day): $recent"
echo "  Old recordings (> 7 days): $week_old"

# Alert if threshold exceeded
if [[ $usage -gt $CRITICAL_THRESHOLD ]]; then
  echo "CRITICAL: Recording storage is $usage% full!"
  # Send alert (email, Slack, etc.)
  exit 2
elif [[ $usage -gt $WARNING_THRESHOLD ]]; then
  echo "WARNING: Recording storage is $usage% full"
  exit 1
fi

exit 0

Add to Nagios/Icinga monitoring:

# Run every 5 minutes
*/5 * * * * /usr/local/sbin/monitor-recording-storage.sh

NFS Troubleshooting

Problem: NFS mount hangs

# Check NFS server connectivity
showmount -e 192.168.1.50

# Force unmount if hung
sudo umount -f /var/spool/asterisk/monitor

# Remount with different options
sudo mount -t nfs -o soft,intr,retrans=3,timeo=15 \
  192.168.1.50:/mnt/recordings /var/spool/asterisk/monitor

Problem: Slow NFS performance

# Check client-side NFS operations
nfsstat -c

# Increase network buffers
sudo sysctl -w net.core.rmem_max=134217728
sudo sysctl -w net.core.wmem_max=134217728

# Monitor packet loss (run on client)
ping -c 100 192.168.1.50 | grep "packet loss"

Problem: Permission denied writing to NFS mount

# Verify Asterisk user can write
sudo -u asterisk touch /var/spool/asterisk/monitor/test.wav

# Check ownership and permissions
ls -ld /var/spool/asterisk/monitor
ls -ld /mnt/recordings  # on NFS server

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

S3 Troubleshooting

Problem: S3 uploads failing

# Check AWS credentials
aws sts get-caller-identity

# Test S3 bucket access
aws s3 ls s3://vicidial-recordings-prod/

# Check IAM permissions (need s3:PutObject, s3:GetObject, s3:ListBucket)
aws iam get-user-policy --user-name vicidial-s3-user --policy-name vicidial-s3-policy

Problem: S3FS mount unreliable

# Check S3FS logs
tail -f /var/log/syslog | grep s3fs

# Unmount and remount with diagnostics
sudo fusermount -u /var/spool/asterisk/monitor
s3fs -d -f vicidial-recordings-prod /var/spool/asterisk/monitor \
  -o passwd_file=~/.s3fs-credentials 2>&1 | tee /tmp/s3fs-debug.log

Asterisk CLI Monitoring

Monitor recordings in real-time via Asterisk CLI:

# Connect to Asterisk console
sudo asterisk -rx "core show channels verbose"

# Check MixMonitor status
sudo asterisk -rx "mixmonitor show"

# List active recordings
sudo asterisk -rx "mixmonitor list"

# Stop a specific recording (if needed)
sudo asterisk -rx "mixmonitor stop <call_id>"

View Asterisk recording logs:

# Follow Asterisk message log
tail -f /var/log/asterisk/messages | grep -i "mixmonitor\|recording"

Summary

Effective ViciDial recording storage requires matching your architecture to operational needs:

Use NFS when:

You have 2-10 Asterisk servers sharing recordings
You have high-bandwidth, low-latency LAN infrastructure
You need quick local playback without cloud dependency
You want simplicity without cloud account management

Use S3 when:

You need unlimited scalability
You want automatic geographic redundancy
You need cost-effective long-term archival with Glacier
You operate in multiple geographic regions
You prefer pay-as-you-go pricing over capital equipment

Best practice hybrid approach:

Record to local Asterisk storage for performance
Upload asynchronously to S3 or NFS backup
Compress and archive to Glacier after 90 days
Delete after 1-7 years per compliance requirements
Monitor storage utilization continuously
Test archival recovery monthly

Key metrics to track:

Daily recording volume (GB)
Storage utilization (%)
Upload success rate (%)
Retrieval latency (seconds)
Cost per call recorded ($/call)

Implement monitoring with appropriate alerting, test failover scenarios regularly, and review retention policies annually as call volume and compliance requirements evolve. The most sophisticated storage system is worthless if recordings cannot be recovered when needed.

Troubleshooting One-Way Audio in ViciDial / Asterisk

Moisi Trungu — Sat, 18 Jul 2026 03:30:02 +0000

Troubleshooting One-Way Audio in ViciDial / Asterisk

Learn to diagnose and resolve one-way audio issues in ViciDial and Asterisk environments, including codec mismatches, RTP problems, and ViciDial-specific configuration errors.

Prerequisites

Before starting this guide, ensure you have:

A working ViciDial installation (3.x or 4.x recommended)
SSH access to your ViciDial server with sudo privileges
Basic understanding of SIP and RTP protocols
Familiarity with Asterisk CLI commands
Access to Asterisk configuration files at /etc/asterisk/
MySQL/MariaDB access to the asterisk database
A test scenario to reproduce the one-way audio issue

Understanding One-Way Audio in ViciDial/Asterisk

One-way audio occurs when call participants can hear one direction of conversation but not the other. In ViciDial environments, this typically manifests as:

Agent hears caller, caller cannot hear agent
Caller hears agent, agent cannot hear caller
One direction is garbled, other direction is clear

The root causes in ViciDial/Asterisk deployments usually involve:

Codec mismatches between endpoints
RTP media path issues (firewall, NAT, port ranges)
SIP signaling vs. media path divergence
ViciDial bridge or transfer configuration errors
Incorrect SIP peer definitions in sip-vicidial.conf
Call recording configuration conflicts
Carrier/trunk misconfigurations

Section 1: Initial Diagnostic Steps

Check Asterisk Version and Core Status

Start by verifying your Asterisk installation is running correctly:

asterisk -rx "core show version"
asterisk -rx "core show license"
asterisk -rx "sip show status"

Expected output shows Asterisk version, licensing info, and active SIP channels. If you see zero channels or connection errors, restart Asterisk:

systemctl restart asterisk
# Wait 15 seconds
asterisk -rx "core show version"

Enable SIP/RTP Debugging

Enable verbose logging to capture the call flow. SSH into your ViciDial server and run:

asterisk -rx "sip set debug on"
asterisk -rx "rtp set debug on"
asterisk -rx "core set verbose 3"

Reproduce the one-way audio issue while these debug logs are active. Monitor the log file in real-time:

tail -f /var/log/asterisk/messages | grep -E "INVITE|SDP|RTP|Media"

Stop debugging after reproducing the issue:

asterisk -rx "sip set debug off"
asterisk -rx "rtp set debug off"

Review Call Logs in ViciDial Database

Query the vicidial_log table to find the call record:

SELECT * FROM vicidial_log 
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 10 MINUTE)
ORDER BY call_date DESC 
LIMIT 1\G

Key fields to examine:

length_in_sec - Call duration
status - Call outcome
recording_id - Whether recording was attempted
user - Agent username
carrier_id - Trunk used for the call

For more detailed call segment information:

SELECT * FROM vicidial_closer_log 
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 10 MINUTE)
ORDER BY call_date DESC 
LIMIT 1\G

Section 2: Codec Troubleshooting

Codec mismatches are the most common cause of one-way audio. ViciDial bridges calls between different endpoints, each with preferred codecs.

Identify Active Codecs

Check which codecs are allowed on your SIP peers:

asterisk -rx "sip show peer AGENTPEER detailed" | grep -i codec
asterisk -rx "sip show peer TRUNKPEER detailed" | grep -i codec

Look for output like:

Codecs (inbound): (ulaw|alaw|gsm)
Codecs (outbound): (ulaw|alaw|gsm)

Review SIP Configuration for Agent Channels

Edit your ViciDial SIP configuration:

nano /etc/asterisk/sip-vicidial.conf

Search for the agent peer definition. A typical configuration looks like:

[6001]
type=peer
host=dynamic
secret=agentpassword
context=from-internal
disallow=all
allow=ulaw
allow=alaw
allow=gsm
dtmfmode=rfc2833
nat=yes
qualify=yes

Ensure your agent device (softphone, desk phone) supports at least one of these codecs. Common issues:

Only allow=ulaw is set - But agent phone only supports opus or g729
nat=no - But agent is behind NAT, causing one-way audio
dtmfmode=info - May conflict with certain PBXes

Review Carrier/Trunk Codec Configuration

Check trunk configurations in sip-vicidial.conf or extensions-vicidial.conf:

grep -A 20 "\[carrier\|trunk" /etc/asterisk/sip-vicidial.conf | head -60

Example proper trunk peer definition:

[mycarrier]
type=peer
host=carrier.example.com
secret=carrierpassword
context=from-carrier
disallow=all
allow=ulaw
allow=alaw
fromuser=myaccount
fromdomain=carrier.example.com
insecure=port,invite
qualify=yes
nat=yes

Verify Codec Negotiation in Call Logs

After running debug, search the logs for codec negotiation:

grep -i "codec" /var/log/asterisk/messages | tail -30

Look for messages indicating codec selection or rejection:

[2024-01-15 14:23:45] Peer 'AGENTPEER' is now Reachable
[2024-01-15 14:23:52] Setting RTP codecs based on INVITE: (ulaw|alaw|gsm)
[2024-01-15 14:23:52] Answering call from AGENTPEER with codec ulaw

If you see codec mismatch messages, your trunk and agent don't share compatible codecs. Solution: Add matching codecs to both peer definitions.

Section 3: RTP and Media Path Diagnosis

RTP (Real-time Transport Protocol) carries the actual audio. One-way audio often indicates RTP flowing in only one direction.

Check RTP Port Configuration

Verify RTP port range in asterisk.conf:

grep -i "rtpstart\|rtpend" /etc/asterisk/asterisk.conf

Default configuration:

[rtp]
rtpstart=10000
rtpend=20000
tos=ef
cos=5

Ensure your firewall allows this entire range. Check current firewall rules:

sudo ufw status | grep 10000
sudo iptables -L | grep 10000

If not visible, open the RTP port range:

sudo ufw allow 10000:20000/udp
sudo firewall-cmd --add-port=10000-20000/udp --permanent
sudo firewall-cmd --reload

Diagnose NAT Issues

One-way audio frequently occurs when:

Agent is behind NAT, trunk is public - Agent can hear trunk (outbound RTP works), trunk can't hear agent (return RTP blocked)
Both behind NAT - NAT traversal needed

Check if peers are behind NAT:

asterisk -rx "sip show peer AGENTPEER" | grep -i nat
asterisk -rx "sip show peer CARRIER" | grep -i nat

Correct NAT configurations:

For agents behind NAT (typical softphone scenario):

[agentpeer]
nat=yes
directmedia=no

For carrier/trunk behind NAT:

[trunk]
nat=yes
directmedia=no

Setting directmedia=no forces Asterisk to remain in the media path, preventing direct RTP between endpoints that can't reach each other.

Analyze RTP Packet Flow

Use tcpdump to capture RTP packets during a call:

# Capture RTP from a specific source/destination
sudo tcpdump -i any -n 'udp and portrange 10000-20000' -w rtp_capture.pcap

# In another terminal, reproduce the issue and let it run for 30 seconds
# Then Ctrl+C the tcpdump

Analyze the capture with Wireshark or tshark:

tshark -r rtp_capture.pcap -f 'rtp' -Y 'rtp' | head -20

Look for:

One direction has packets, other has none - Classic one-way audio
Asymmetric packet counts - Unbalanced conversation
Packets with 0 length - Malformed RTP

Check Asterisk RTP Statistics

During an active call, check RTP status:

asterisk -rx "rtp show stats"

Output shows all active RTP streams:

RTP Stats:
  RTP Stream #1: 192.168.1.100:5060 -> 203.0.113.50:5060
    Rx Packets: 1250, Rx Bytes: 75000
    Tx Packets: 0, Tx Bytes: 0
    RTT: 45ms, Jitter: 12ms

If Rx Packets > 0 but Tx Packets = 0 (or vice versa), you have one-way audio. This indicates RTP is flowing inbound but not outbound.

Section 4: ViciDial-Specific Configuration Issues

Verify Bridge Settings in extensions-vicidial.conf

ViciDial creates bridges between agents and callers using dialplan. Check the bridge configuration:

grep -A 30 "exten => _X.,1," /etc/asterisk/extensions-vicidial.conf | head -50

Look for bridge commands like:

exten => _X.,1,Bridge(${CALLVAR},${BRIDGEOPTIONS})

Common bridge option misconfigurations:

; WRONG - No audio from agent to caller
exten => 6001,1,Bridge(SIP/agentpeer,p)

; CORRECT - Bidirectional audio with proper options
exten => 6001,1,Bridge(SIP/agentpeer,mwT)

Bridge option meanings:

m - Play music on hold while calling
w - Allow attended transfers
T - Allow DTMF transfers
p - Pass through DTMF (may break audio)

Check ViciDial Call Recording Configuration

Call recording sometimes interferes with audio paths. Check recording settings in /etc/asterisk/extensions-vicidial.conf:

grep -i "MixMonitor\|Monitor" /etc/asterisk/extensions-vicidial.conf

Verify the recording directory exists and has proper permissions:

ls -la /var/spool/asterisk/monitor/
# Should output:
# drwxr-xr-x  asterisk asterisk  /var/spool/asterisk/monitor

If recording is interfering, temporarily disable it:

# In extensions-vicidial.conf, comment out MixMonitor lines
# exten => _X.,2,MixMonitor(/var/spool/asterisk/monitor/${MIXMONITOR_FILENAME},${AUDIOHOOKS})

Restart dialplan:

asterisk -rx "dialplan reload"

Retest the call. If audio works with recording disabled, the recording configuration is the issue.

Verify Agent Channel Context

Agents connect via SIP. Verify their context points to proper dialplan:

asterisk -rx "sip show peer 6001" | grep context

Expected output:

Context: from-internal

This context must exist and contain the proper dialplan. Check it:

grep -A 20 "^\[from-internal\]" /etc/asterisk/extensions-vicidial.conf

Should contain logic to route calls to agents or queues.

Check Dialplan Variables Affecting Audio

Some ViciDial dialplan variable misconfigurations cause audio issues:

grep -i "CALLVAR\|BRIDGEOPTIONS\|AUDIOHOOKS" /etc/asterisk/extensions-vicidial.conf | head -20

These variables should be properly set before bridge execution. If missing or malformed, one-way audio results.

Section 5: Carrier and Trunk Issues

One-way audio often originates from carrier/trunk misconfiguration, especially for inbound calls.

Query ViciDial Carrier Configuration

Check configured carriers in the database:

SELECT * FROM vicidial_carrier_list WHERE carrier_active = 'Y'\G

Key fields:

carrier_name - Identifier in config
carrier_tech - Usually SIP
outbound_carrier_id - Used for outbound calls

For more details:

SELECT * FROM vicidial_carrier_log 
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 5 MINUTE)\G

Verify Trunk Peer Definition Matches Carrier Config

Find the carrier in sip-vicidial.conf:

grep -A 30 "^\[carrier_name\]" /etc/asterisk/sip-vicidial.conf

Example proper carrier definition:

[myvoipcarrier]
type=peer
host=sip.carrier.example.com
secret=carrier_auth_secret
fromuser=account_id
fromdomain=sip.carrier.example.com
context=from-carrier
disallow=all
allow=ulaw
nat=yes
directmedia=no
insecure=port,invite
qualify=yes
port=5060

Test Carrier Connectivity

Verify the trunk is registered and reachable:

asterisk -rx "sip show registry"

Expected output shows registered trunks:

Host                            Username    Refresh State       Reg.Expires ID
sip.carrier.com:5060           account_id  105     Registered  3600       0

If status is "Unregistered" or missing, the carrier configuration is incorrect. Check registration credentials:

grep -B 5 -A 15 "^\[myvoipcarrier\]" /etc/asterisk/sip-vicidial.conf | grep -E "fromuser|secret|host"

Check Carrier Audio Codecs Against Agent Codecs

This is critical. Many carriers only support ulaw. Verify:

asterisk -rx "sip show peer myvoipcarrier detailed" | grep -i codec

If carrier only supports ulaw but your agents are sending gsm, one-way audio occurs during transcoding.

Solution: Align codecs between carrier and agent peers:

[myvoipcarrier]
disallow=all
allow=ulaw
allow=alaw

[agentpeer]
disallow=all
allow=ulaw
allow=alaw

Monitor Active Trunk Calls

Check what calls are currently using trunks:

asterisk -rx "sip show channels" | grep carrier

Shows active channels:

Peer             User/ANR          Call ID              Seq (Tx/Rx)  Lag    Jitter   Time
myvoipcarrier    account_id        [call_id]            102/103      0 ms  0 ms     0:00:15

Section 6: Advanced Debugging Techniques

Capture Full SIP Trace for Single Call

Create a granular SIP trace for one specific call. First, identify an inbound number or agent:

# For agent 6001:
asterisk -rx "sip set debug peer 6001"

# For carrier trunk:
asterisk -rx "sip set debug peer myvoipcarrier"

Reproduce the issue, then immediately stop:

asterisk -rx "sip set debug off"

Extract the trace from logs:

grep "6001\|myvoipcarrier" /var/log/asterisk/messages | grep -E "INVITE|100 Trying|180 Ringing|200 OK|ACK|BYE" > /tmp/sip_trace.log
cat /tmp/sip_trace.log

Look for:

INVITE from agent - SIP setup
200 OK with SDP - Media parameters exchanged
ACK - Confirmation received
RTP port assignment in SDP - Is it the same for both directions?

Parse SDP Offers and Answers

SDP (Session Description Protocol) defines media parameters. A typical problematic SDP exchange:

Agent INVITE SDP:

m=audio 10000 RTP/AVP 0 8 3
a=rtpmap:0 PCMU/8000
a=rtpmap:8 PCMA/8000

Trunk 200 OK SDP (with mismatched port):

m=audio 15432 RTP/AVP 0

The ports differ (10000 vs 15432). If Asterisk doesn't properly manage this bridge, one-way audio results.

Enable Asterisk Memory and Resource Monitoring

One-way audio sometimes indicates resource exhaustion. Monitor during calls:

asterisk -rx "memory show summary"

Expected output:

Name                          Allocated  Freed      In Use
astobj2                       2097152    0          2097152
cache                         2097152    0          1048576
channel                       524288     0          262144

Excessive memory usage indicates a leak. Check file descriptor limits:

ulimit -n
# Increase if needed:
ulimit -n 65536

Monitor CPU usage during problematic calls:

top -p $(pgrep asterisk)
# Should show < 80% CPU for normal operation

Use Verbose Logging for Dialplan Execution

Enable verbose dialplan logging to see call flow:

asterisk -rx "core set verbose 7"

During a call, logs will show:

[2024-01-15 14:35:42] -- <SIP/agentpeer-00000001> executing [6001@from-internal:1] in new stack
[2024-01-15 14:35:42] -- Executing [6001@from-internal:1] Bridge("SIP/agentpeer-00000001", "SIP/trunk")
[2024-01-15 14:35:45] -- SIP/trunk-00000002 answered SIP/agentpeer-00000001

If the bridge fails or doesn't execute, dialplan is the issue.

Section 7: Troubleshooting Checklist

Use this systematic checklist when one-way audio is reported:

Initial Verification

[ ] Call actually exists (check vicidial_log)
[ ] Asterisk is running (asterisk -rx "core show version")
[ ] SIP and RTP are active (asterisk -rx "sip show status")

Audio Path Verification

[ ] Agent phone is receiving audio (one-way confirmed)
[ ] Caller ID displays correctly (signaling working)
[ ] Call duration shows progress (not immediate hangup)

Codec Analysis

[ ] Agent phone supports configured codec
[ ] Carrier/trunk supports same codec
[ ] No codec transcoding required
[ ] disallow=all used before allow= statements

Network and RTP

[ ] Firewall allows RTP port range (10000:20000)
[ ] No VPN or security appliances blocking RTP
[ ] NAT settings correct for peer location
[ ] RTP statistics show bidirectional packet flow

ViciDial Configuration

[ ] sip-vicidial.conf peers properly defined
[ ] extensions-vicidial.conf bridge options correct
[ ] Agent context points to proper dialplan
[ ] Recording configuration not interfering

Carrier/Trunk Verification

[ ] Trunk is registered (sip show registry)
[ ] Trunk responds to qualify checks
[ ] Trunk codec compatible with agents
[ ] Trunk definition syntax correct

Section 8: Common Scenarios and Solutions

Scenario 1: Agent Hears Caller, Caller Cannot Hear Agent

Typical Cause: Agent RTP is not reaching the carrier/external caller.

Diagnosis:

asterisk -rx "rtp show stats"
# Look for stream with Rx packets but 0 Tx packets from agent side

Solution:

Check NAT settings: asterisk -rx "sip show peer agentpeer" | grep nat
Set nat=yes and directmedia=no for agent peer
Reload SIP config: asterisk -rx "sip reload"

Scenario 2: Caller Hears Agent, Agent Cannot Hear Caller

Typical Cause: Caller RTP (from carrier) is not reaching agent.

Diagnosis:

SELECT carrier_id FROM vicidial_log 
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 5 MINUTE) LIMIT 1;

Find the carrier, then check its codec:

asterisk -rx "sip show peer [carrier_name] detailed" | grep codec

Solution:

Verify agent allows carrier's codec
Add codec to agent peer: allow=[carrier_codec]
Ensure directmedia=no on both sides

Scenario 3: Both Directions Have Audio, But Intermittent Cutouts

Typical Cause: Jitter, packet loss, or RTP port exhaustion.

Diagnosis:

# Check for port exhaustion
netstat -an | grep ESTABLISHED | wc -l
# If > 50,000, approaching limit

# Check jitter on active calls
asterisk -rx "rtp show stats" | grep -i jitter

Solution:

Increase RTP port range in asterisk.conf:

[rtp]
rtpstart=10000
rtpend=30000

Restart Asterisk
Investigate network jitter with tcpdump

Section 9: Performance Considerations

Optimize Asterisk for ViciDial Load

For high-call-volume ViciDial environments, optimize Asterisk:

# Edit /etc/asterisk/asterisk.conf
nano /etc/asterisk/asterisk.conf

Add these settings:

[options]
threadpool_initial_size=50
threadpool_max_size=500
cache_record_buffers=128
maxcalls=10000
maxload=0.9
maxfiles=65536

[rtp]
rtpstart=10000
rtpend=30000
tos=ef
cos=5
dtmf_mode=rfc2833_fax

Tune SIP Settings for Reliability

Edit /etc/asterisk/sip.conf:

[general]
# Increase retransmit timers for carrier reliability
retransmission_timer=500
max_retransmissions=6

# Improve scalability
srvlookup=yes
pedantic=no
notifyringing=yes
disallow=all
allow=ulaw
allow=alaw

# NAT settings
localnet=192.168.0.0/255.255.0.0
externip=203.0.113.50

Monitor Call Quality Metrics

Create a monitoring script to track audio issues:

#!/bin/bash
# save as /usr/local/bin/monitor_vicidial_audio.sh

while true; do
    echo "=== $(date) ==="

    # Check active calls
    ACTIVE=$(asterisk -rx "core show calls" | grep "active calls" | awk '{print $1}')
    echo "Active calls: $ACTIVE"

    # Check codec mismatches
    MISMATCHES=$(grep -c "codec mismatch" /var/log/asterisk/messages)
    echo "Codec mismatches: $MISMATCHES"

    # Check RTP errors
    RTP_ERRS=$(grep -c "RTP.*error\|RTP.*timeout" /var/log/asterisk/messages)
    echo "RTP errors: $RTP_ERRS"

    sleep 60
done

Run it:

chmod +x /usr/local/bin/monitor_vicidial_audio.sh
/usr/local/bin/monitor_vicidial_audio.sh &

Troubleshooting

Common Mistakes When Troubleshooting One-Way Audio

Mistake 1: Only reloading SIP without reloading dialplan

# WRONG - Incomplete reload
asterisk -rx "sip reload"

# CORRECT - Both modules
asterisk -rx "sip reload"
asterisk -rx "dialplan reload"

Mistake 2: Not checking both ends of the call

One-way audio is directional. You must check:

Agent peer config AND carrier peer config
Agent RTP port range AND carrier port range
Agent NAT setting AND carrier NAT setting

Mistake 3: Assuming all one-way audio has same root cause

The cause depends on direction:

Agent→Caller one-way? Check agent RTP and NAT
Caller→Agent one-way? Check carrier RTP and codec
Both intermittent? Check jitter and packet loss

Persistent One-Way Audio After Configuration Changes

If one-way audio persists after following this guide:

Full Asterisk restart (not reload):

systemctl stop asterisk
sleep 5
systemctl start asterisk

Clear SIP cache and registrations:

asterisk -rx "sip prune realtime all"
asterisk -rx "sip prune peers"

Check for conflicting configurations:

# Look for duplicate peer definitions
grep -n "^\[" /etc/asterisk/sip-vicidial.conf | grep -E "agentpeer|carrier" | sort

If duplicates exist, remove them.

Verify database consistency:

-- Check for agents with malformed SIP config
SELECT * FROM vicidial_users 
WHERE phone LIKE '%%' 
AND user_phone_type NOT IN ('SIP', 'IAX2');

Escalation: Capture full trace

If none of above resolves it, capture comprehensive data:

# Set everything to debug
asterisk -rx "sip set debug on"
asterisk -rx "rtp set debug on"
asterisk -rx "core set verbose 10"

# Let it log for 30 seconds during problem call
# Then save logs
cp /var/log/asterisk/messages /tmp/vicidial_audio_debug_$(date +%s).log

# Analyze
grep "INVITE\|200 OK\|ACK\|RTP" /tmp/vicidial_audio_debug_*.log | head -100

Summary

One-way audio in ViciDial/Asterisk environments typically results from codec mismatches, RTP path failures, or configuration errors. Use this systematic approach:

Confirm the issue with database queries and call logs
Enable debugging to see SIP and RTP flows
Check codecs on both agent and carrier peers
Verify RTP connectivity with tcpdump and packet analysis
Review ViciDial-specific bridge and dialplan configurations
Inspect carrier/trunk definitions and registration
Use advanced tools like SDP analysis and RTP statistics
Monitor continuously to prevent recurrence

The most common fixes:

Set nat=yes and directmedia=no for peers behind NAT
Align codecs between all SIP peers
Ensure firewall allows RTP port range
Verify bridge options include m, w, and T flags
Restart Asterisk (not just reload) after major config changes

With this guide and methodical debugging, you'll resolve even complex one-way audio issues in production ViciDial environments.

ViciDial Agent Screen Layout & Custom CRM Fields

Moisi Trungu — Fri, 17 Jul 2026 03:30:03 +0000

ViciDial Agent Screen Layout & Custom CRM Fields

Master the art of customizing your ViciDial agent screen interface, configuring dynamic CRM fields, and optimizing call center workflows for maximum productivity and data capture.

Prerequisites

Before diving into agent screen customization, ensure you have:

ViciDial 2.14 or higher installed and operational
Root or sudo access to your ViciDial server
MySQL/MariaDB database access with administrative privileges
Basic understanding of ViciDial user roles and permissions
Asterisk 13+ running alongside ViciDial
Direct access to /usr/src/astguiclient/ directory structure
A test campaign and test user account created
Backup of your database and configuration files

Verify your installation:

mysql -u root -p -e "SELECT VERSION();"
asterisk -rx "core show version"
ls -la /usr/src/astguiclient/

Understanding ViciDial Agent Screen Architecture

The ViciDial agent screen (/agc/vicidial.php) is the primary interface where call center agents interact with leads, manage calls, and capture customer data. The screen's layout and available fields directly impact agent efficiency and data quality.

The agent screen pulls configuration from multiple sources:

Database tables (vicidial_lists, vicidial_campaigns, custom_fields)
Campaign-specific settings
User permission levels
Script definitions
Custom field mappings

The core agent screen PHP file loads JavaScript modules that dynamically render the interface based on database queries. Every field, button, and display element can be customized through the database or direct PHP modification.

Accessing Agent Screen Configuration

Via Web Administration Panel

The primary method for most users involves the ViciDial admin panel:

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

Admin → Campaigns → Select Campaign → Agent Screen Layout

This interface provides a visual editor for reordering and enabling/disabling default fields.

Database Direct Access

For advanced customization, query the database directly:

mysql -u vicidial -p asterisk

Key tables for agent screen configuration:

-- Check campaign-specific agent screen settings
SELECT campaign_id, active, screen_layout FROM vicidial_campaigns 
WHERE campaign_name = 'YOUR_CAMPAIGN';

-- View all custom fields in the system
SELECT field_id, field_name, field_label, active FROM custom_fields 
ORDER BY field_id;

-- Check which fields are assigned to a campaign
SELECT * FROM vicidial_campaign_fields 
WHERE campaign_id = 'XXXXX';

File System Configuration

The actual agent screen PHP file is located at:

/usr/src/astguiclient/agc/vicidial.php

However, this is the compiled version. The source files are typically in:

/usr/src/astguiclient/src/

Core configuration for screen appearance:

/etc/asterisk/vicidial.conf
/usr/src/astguiclient/conf/vicidial_client.conf

Default Agent Screen Fields

ViciDial includes these standard fields by default:

Field Name	Purpose	Database Source
Lead ID	Unique lead identifier	vicidial_list.lead_id
Phone Number	Contact number	vicidial_list.phone_number
Status	Call disposition	vicidial_log.status
Name	Contact name	vicidial_list.first_name, last_name
Address	Contact address	vicidial_list.address
City/State/Zip	Location data	vicidial_list.city, state, postal_code
Email	Contact email	vicidial_list.email
Owner	Campaign owner	vicidial_campaigns.owner
Notes	Call notes	vicidial_log.notes
Call Recording	Audio link	vicidial_log.uniqueid

Creating and Managing Custom CRM Fields

Creating New Custom Fields

Access the custom fields management section:

https://your-vicidial-server/vicidial/admin.php → 
Tools → Custom Fields

Or use the database directly:

INSERT INTO custom_fields 
(field_name, field_label, field_type, active, date_created) 
VALUES 
('customer_tier', 'Customer Tier', 'SELECT', 1, NOW());

Custom field types supported:

TEXT - Single line text input
TEXTAREA - Multi-line text area
SELECT - Dropdown selection
RADIOBUTTON - Radio button group
CHECKBOX - Checkbox option
HIDDEN - Hidden field (not displayed but stored)
DATE - Date picker
DATETIME - Date and time picker
EMAIL - Email validation field
NUMERIC - Number-only input
PHONE - Phone number formatting

Practical Custom Field Examples

Example 1: Creating a Customer Tier field

INSERT INTO custom_fields 
(field_name, field_label, field_type, active, field_options, date_created) 
VALUES 
(
  'customer_tier',
  'Customer Tier',
  'SELECT',
  1,
  'Standard|Gold|Platinum',
  NOW()
);

Example 2: Creating a Previous Purchase Amount field

INSERT INTO custom_fields 
(field_name, field_label, field_type, active, date_created) 
VALUES 
('previous_purchase_amount', 'Previous Purchase Amount ($)', 'NUMERIC', 1, NOW());

Example 3: Creating a Last Contact Date field

INSERT INTO custom_fields 
(field_name, field_label, field_type, active, date_created) 
VALUES 
('last_contact_date', 'Last Contact Date', 'DATE', 1, NOW());

Example 4: Creating a Compliance Notes field

INSERT INTO custom_fields 
(field_name, field_label, field_type, active, date_created) 
VALUES 
('compliance_notes', 'Compliance Notes', 'TEXTAREA', 1, NOW());

Assigning Custom Fields to Campaigns

Once created, assign custom fields to specific campaigns:

-- Get the campaign ID
SELECT campaign_id, campaign_name FROM vicidial_campaigns 
WHERE campaign_name = 'Sales_Campaign_001';

-- Assign custom field to campaign (assuming campaign_id = 101)
INSERT INTO vicidial_campaign_fields 
(campaign_id, field_id, field_position, active, date_created) 
VALUES 
(101, (SELECT field_id FROM custom_fields WHERE field_name = 'customer_tier'), 1, 1, NOW());

Reordering Custom Fields on Agent Screen

Control field display order through the field_position column:

-- Update field positions for campaign 101
UPDATE vicidial_campaign_fields 
SET field_position = 1 
WHERE campaign_id = 101 AND field_id = (SELECT field_id FROM custom_fields WHERE field_name = 'customer_tier');

UPDATE vicidial_campaign_fields 
SET field_position = 2 
WHERE campaign_id = 101 AND field_id = (SELECT field_id FROM custom_fields WHERE field_name = 'previous_purchase_amount');

UPDATE vicidial_campaign_fields 
SET field_position = 3 
WHERE campaign_id = 101 AND field_id = (SELECT field_id FROM custom_fields WHERE field_name = 'last_contact_date');

Modifying Agent Screen Layout via PHP

Understanding the Agent Screen Rendering

The agent screen is primarily rendered by /usr/src/astguiclient/agc/vicidial.php. This file queries the database and generates HTML/JavaScript dynamically.

To customize the agent screen layout directly in PHP, you'll need to work with the source files:

cd /usr/src/astguiclient/
# Backup original
cp agc/vicidial.php agc/vicidial.php.backup

# Edit the file
nano agc/vicidial.php

Example: Adding a Custom Section to the Agent Screen

Most customizations involve modifying sections where lead data is displayed. The typical structure includes a form that displays lead information.

Find the section where lead fields are rendered:

// Typical structure in vicidial.php
// Around line 2000-3000, you'll find the HTML form construction

// Example of adding a custom section after the standard fields
?>
<!-- Custom CRM Section -->
<table class="customcrmtable" width="100%">
<tr>
<td class="label">Customer Tier:</td>
<td><input type="text" name="customer_tier" id="customer_tier" maxlength="50" size="30" /></td>
</tr>
<tr>
<td class="label">Previous Purchase:</td>
<td><input type="text" name="previous_purchase_amount" id="previous_purchase_amount" maxlength="10" size="30" /></td>
</tr>
</table>
<?php

Adding JavaScript to Populate Custom Fields

When a lead is loaded, custom fields should be populated from the database. Add JavaScript to handle this:

// Add this to vicidial.php JavaScript section
function populate_custom_fields(lead_id) {
    $.ajax({
        type: "POST",
        url: "/agc/ajax_load_custom_fields.php",
        data: {
            lead_id: lead_id,
            action: "get_custom_fields"
        },
        success: function(response) {
            var fields = JSON.parse(response);

            if (fields.customer_tier) {
                document.getElementById('customer_tier').value = fields.customer_tier;
            }
            if (fields.previous_purchase_amount) {
                document.getElementById('previous_purchase_amount').value = fields.previous_purchase_amount;
            }
            if (fields.last_contact_date) {
                document.getElementById('last_contact_date').value = fields.last_contact_date;
            }
        }
    });
}

Creating Backend PHP Scripts for Custom Field Handling

Creating AJAX Handler for Custom Fields

Create a new PHP file to handle custom field operations:

nano /usr/src/astguiclient/agc/ajax_load_custom_fields.php

<?php
// ajax_load_custom_fields.php - Handle custom field loading and saving

// Include ViciDial configuration
require_once('/usr/src/astguiclient/conf/vicidial_client.conf');

// Get database connection details from config
$DB_server = '127.0.0.1';
$DB_user = 'vicidial';
$DB_password = getenv('DB_PASSWORD') ?: 'password';
$DB_name = 'asterisk';

// Connect to database
$mysqli = new mysqli($DB_server, $DB_user, $DB_password, $DB_name);
if ($mysqli->connect_error) {
    die(json_encode(['error' => 'Database connection failed']));
}

$action = isset($_POST['action']) ? $_POST['action'] : '';
$lead_id = isset($_POST['lead_id']) ? intval($_POST['lead_id']) : 0;

if ($action === 'get_custom_fields' && $lead_id > 0) {
    $query = "
        SELECT field_name, field_value 
        FROM vicidial_custom_field_data 
        WHERE lead_id = ?
    ";

    $stmt = $mysqli->prepare($query);
    $stmt->bind_param('i', $lead_id);
    $stmt->execute();
    $result = $stmt->get_result();

    $fields = [];
    while ($row = $result->fetch_assoc()) {
        $fields[$row['field_name']] = $row['field_value'];
    }

    echo json_encode($fields);
    $stmt->close();
}
elseif ($action === 'save_custom_fields' && $lead_id > 0) {
    $field_name = isset($_POST['field_name']) ? $_POST['field_name'] : '';
    $field_value = isset($_POST['field_value']) ? $_POST['field_value'] : '';

    // Check if record exists
    $check_query = "
        SELECT id FROM vicidial_custom_field_data 
        WHERE lead_id = ? AND field_name = ?
    ";

    $check_stmt = $mysqli->prepare($check_query);
    $check_stmt->bind_param('is', $lead_id, $field_name);
    $check_stmt->execute();
    $check_result = $check_stmt->get_result();

    if ($check_result->num_rows > 0) {
        // Update existing
        $update_query = "
            UPDATE vicidial_custom_field_data 
            SET field_value = ?, date_modified = NOW()
            WHERE lead_id = ? AND field_name = ?
        ";

        $update_stmt = $mysqli->prepare($update_query);
        $update_stmt->bind_param('sis', $field_value, $lead_id, $field_name);
        $update_stmt->execute();
        echo json_encode(['status' => 'updated']);
        $update_stmt->close();
    } else {
        // Insert new
        $insert_query = "
            INSERT INTO vicidial_custom_field_data 
            (lead_id, field_name, field_value, date_created) 
            VALUES (?, ?, ?, NOW())
        ";

        $insert_stmt = $mysqli->prepare($insert_query);
        $insert_stmt->bind_param('iss', $lead_id, $field_name, $field_value);
        $insert_stmt->execute();
        echo json_encode(['status' => 'inserted']);
        $insert_stmt->close();
    }

    $check_stmt->close();
}

$mysqli->close();
?>

Ensuring Custom Field Data Table Exists

Create the custom field data storage table if it doesn't exist:

CREATE TABLE IF NOT EXISTS vicidial_custom_field_data (
    id INT AUTO_INCREMENT PRIMARY KEY,
    lead_id INT NOT NULL,
    field_name VARCHAR(100) NOT NULL,
    field_value LONGTEXT,
    date_created DATETIME DEFAULT CURRENT_TIMESTAMP,
    date_modified DATETIME ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_lead_id (lead_id),
    INDEX idx_field_name (field_name),
    UNIQUE KEY unique_lead_field (lead_id, field_name)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Advanced Agent Screen Customization

Conditional Field Display Based on Campaign

Display different custom fields depending on which campaign is active:

// In vicidial.php, after loading campaign info
$campaign_id = $_REQUEST['campaign_id'];

$campaign_query = "
    SELECT vcf.field_id, cf.field_name, cf.field_label, cf.field_type
    FROM vicidial_campaign_fields vcf
    JOIN custom_fields cf ON vcf.field_id = cf.field_id
    WHERE vcf.campaign_id = ? AND vcf.active = 1
    ORDER BY vcf.field_position ASC
";

$stmt = $mysqli->prepare($campaign_query);
$stmt->bind_param('i', $campaign_id);
$stmt->execute();
$result = $stmt->get_result();

$custom_fields_html = '';
while ($row = $result->fetch_assoc()) {
    $custom_fields_html .= render_field($row);
}

echo $custom_fields_html;

Creating Dynamic Field Dependencies

Make certain fields appear/disappear based on other field values:

// Add to vicidial.php JavaScript section
document.getElementById('customer_tier').addEventListener('change', function() {
    var tier = this.value;

    if (tier === 'Platinum') {
        // Show VIP fields
        document.getElementById('previous_purchase_amount').parentElement.parentElement.style.display = 'table-row';
        document.getElementById('vip_notes').parentElement.parentElement.style.display = 'table-row';
    } else {
        // Hide VIP fields
        document.getElementById('previous_purchase_amount').parentElement.parentElement.style.display = 'none';
        document.getElementById('vip_notes').parentElement.parentElement.style.display = 'none';
    }
});

Custom Screen Layout Presets

Create multiple screen layout configurations for different agent types:

-- Create layout preference table
CREATE TABLE IF NOT EXISTS agent_screen_layouts (
    layout_id INT AUTO_INCREMENT PRIMARY KEY,
    layout_name VARCHAR(100) NOT NULL,
    layout_description TEXT,
    campaign_id INT,
    user_group VARCHAR(50),
    field_configuration JSON,
    active TINYINT DEFAULT 1,
    date_created DATETIME DEFAULT CURRENT_TIMESTAMP,
    date_modified DATETIME ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- Insert preset layouts
INSERT INTO agent_screen_layouts 
(layout_name, campaign_id, user_group, field_configuration, active) 
VALUES 
(
    'Sales Agent Layout',
    101,
    'SALES',
    '[{"field":"customer_tier","position":1,"visible":true},{"field":"previous_purchase_amount","position":2,"visible":true}]',
    1
);

INSERT INTO agent_screen_layouts 
(layout_name, campaign_id, user_group, field_configuration, active) 
VALUES 
(
    'Support Agent Layout',
    102,
    'SUPPORT',
    '[{"field":"issue_type","position":1,"visible":true},{"field":"priority","position":2,"visible":true}]',
    1
);

Configuring Custom Field Validation

Adding Server-Side Validation

In your AJAX handler, add validation logic:

// In ajax_load_custom_fields.php, add validation function
function validate_custom_field($field_name, $field_value, $field_type) {
    switch($field_type) {
        case 'NUMERIC':
            if (!is_numeric($field_value)) {
                return ['valid' => false, 'error' => 'Field must be numeric'];
            }
            break;
        case 'EMAIL':
            if (!filter_var($field_value, FILTER_VALIDATE_EMAIL)) {
                return ['valid' => false, 'error' => 'Invalid email format'];
            }
            break;
        case 'PHONE':
            // Basic phone validation
            $phone_clean = preg_replace('/[^0-9]/', '', $field_value);
            if (strlen($phone_clean) < 10) {
                return ['valid' => false, 'error' => 'Phone number too short'];
            }
            break;
        case 'DATE':
            if (!strtotime($field_value)) {
                return ['valid' => false, 'error' => 'Invalid date format'];
            }
            break;
    }

    return ['valid' => true];
}

// Use in save operation
if ($action === 'save_custom_fields') {
    // Get field type first
    $type_query = "SELECT field_type FROM custom_fields WHERE field_name = ?";
    $type_stmt = $mysqli->prepare($type_query);
    $type_stmt->bind_param('s', $field_name);
    $type_stmt->execute();
    $type_result = $type_stmt->get_result();
    $type_row = $type_result->fetch_assoc();

    // Validate
    $validation = validate_custom_field($field_name, $field_value, $type_row['field_type']);
    if (!$validation['valid']) {
        echo json_encode(['status' => 'error', 'error' => $validation['error']]);
        exit;
    }

    // Proceed with save...
}

Client-Side Validation with JavaScript

// Add to agent screen JavaScript
function validate_field_before_save(field_name, field_value, field_type) {
    switch(field_type) {
        case 'NUMERIC':
            if (isNaN(field_value)) {
                alert('Please enter a valid number');
                return false;
            }
            break;
        case 'EMAIL':
            var email_pattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
            if (!email_pattern.test(field_value)) {
                alert('Please enter a valid email address');
                return false;
            }
            break;
        case 'PHONE':
            var phone_clean = field_value.replace(/[^0-9]/g, '');
            if (phone_clean.length < 10) {
                alert('Phone number must be at least 10 digits');
                return false;
            }
            break;
    }
    return true;
}

Performance Optimization for Custom Fields

Indexing Custom Field Tables

Ensure database queries remain fast with proper indexing:

-- Optimize custom_fields table
ALTER TABLE custom_fields 
ADD INDEX idx_field_name (field_name),
ADD INDEX idx_active (active);

-- Optimize custom field data table
ALTER TABLE vicidial_custom_field_data 
ADD INDEX idx_lead_field (lead_id, field_name),
ADD INDEX idx_modified (date_modified);

Caching Custom Field Configuration

Implement caching to reduce database queries:

// In vicidial.php or shared include file
function get_campaign_custom_fields_cached($campaign_id) {
    $cache_key = "campaign_fields_{$campaign_id}";

    // Try to get from APC/APCu cache
    if (extension_loaded('apc')) {
        $cached = apc_fetch($cache_key);
        if ($cached !== false) {
            return $cached;
        }
    }

    // Query database
    $query = "
        SELECT cf.field_id, cf.field_name, cf.field_label, cf.field_type
        FROM vicidial_campaign_fields vcf
        JOIN custom_fields cf ON vcf.field_id = cf.field_id
        WHERE vcf.campaign_id = ? AND vcf.active = 1
        ORDER BY vcf.field_position ASC
    ";

    global $mysqli;
    $stmt = $mysqli->prepare($query);
    $stmt->bind_param('i', $campaign_id);
    $stmt->execute();
    $result = $stmt->get_result();

    $fields = [];
    while ($row = $result->fetch_assoc()) {
        $fields[] = $row;
    }

    // Store in cache for 1 hour
    if (extension_loaded('apc')) {
        apc_store($cache_key, $fields, 3600);
    }

    return $fields;
}

Integrating with External CRM Systems

Syncing Custom Fields to External CRM

Create a background job to sync ViciDial custom fields to external systems:

// /usr/src/astguiclient/cronjobs/sync_crm_fields.php
<?php
set_time_limit(300);

require_once('/usr/src/astguiclient/conf/vicidial_client.conf');

$mysqli = new mysqli('127.0.0.1', 'vicidial', 'password', 'asterisk');

// Get all leads with modified custom fields
$query = "
    SELECT DISTINCT vcfd.lead_id, vcfd.field_name, vcfd.field_value
    FROM vicidial_custom_field_data vcfd
    JOIN vicidial_list vl ON vcfd.lead_id = vl.lead_id
    WHERE vcfd.date_modified >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
    ORDER BY vcfd.lead_id
";

$result = $mysqli->query($query);

while ($row = $result->fetch_assoc()) {
    $lead_id = $row['lead_id'];
    $field_name = $row['field_name'];
    $field_value = $row['field_value'];

    // Send to external CRM API
    send_to_external_crm($lead_id, $field_name, $field_value);
}

function send_to_external_crm($lead_id, $field_name, $field_value) {
    $crm_api_url = 'https://api.externalcrm.com/leads/update';
    $crm_api_key = getenv('CRM_API_KEY');

    $data = [
        'lead_id' => $lead_id,
        'field_name' => $field_name,
        'field_value' => $field_value
    ];

    $ch = curl_init($crm_api_url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $crm_api_key,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

    $response = curl_exec($ch);
    curl_close($ch);

    return $response;
}
?>

Schedule this with cron:

# Add to crontab for vicidial user
*/15 * * * * /usr/bin/php /usr/src/astguiclient/cronjobs/sync_crm_fields.php

Troubleshooting Agent Screen Issues

Custom Fields Not Appearing on Agent Screen

Problem: Custom fields are created but don't show on the agent screen.

Solution:

Verify fields are assigned to the campaign:

SELECT * FROM vicidial_campaign_fields 
WHERE campaign_id = YOUR_CAMPAIGN_ID AND active = 1;

Check if custom fields table exists:

SHOW TABLES LIKE 'custom_fields';
SHOW TABLES LIKE 'vicidial_custom_field_data';

Clear browser cache and refresh agent screen
Check Asterisk logs:

tail -f /var/log/asterisk/messages | grep -i "custom\|field"

Custom Field Data Not Saving

Problem: Agent enters data in custom fields but it doesn't persist.

Solution:

Verify AJAX script exists:

ls -la /usr/src/astguiclient/agc/ajax_load_custom_fields.php

Check database permissions:

mysql -u root -p asterisk
SHOW GRANTS FOR 'vicidial'@'localhost';

Verify custom field data table structure:

DESCRIBE vicidial_custom_field_data;

Check browser console for JavaScript errors (F12)
Verify PHP error logging is enabled:

grep -i "error_log\|display_errors" /etc/php.ini
tail -f /var/log/php-errors.log

Agent Screen Slow Performance with Many Custom Fields

Problem: Agent screen loads slowly when many custom fields are present.

Solution:

Check if custom fields are properly indexed:

SHOW INDEX FROM custom_fields;
SHOW INDEX FROM vicidial_custom_field_data;

Add missing indexes:

ALTER TABLE vicidial_custom_field_data 
ADD INDEX idx_lead_id (lead_id);

Limit fields loaded per campaign - don't load unused fields:

-- Disable inactive fields
UPDATE vicidial_campaign_fields 
SET active = 0 
WHERE campaign_id = YOUR_CAMPAIGN_ID AND active = 1 
LIMIT (SELECT COUNT(*)-10 FROM vicidial_campaign_fields);

Enable query caching in MySQL:

mysql -u root -p
SET GLOBAL query_cache_type = ON;
SET GLOBAL query_cache_size = 268435456;

JavaScript Errors on Agent Screen

Problem: Browser console shows JavaScript errors related to custom fields.

Solution:

Check if jQuery is loaded properly:

// Open browser console and run
console.log(typeof jQuery);

Verify AJAX endpoint returns valid JSON:

curl -X POST http://localhost/agc/ajax_load_custom_fields.php \
  -d "action=get_custom_fields&lead_id=12345"

Add error handling to AJAX calls:

$.ajax({
    type: "POST",
    url: "/agc/ajax_load_custom_fields.php",
    data: {lead_id: lead_id, action: "get_custom_fields"},
    dataType: "json",
    error: function(xhr, status, error) {
        console.error("AJAX Error: " + error);
        console.error("Response: " + xhr.responseText);
    }
});

Custom Field Values Displaying Incorrectly

Problem: Custom field values show strange characters or encoding issues.

Solution:

Verify database character encoding:

SHOW CREATE TABLE vicidial_custom_field_data;
-- Should show DEFAULT CHARSET=utf8mb4

Fix encoding if needed:

ALTER TABLE vicidial_custom_field_data 
CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Ensure PHP file has UTF-8 header:

header('Content-Type: application/json; charset=utf-8');

Check field_value column type supports required length:

DESCRIBE vicidial_custom_field_data;
-- field_value should be LONGTEXT or TEXT

Summary

Mastering ViciDial agent screen customization and custom CRM fields provides significant advantages:

Key Takeaways:

Agent Screen Architecture - Understand that the agent screen draws from multiple database sources and can be customized both through the admin panel and direct PHP/database modifications.
Custom Fields Foundation - Create custom fields through the admin interface or database inserts, then assign them to campaigns with proper positioning.
Data Storage - Implement a dedicated custom field data table (vicidial_custom_field_data) for storing field values per lead, enabling scalability and efficiency.
AJAX Integration - Build backend PHP scripts that handle field loading and saving asynchronously, providing a responsive agent experience.
Validation - Implement both client-side JavaScript and server-side PHP validation to ensure data quality and prevent invalid entries.
Performance - Index tables properly, implement caching strategies, and avoid loading unnecessary fields to maintain agent screen responsiveness.
External Integration - Create cronjobs to sync custom fields with external CRM systems, enabling unified customer data across platforms.
Troubleshooting - Systematically verify database structure, permissions, JavaScript errors, and encoding issues when problems arise.

The agent screen is the core of agent productivity. By investing time in proper customization, validation, and optimization, you create an environment where agents work efficiently while capturing high-quality data that drives business intelligence and customer relationship management.

Always backup your database before making structural changes, and test customizations in a staging environment before deploying to production. Monitor performance metrics after implementing custom fields, and use database indexes strategically to maintain responsiveness as your custom field data grows.

Asterisk Voicemail System — Setup, Email Integration & IVR

Moisi Trungu — Thu, 16 Jul 2026 03:30:03 +0000

Asterisk Voicemail System — Setup, Email Integration & IVR

Learn to configure production-grade voicemail in Asterisk with email notifications, custom greetings, transcription, and IVR routing for ViciDial environments.

Prerequisites

Before starting this tutorial, ensure you have:

Asterisk 13.x or higher installed and running (ViciDial typically runs 11.x through 16.x)
Root or sudo access to your Asterisk server
MySQL/MariaDB with an existing Asterisk database (vicidial user with appropriate permissions)
Postfix or Exim mail server configured and tested
sox and mailx utilities installed for audio handling and mail delivery
Asterisk source code downloaded (for custom modules if needed)
ViciDial version 2.12+ (if integrating with ViciDial's agent interface)
Working SIP extensions or IAX2 trunks configured
Basic understanding of Asterisk dialplan syntax and Linux command line

Verify Asterisk is running:

sudo asterisk -rx "core show version"
sudo systemctl status asterisk

Understanding Asterisk Voicemail Architecture

Asterisk voicemail operates through the app_voicemail module, which stores voicemail messages in the filesystem (typically /var/spool/asterisk/voicemail/) and maintains metadata in Asterisk's astdb or via ODBC connectivity.

The complete voicemail flow:

Call arrives → matches voicemail extension in dialplan
Answer and greeting → plays custom or default greeting
Record message → stores to filesystem with timestamp
Notification → triggers email dispatch via MTA
Retrieval → agent retrieves via *98 or IVR menu
Archive → system moves old messages or deletes per policy

In ViciDial environments, voicemail ties directly to the vicidial_users table and can be correlated with vicidial_log entries for compliance and reporting.

Section 1: Core Voicemail Configuration

Installing and Enabling app_voicemail

Verify app_voicemail is compiled:

sudo asterisk -rx "module show like voicemail"

If not loaded:

sudo asterisk -rx "module load app_voicemail"

To make it persistent across restarts, edit /etc/asterisk/modules.conf:

[modules]
autoload=yes

; Specific voicemail module
load => app_voicemail.so
load => res_adsi.so
load => res_smdi.so

Creating the Voicemail Context

Edit /etc/asterisk/voicemail.conf to define voicemail boxes and contexts:

[general]
; Format for storing voicemail
format=wav49|gsm|wav
; Maximum message length in seconds (600 = 10 minutes)
maxmessage=600
minmessage=3
; Silence threshold (in milliseconds)
silencethreshold=128
; Number of seconds of silence to end message
maxsilence=10
; Email notification settings
serveremail=asterisk@yourdomain.com
fromstring=ViciDial Voicemail
emaildateformat=%A, %B %d, %Y at %l:%M %p
attachvolumeenvelope=yes
attach=yes
; Envelope format and headers
emailsubject=You have a voicemail message from ${VM_CALLERID}
emailbody=Dear ${VM_NAME},\n\nYou have received a new voicemail message from ${VM_CALLERID}.\n\nMessage length: ${VM_DUR} seconds\nReceived: ${VM_DATE}\n\nPlease retrieve your message at your earliest convenience.\n\nViciDial Team

[vicidial_context]
; Mailbox format: mailbox=>password,fullname,email,pager_email,options
; Options include: u(unavail), b(busy), t(tempgreeting), g(greeting)
6001=>9999,Agent Smith,agent.smith@company.com,,uj(voicemail-inactive)
6002=>8888,Agent Jones,agent.jones@company.com,,uj(voicemail-inactive)
6003=>7777,Agent Brown,agent.brown@company.com,,u
; Bulk add for 100 users (6100-6199)
6100=>1111,Sales Agent 100,sales100@company.com
6101=>1111,Sales Agent 101,sales101@company.com

The format breakdown:

mailbox = voicemail extension (typically matches SIP extension)
password = digit code to access voicemail
fullname = announced name for callers
email = primary notification recipient
pager_email = secondary recipient (often mobile)
options = flags for unavailable (u), busy (b), temporary greeting (t), greeting recorded (g)

Linking ViciDial Users to Voicemail

ViciDial's vicidial_users table has voicemail integration points. Query the schema:

SHOW COLUMNS FROM vicidial_users LIKE '%voicemail%';

If your ViciDial version supports it, you'll see fields like voicemail_ext or vm_enabled. Alternatively, create a mapping table:

CREATE TABLE IF NOT EXISTS vicidial_voicemail_map (
  user_id INT NOT NULL PRIMARY KEY,
  vm_ext VARCHAR(10),
  vm_password VARCHAR(10),
  vm_email VARCHAR(100),
  vm_enabled ENUM('Y','N') DEFAULT 'Y',
  INDEX idx_user_id (user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Populate it:

INSERT INTO vicidial_voicemail_map (user_id, vm_ext, vm_password, vm_email, vm_enabled)
SELECT user_id, extension, '9999', email, 'Y' 
FROM vicidial_users 
WHERE user_status='ACTIVE' AND role='AGENT';

Section 2: Dialplan Integration & IVR Routing

Creating the Voicemail Dialplan Context

Edit /etc/asterisk/extensions-vicidial.conf and add a dedicated voicemail context:

[voicemail-context]
; Main voicemail entry point
exten => s,1,Verbose(2,Entering voicemail context from ${CALLERID(num)})
exten => s,n,Set(VM_CONTEXT=vicidial_context)
exten => s,n,Playback(vm-welcome,noanswer)
exten => s,n,VoiceMail(${EXTEN}@${VM_CONTEXT},u)
exten => s,n,Hangup()

; Voicemail menu for agents (*98 access)
[voicemail-main-menu]
exten => s,1,NoOp(Voicemail Main Menu for ${CALLERID(num)})
exten => s,n,Set(ATTEMPT=0)
exten => s,n(authenticate)
exten => s,n,Set(ATTEMPT=$[${ATTEMPT} + 1])
exten => s,n,Playback(vm-login,noanswer)
exten => s,n,Read(VMBOX,vm-enter-id,5)
exten => s,n,Read(VMPASS,vm-enter-password,5)
exten => s,n,VoiceMailMain(${VMBOX}@${VM_CONTEXT})
exten => s,n,Hangup()

; Access voicemail directly with extension
exten => _610[0-9],1,NoOp(Direct voicemail for ${EXTEN})
exten => _610[0-9],n,VoiceMail(${EXTEN}@vicidial_context,u)
exten => _610[0-9],n,Hangup()

; Fallback for invalid extensions
exten => i,1,Playback(invalid,noanswer)
exten => i,n,Hangup()

IVR-Based Voicemail Routing

For more sophisticated call routing, create an IVR menu that directs calls to agent voicemail or live queue:

[vicidial-ivr-main]
exten => s,1,NoOp(=== ViciDial IVR Entry ===)
exten => s,n,Set(CHANNEL(language)=en)
exten => s,n,Playback(vm-goodbye,noanswer)
exten => s,n(menu)
exten => s,n,Playback(press-1-for-sales,noanswer)
exten => s,n,Playback(press-2-for-support,noanswer)
exten => s,n,Playback(press-0-operator,noanswer)
exten => s,n,WaitExten(5)

exten => 1,1,NoOp(=== Sales Queue ===)
exten => 1,n,Queue(sales_queue,t,,,300)
exten => 1,n,VoiceMail(6100@vicidial_context,u)
exten => 1,n,Hangup()

exten => 2,1,NoOp(=== Support Queue ===)
exten => 2,n,Queue(support_queue,t,,,300)
exten => 2,n,VoiceMail(6200@vicidial_context,u)
exten => 2,n,Hangup()

exten => 0,1,NoOp(=== Operator Transfer ===)
exten => 0,n,Dial(SIP/6001,20)
exten => 0,n,VoiceMail(6001@vicidial_context,b)
exten => 0,n,Hangup()

exten => t,1,Playback(vm-goodbye,noanswer)
exten => t,n,Hangup()

exten => i,1,Playback(invalid,noanswer)
exten => i,n,Goto(s,menu)

Assign this context to your inbound trunk in sip.conf or SIP configuration:

[my_carrier_trunk]
type=peer
context=vicidial-ivr-main
host=carrier.example.com
insecure=invite

Section 3: Email Integration & Notifications

Configuring Postfix for Voicemail Delivery

Ensure Postfix is installed and running:

sudo apt-get install postfix mailutils
sudo systemctl start postfix
sudo systemctl enable postfix

Test mail delivery:

echo "Test message" | mail -s "Test" youremail@example.com

Advanced Voicemail Email Configuration

Update /etc/asterisk/voicemail.conf with full email settings:

[general]
; Email delivery
serveremail=asterisk@yourdomain.com
fromstring=ViciDial Voicemail System
emaildateformat=%A, %B %d, %Y at %l:%M %p

; Attach voicemail as audio file
attach=yes
attachvolumeenvelope=yes

; Audio formats to attach (most compatible first)
format=wav49|gsm|wav

; Email body templates
emailsubject=Voicemail: ${VM_CALLERID} - ${VM_DATE}
emailbody=Dear ${VM_NAME},\n\nYou have a voicemail message.\n\nCaller: ${VM_CALLERID}\nLength: ${VM_DUR} seconds\nReceived: ${VM_DATE}\nBox: ${VM_MAILBOX}\n\nTo retrieve: Dial *98 and enter your voicemail password.\n\nViciDial System

; Pager/SMS format (text-only)
pagerfromstring=ViciDial Alerts
pagersubject=VM from ${VM_CALLERID}
pagerbody=${VM_NAME}, new voicemail from ${VM_CALLERID} (${VM_DUR}s) at ${VM_DATE}

; Maximum email size (prevent bloat)
volgain=0
emaildateformat=%A, %B %d, %Y at %l:%M %p

[vicidial_context]
; Per-mailbox override
6001=>9999,Agent Smith,smith@company.com,smith.mobile@sms.example.com,uj
6002=>8888,Agent Jones,jones@company.com,,u

Custom Email Handler Script

For advanced processing (transcription, CRM integration), create /usr/local/bin/voicemail-handler.sh:

#!/bin/bash

# ViciDial Voicemail Handler Script
# Called by Asterisk after voicemail recording

VMBOX="$1"
CONTEXT="$2"
MAILBOX_DIR="/var/spool/asterisk/voicemail/${CONTEXT}/${VMBOX}"
CALLERID="$3"
DURATION="$4"

# Logging
LOG_FILE="/var/log/asterisk/voicemail-handler.log"
echo "$(date '+%Y-%m-%d %H:%M:%S') - Processing VM: Box=$VMBOX, Caller=$CALLERID, Duration=$DURATION" >> "$LOG_FILE"

# Get most recent message
LATEST_MSG=$(ls -t "$MAILBOX_DIR/new/"*.wav 2>/dev/null | head -1)

if [ -z "$LATEST_MSG" ]; then
    echo "$(date '+%Y-%m-%d %H:%M:%S') - ERROR: No message found for $VMBOX" >> "$LOG_FILE"
    exit 1
fi

# Convert to MP3 (optional, requires sox)
if command -v sox &> /dev/null; then
    MP3_FILE="${LATEST_MSG%.wav}.mp3"
    sox "$LATEST_MSG" -C 128 "$MP3_FILE" 2>> "$LOG_FILE"
    ATTACH_FILE="$MP3_FILE"
else
    ATTACH_FILE="$LATEST_MSG"
fi

# Query ViciDial database for mailbox owner info
AGENT_EMAIL=$(mysql -u asterisk -pasterisk asterisk -N -e \
    "SELECT email FROM vicidial_users WHERE extension='$VMBOX' LIMIT 1;" 2>/dev/null)

if [ -z "$AGENT_EMAIL" ]; then
    echo "$(date '+%Y-%m-%d %H:%M:%S') - WARNING: No email found for extension $VMBOX" >> "$LOG_FILE"
    exit 1
fi

# Send email with attachment
MAIL_SUBJECT="Voicemail from $CALLERID (${DURATION}s)"
MAIL_BODY="You have a new voicemail message.\n\nCaller: $CALLERID\nDuration: ${DURATION} seconds\nReceived: $(date '+%Y-%m-%d %H:%M:%S')\n\nPlease see attached audio file."

echo -e "$MAIL_BODY" | mutt -s "$MAIL_SUBJECT" -a "$ATTACH_FILE" -- "$AGENT_EMAIL" 2>> "$LOG_FILE"

echo "$(date '+%Y-%m-%d %H:%M:%S') - Email sent to $AGENT_EMAIL" >> "$LOG_FILE"

exit 0

Make it executable and update Asterisk to call it:

sudo chmod +x /usr/local/bin/voicemail-handler.sh

[general]
; Call external script after voicemail saved
; Note: This requires res_voicemail compiled with SENDMAIL support
mailcmd=/usr/local/bin/voicemail-handler.sh

ODBC-Based Voicemail Storage (Alternative)

For high-volume environments, store voicemail metadata in MySQL instead of astdb:

Create the table:

CREATE TABLE asterisk.voicemail_msgs (
  id INT AUTO_INCREMENT PRIMARY KEY,
  context VARCHAR(50),
  mailbox VARCHAR(50),
  callerid VARCHAR(50),
  duration INT,
  message_date DATETIME,
  is_read ENUM('Y','N') DEFAULT 'N',
  INDEX idx_context_mailbox (context, mailbox),
  INDEX idx_date (message_date)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Configure ODBC in /etc/asterisk/res_odbc.conf:

[asterisk]
dsn=asterisk
username=asterisk
password=asterisk
pooling=yes
limit=10

Update voicemail.conf to use ODBC:

[general]
; Enable ODBC support
odbcstorage=asterisk
odbctable=voicemail_msgs

Section 4: Agent Retrieval Interface

Enabling *98 Voicemail Access

Add to your main extension context in extensions-vicidial.conf:

[vicidial-agents]
; Agent voicemail retrieval (*98)
exten => 98,1,NoOp(Voicemail retrieval initiated by ${CALLERID(num)})
exten => 98,n,Authenticate(${EXTEN})
exten => 98,n,VoiceMailMain(@vicidial_context)
exten => 98,n,Hangup()

; Record temporary greeting (*99)
exten => 99,1,NoOp(Recording temporary greeting)
exten => 99,n,VoiceMailMain(${CALLERID(num)}@vicidial_context,t)
exten => 99,n,Hangup()

Include this context in your SIP extensions:

[6000-6299](vicidial_agent)
type=friend
context=vicidial-agents
disallow=all
allow=ulaw,gsm

Web-Based Voicemail Retrieval for ViciDial

Add a custom PHP interface at /var/www/html/vicidial/voicemail.php:

<?php
// ViciDial Web Voicemail Interface
session_start();

// Verify agent is logged in
if (!isset($_SESSION['user_id'])) {
    header("Location: index.php");
    exit;
}

$user_id = $_SESSION['user_id'];
$user_extension = $_SESSION['extension'];

// Database connection
$db = new mysqli("localhost", "asterisk", "asterisk", "asterisk");
if ($db->connect_error) {
    die("Database connection failed: " . $db->connect_error);
}

// Retrieve voicemail boxes for user
$query = "SELECT vm_ext, vm_email FROM vicidial_voicemail_map WHERE user_id = ?";
$stmt = $db->prepare($query);
$stmt->bind_param("i", $user_id);
$stmt->execute();
$result = $stmt->get_result();

?>
<!DOCTYPE html>
<html>
<head>
    <title>Voicemail Manager</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 20px; }
        .vm-box { border: 1px solid #ccc; padding: 10px; margin: 10px 0; }
        .controls { margin: 10px 0; }
        button { padding: 8px 15px; cursor: pointer; }
    </style>
</head>
<body>
    <h2>Voicemail Manager</h2>

    <?php
    if ($result->num_rows > 0) {
        while ($row = $result->fetch_assoc()) {
            ?>
            <div class="vm-box">
                <h3>Extension <?php echo htmlspecialchars($row['vm_ext']); ?></h3>
                <p>Email: <?php echo htmlspecialchars($row['vm_email']); ?></p>
                <div class="controls">
                    <button onclick="accessVoicemail('<?php echo $row['vm_ext']; ?>')">
                        Access Voicemail
                    </button>
                    <button onclick="recordGreeting('<?php echo $row['vm_ext']; ?>')">
                        Record Greeting
                    </button>
                </div>
            </div>
            <?php
        }
    } else {
        echo "<p>No voicemail boxes configured for your account.</p>";
    }
    ?>

    <script>
    function accessVoicemail(ext) {
        // Trigger Asterisk originate call to VoiceMailMain
        fetch('voicemail-api.php', {
            method: 'POST',
            headers: {'Content-Type': 'application/x-www-form-urlencoded'},
            body: 'action=access&ext=' + encodeURIComponent(ext)
        })
        .then(response => response.json())
        .then(data => {
            if (data.success) {
                alert('Voicemail dialing to ' + ext);
            } else {
                alert('Error: ' + data.message);
            }
        });
    }

    function recordGreeting(ext) {
        if (confirm('Record temporary greeting for ' + ext + '?')) {
            fetch('voicemail-api.php', {
                method: 'POST',
                headers: {'Content-Type': 'application/x-www-form-urlencoded'},
                body: 'action=greeting&ext=' + encodeURIComponent(ext)
            })
            .then(response => response.json())
            .then(data => {
                alert(data.message);
            });
        }
    }
    </script>
</body>
</html>

Backend API at /var/www/html/vicidial/voicemail-api.php:

<?php
// Voicemail API for originating calls
session_start();

if (!isset($_SESSION['user_id'])) {
    http_response_code(401);
    echo json_encode(['success' => false, 'message' => 'Unauthorized']);
    exit;
}

$action = $_POST['action'] ?? '';
$ext = preg_replace('/[^0-9]/', '', $_POST['ext'] ?? '');

if (empty($ext)) {
    echo json_encode(['success' => false, 'message' => 'Invalid extension']);
    exit;
}

// Use Asterisk Manager Interface or AGI to originate call
$user_ext = $_SESSION['extension'];
$priority = ($action === 'greeting') ? 't' : 'u';

// Option 1: Use Asterisk Manager (requires AMI configuration)
$socket = fsockopen('localhost', 5038, $errno, $errstr, 2);
if (!$socket) {
    echo json_encode(['success' => false, 'message' => 'Cannot connect to Asterisk']);
    exit;
}

fwrite($socket, "Action: Login\r\nUsername: admin\r\nSecret: your_ami_secret\r\n\r\n");
fgets($socket, 1024);

$cmd = "Action: Originate\r\n"
     . "Channel: SIP/$user_ext\r\n"
     . "Context: vicidial-agents\r\n"
     . "Exten: $ext\r\n"
     . "Priority: 1\r\n"
     . "Async: true\r\n\r\n";

fwrite($socket, $cmd);
$response = fgets($socket, 1024);

fwrite($socket, "Action: Logoff\r\n\r\n");
fclose($socket);

echo json_encode(['success' => true, 'message' => 'Voicemail access initiated']);

Section 5: Advanced Features

Voicemail Transcription

Integrate with Google Cloud Speech-to-Text or Voicemail Transcription service:

#!/bin/bash
# /usr/local/bin/transcribe-voicemail.sh

VM_FILE="$1"
OUTPUT_FILE="${VM_FILE%.wav}.txt"

# Convert WAV to FLAC (Google requires)
flac "$VM_FILE" -o "${VM_FILE%.wav}.flac"

# Send to Google Speech-to-Text API
curl -X POST \
  --data-binary @"${VM_FILE%.wav}.flac" \
  -H "Content-Type: audio/flac" \
  "https://www.google.com/speech-api/json?output=json&client=chromium&key=YOUR_API_KEY" \
  > "$OUTPUT_FILE"

# Extract text from response
TRANSCRIPT=$(python3 -c "
import json
import sys
with open('$OUTPUT_FILE') as f:
    data = json.load(f)
    if 'result' in data and len(data['result']) > 0:
        print(data['result'][0]['alternative'][0]['transcript'])
" 2>/dev/null)

# Update database with transcript
mysql -u asterisk -pasterisk asterisk -e \
    "INSERT INTO voicemail_transcripts (vm_file, transcript, created_date) \
     VALUES ('$VM_FILE', '$TRANSCRIPT', NOW());"

echo "Transcription complete: $TRANSCRIPT"

Voicemail Purging & Archival

Create a maintenance script at /usr/local/bin/voicemail-maintenance.sh:

#!/bin/bash
# Archive and delete old voicemail messages

VOICEMAIL_ROOT="/var/spool/asterisk/voicemail"
ARCHIVE_DIR="/backup/voicemail-archive"
RETENTION_DAYS=90

# Create archive directory
mkdir -p "$ARCHIVE_DIR"

# Find and archive messages older than 90 days
find "$VOICEMAIL_ROOT" -type f -name "*.wav" -mtime +$RETENTION_DAYS | while read file; do
    dir=$(dirname "$file")
    context=$(basename $(dirname "$dir"))
    mailbox=$(basename "$dir")

    # Create archive structure
    archive_path="$ARCHIVE_DIR/$context/$mailbox"
    mkdir -p "$archive_path"

    # Move file to archive
    mv "$file" "$archive_path/"

    # Also move metadata
    base=$(basename "$file" .wav)
    [ -f "$dir/$base.txt" ] && mv "$dir/$base.txt" "$archive_path/"
    [ -f "$dir/$base.gsm" ] && mv "$dir/$base.gsm" "$archive_path/"

    echo "$(date) - Archived: $file"
done

# Tar and compress old archives (>30 days old)
find "$ARCHIVE_DIR" -type f -mtime +30 | xargs tar -czf "$ARCHIVE_DIR/voicemail-$(date +%Y%m%d).tar.gz"

echo "Voicemail maintenance completed at $(date)"

Schedule in crontab:

0 2 * * * /usr/local/bin/voicemail-maintenance.sh >> /var/log/voicemail-maintenance.log 2>&1

Voicemail Analytics & Reporting

Query voicemail activity:

-- Voicemail message count per agent
SELECT 
    vl.user_id,
    vu.user_name,
    vu.extension,
    COUNT(*) as vm_count,
    AVG(vl.message_length) as avg_duration,
    MAX(vl.call_date) as last_voicemail
FROM vicidial_log vl
JOIN vicidial_users vu ON vl.user_id = vu.user_id
WHERE vl.disposition = 'VOICEMAIL'
GROUP BY vl.user_id
ORDER BY vm_count DESC;

-- Voicemail response time (how long until agent retrieves)
SELECT 
    mailbox,
    COUNT(*) as total_voicemails,
    AVG(TIMESTAMPDIFF(HOUR, created, accessed)) as avg_retrieval_hours
FROM voicemail_msgs
WHERE accessed IS NOT NULL
GROUP BY mailbox;

Section 6: Troubleshooting

Voicemail Not Recording

Symptom: Calls go to voicemail but no message is left.

Diagnosis:

# Check voicemail module is loaded
sudo asterisk -rx "module show like voicemail"

# Check dialplan is correct
sudo asterisk -rx "dialplan show voicemail-context"

# Check filesystem permissions
ls -la /var/spool/asterisk/voicemail/
sudo chown -R asterisk:asterisk /var/spool/asterisk/voicemail/
sudo chmod -R 755 /var/spool/asterisk/voicemail/

Solution:

Reload dialplan and modules:

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

Email Notifications Not Sending

Symptom: Voicemails recorded but no email received.

Diagnosis:

# Check mail service
sudo systemctl status postfix
sudo mailq

# Test mail delivery directly
echo "Test" | mail -s "Test Subject" youremail@example.com

# Check Asterisk logs
tail -f /var/log/asterisk/full
grep -i "voicemail\|email" /var/log/asterisk/full

# Verify voicemail.conf settings
grep -A5 "serveremail\|attach\|format" /etc/asterisk/voicemail.conf

Solution:

Ensure Postfix is running and configured:

sudo postfix start
# Test SMTP connectivity
telnet localhost 25

Verify voicemail.conf has attach=yes and correct serveremail.

Agent Cannot Access Voicemail via *98

Symptom: Dialing *98 hangs or says extension not found.

Diagnosis:

# Verify extension pattern
sudo asterisk -rx "dialplan show vicidial-agents"

# Check SIP registration
sudo asterisk -rx "sip show peers" | grep 600

# Test with asterisk -vvv
sudo asterisk -vvv
# Then dial *98 and watch console output

Solution:

Ensure voicemail-agents context is included in agent SIP profiles:

[6000-6299](vicidial_agent)
type=friend
context=vicidial-agents

Reload SIP:

sudo asterisk -rx "sip reload"

Voicemail Files Corrupted or Unplayable

Symptom: Voicemail records but plays as noise.

Diagnosis:

# Check file format and integrity
file /var/spool/asterisk/voicemail/vicidial_context/6001/INBOX/*.wav

# Play file manually
sox /var/spool/asterisk/voicemail/vicidial_context/6001/INBOX/msg0000.wav -t raw -

# Check codec mismatch in dialplan
sudo asterisk -rx "core show codecs"

Solution:

Ensure codec configuration matches in sip.conf:

allow=ulaw,gsm,g729
disallow=all

Verify voicemail format in voicemail.conf is compatible:

format=wav49|gsm|ulaw

Performance Issues with Large Voicemail Spool

Symptom: Asterisk slow, voicemail access lags.

Diagnosis:

# Check spool disk usage
du -sh /var/spool/asterisk/voicemail/

# Count total files
find /var/spool/asterisk/voicemail -type f | wc -l

# Check I/O wait
iostat -x 1 5

Solution:

Implement archival maintenance (see Section 5), migrate to ODBC backend, or use external storage:


bash
# Enable S