DEV Community

Moisi Trungu
Moisi Trungu

Posted on • Originally published at flixzone.icu

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

#devops #linux #sip #voip

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:

  1. Agent status is not in a call-receiving state (paused, not ready, on break)
  2. Agent phone/device is not registered with Asterisk
  3. Campaign routing rules exclude the agent from receiving calls
  4. Database inconsistency between agent status and Asterisk registration
  5. 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';
Enter fullscreen mode Exit fullscreen mode

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();
Enter fullscreen mode Exit fullscreen mode

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';"
Enter fullscreen mode Exit fullscreen mode

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';"
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

The phone_login field contains the extension number. This must:

  1. Match the actual phone extension the agent is using
  2. Be registered with Asterisk (confirmed via sip show peers)
  3. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Common problems:

  1. Wrong password: The phone must have the exact secret configured
  2. Wrong context: Verify the context matches the dialplan rules
  3. NAT issues: If agent is behind NAT, ensure nat=yes is set
  4. 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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

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');
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

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;"
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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()
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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';"
Enter fullscreen mode Exit fullscreen mode

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)"
Enter fullscreen mode Exit fullscreen mode

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';"
Enter fullscreen mode Exit fullscreen mode

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;"
Enter fullscreen mode Exit fullscreen mode

Expected: Recent calls showing READY when attempted

Step 5: Check Asterisk Logs

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

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
Enter fullscreen mode Exit fullscreen mode

Make it executable and run:

chmod +x vicidial-agent-check.sh
./vicidial-agent-check.sh AGENT001
Enter fullscreen mode Exit fullscreen mode

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';"
Enter fullscreen mode Exit fullscreen mode

Solutions:

  1. Verify campaign is not paused (pause_calls = 'N')
  2. Check if agent has minimum calls limit reached (vicidial_campaign_agents.max_calls_today)
  3. Ensure campaign's lead pool has available leads
  4. 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;
Enter fullscreen mode Exit fullscreen mode

Solutions:

  1. Force agent logout: 
UPDATE vicidial_users SET status='LOGGED OUT' WHERE user='AGENT001';
Enter fullscreen mode Exit fullscreen mode
  1. Clear any stale sessions: 
asterisk -rx "sip show channels" | grep 101
Enter fullscreen mode Exit fullscreen mode
  1. 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>
Enter fullscreen mode Exit fullscreen mode

Solutions:

  1. Adjust SIP settings in /etc/asterisk/sip-vicidial.conf: 
[general]
registerintervalseconds=60
qualify=yes
qualifyfreq=60
notifyringing=yes
Enter fullscreen mode Exit fullscreen mode
  1. Add keep-alive to specific peer: 
[101]
keepalive=25
qualify=yes
qualifyfreq=30
Enter fullscreen mode Exit fullscreen mode
  1. Check for network connectivity issues between phone and server: 
# From agent phone's perspective (if possible)
tcpdump -i eth0 -n "host <vicidial-server-ip>"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Solutions:

  1. 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
Enter fullscreen mode Exit fullscreen mode
  1. 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';
Enter fullscreen mode Exit fullscreen mode

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';
Enter fullscreen mode Exit fullscreen mode

Verify both records exist and are active.

Solutions:

  1. Verify user group permissions: 
SELECT * FROM vicidial_user_groups 
WHERE user_group = (SELECT user_group FROM vicidial_users WHERE user='AGENT_NEW');
Enter fullscreen mode Exit fullscreen mode
  1. Check if user group is assigned to campaign: 
SELECT * FROM vicidial_campaign_user_groups 
WHERE campaign_id='CAMPAIGN01';
Enter fullscreen mode Exit fullscreen mode
  1. Ensure agent phone extension is unique: 
SELECT user, phone_login FROM vicidial_users WHERE phone_login='101' AND user != 'AGENT_NEW';
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Solutions:

  1. Verify SIP peer context matches a valid context with agent extensions: 
[101]
type=friend
context=agents     # This context must be defined
Enter fullscreen mode Exit fullscreen mode
  1. Reload dialplan: 
asterisk -rx "dialplan reload"
Enter fullscreen mode Exit fullscreen mode
  1. 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';"
Enter fullscreen mode Exit fullscreen mode

Summary

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

  1. Agent Status Issues: Agent in non-available status (NOT READY, BREAK, LUNCH). Fix by checking vicidial_users.status and ensuring agent transitions to READY.

  2. Phone Registration: Agent's extension not registered with Asterisk. Verify via sip show peers and check SIP configuration in /etc/asterisk/sip-vicidial.conf.

  3. Campaign Routing: Agent not assigned to campaign or campaign paused. Verify vicidial_campaign_agents and vicidial_campaigns tables.

  4. Database Inconsistency: Stale database records not matching live Asterisk state. Clean up via targeted UPDATE queries and restart ViciDial services.

  5. 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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)