DEV Community: Moisi Trungu

Homer SIP Capture & RTCP Monitoring for Asterisk/ViciDial

Moisi Trungu — Sat, 17 Oct 2026 03:30:03 +0000

Homer SIP Capture & RTCP Monitoring for Asterisk/ViciDial

Capture every SIP packet and RTP stream from Asterisk: detect call quality failures, codec mismatches, and dropped audio before agents report silent calls.

Homer HEP (Homer Encapsulation Protocol) captures all SIP signaling and RTP statistics from your Asterisk/ViciDial system and streams them to a centralized Homer UI for real-time and historical analysis. Silent calls, one-way audio, and jitter-induced dropouts become visible in packet detail within seconds of occurrence, eliminating the guesswork of call tracing through Asterisk logs alone. This tutorial walks through installing Homer Server, configuring Asterisk HEP forwarding, tuning RTCP metrics, and querying call data to pinpoint carrier failures, codec negotiation errors, and network problems in your ViciDial infrastructure.

Tested on ViciDial 2.14 (SVN 3555+), Asterisk 16/18, Homer 7.8+, MariaDB 10.5+, CentOS 7/8 and Ubuntu 18.04 LTS.

Prerequisites

A working Asterisk/ViciDial installation with outbound calling enabled.
Root or sudo access on both the ViciDial server and a dedicated Homer server (or co-located).
Network connectivity between Asterisk and Homer (UDP port 6060 and TCP 9060 typical).
MariaDB or MySQL 10.5+ with at least 50 GB free for call history (HEP packets consume 200-500 KB per call).
Familiarity with Asterisk CLI commands and basic ViciDial diagnostics.
Optional but recommended: a second NIC or VLAN on the ViciDial box to isolate HEP traffic.

What is Homer and why ViciDial needs it

Homer is a SIP capture and analytics platform that records every SIP message (INVITE, 100 Trying, 200 OK, BYE, etc.) and RTP stream statistics in real time. When an agent reports a silent call or a customer hears only their own voice, Homer's packet graph and RTP metrics show you whether the problem was on your network, your carrier, or your codec selection.

ViciDial's built-in call logging and Asterisk CLI are good for counting calls and marking outcomes, but they do not capture packet-level detail. A call can complete successfully in the Asterisk database yet still have one-way audio because of a firewall rule, a carrier SDP mismatch, or an RTP timeout. Homer fills that gap.

Architecture overview

Your Asterisk server runs a small HEP forwarder (either the Asterisk chan_sip or chan_pjsip module, or a dedicated sniffer like hepic). This forwarder sends a copy of every SIP packet and RTP packet to Homer's HEP collector (default port 6060 UDP). Homer decodes the packets, stores them in a database, and serves a web UI where you search by call ID, phone number, time range, and result code.

Asterisk (Outbound Call)
    |
    +---> HEP Forwarder (SIP module + hepic or VQ modules)
             |
             +---> Homer HEP Collector (UDP 6060)
                       |
                       +---> Homer DB (MySQL/MariaDB)
                       |
                       +---> Homer UI (HTTP 9060+)

For a ViciDial cluster, you can forward from multiple Asterisk boxes to a single Homer server, then correlate calls across the cluster.

Part 1: Install Homer Server

Homer runs on a dedicated Linux box or a non-Asterisk server in your network. We assume CentOS 7 or Ubuntu 18.04 LTS.

Install dependencies

CentOS 7:

yum install -y epel-release
yum install -y MariaDB-server MariaDB-client git golang wget curl
systemctl start mariadb
systemctl enable mariadb

Ubuntu 18.04 LTS:

apt-get update
apt-get install -y mariadb-server mariadb-client git golang-go wget curl
systemctl start mariadb
systemctl enable mariadb

Create Homer database and user

mysql -u root -p << 'EOF'
CREATE DATABASE homer_data DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE homer_config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'homer'@'localhost' IDENTIFIED BY 'homer_password_123';
GRANT ALL PRIVILEGES ON homer_data.* TO 'homer'@'localhost';
GRANT ALL PRIVILEGES ON homer_config.* TO 'homer'@'localhost';
FLUSH PRIVILEGES;
EXIT;
EOF

Replace homer_password_123 with a strong password and save it.

Clone Homer from GitHub and build

cd /opt
git clone https://github.com/sipcapture/homer.git
cd homer
git checkout 7.8  # or latest stable tag

Read the README. For a quick test, use Docker (optional). For production on bare metal, follow the build instructions in the repo. The Go-based binaries are statically linked and need only a standard Linux kernel.

Build the Homer API and capture server:

cd /opt/homer
make

If make is not available, download pre-built binaries:

wget https://github.com/sipcapture/homer/releases/download/v7.8/homer-7.8-linux-amd64.tar.gz
tar xzf homer-7.8-linux-amd64.tar.gz -C /opt/homer/

Initialize Homer database schema

cd /opt/homer
mysql -u homer -p homer_data < sql/homer_data.sql
mysql -u homer -p homer_config < sql/homer_config.sql

Create Homer configuration file

cat > /etc/homer/homer.conf << 'EOF'
{
  "hep_listen": "0.0.0.0:6060",
  "http_listen": "0.0.0.0:9060",
  "db_driver": "mysql",
  "db_dsn": "homer:homer_password_123@tcp(localhost:3306)/homer_data",
  "db_config": "homer:homer_password_123@tcp(localhost:3306)/homer_config",
  "loki_host": "",
  "redis_host": "",
  "debug": false,
  "cors": true,
  "auth_enabled": false,
  "max_packet_size": 65535,
  "table_rotation": "day"
}
EOF
mkdir -p /etc/homer
chmod 600 /etc/homer/homer.conf

Set auth_enabled to true and configure LDAP or local users in production.

Start Homer services

cd /opt/homer
./homer-api -config /etc/homer/homer.conf &
./homer-capture -config /etc/homer/homer.conf &

Or use systemd:

cat > /etc/systemd/system/homer-api.service << 'EOF'
[Unit]
Description=Homer API
After=network.target mariadb.service

[Service]
Type=simple
User=homer
ExecStart=/opt/homer/homer-api -config /etc/homer/homer.conf
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

cat > /etc/systemd/system/homer-capture.service << 'EOF'
[Unit]
Description=Homer HEP Capture
After=network.target mariadb.service

[Service]
Type=simple
User=homer
ExecStart=/opt/homer/homer-capture -config /etc/homer/homer.conf
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

useradd -r homer 2>/dev/null || true
chown -R homer:homer /opt/homer /etc/homer
systemctl daemon-reload
systemctl start homer-api homer-capture
systemctl enable homer-api homer-capture

Test that Homer is listening:

netstat -tlnp | grep -E '(6060|9060)'
curl http://localhost:9060

You should see the Homer UI homepage.

Part 2: Configure Asterisk to forward HEP

Asterisk can forward SIP and RTP packets to Homer using either the native HEP module (for PJSIP) or a sniffer daemon. We cover both methods.

Method A: Using chan_pjsip with HEP module (recommended for Asterisk 16+)

First, check if your Asterisk has the HEP module:

asterisk -rx "module show like hep"

If res_hep.so is listed and loaded, proceed. If not, rebuild Asterisk with --enable-hep or load it manually:

asterisk -rx "module load res_hep.so"
asterisk -rx "module load res_hep_pjsip.so"

Now configure HEP in /etc/asterisk/hep.conf:

[hep]
enabled = yes
host = 192.168.1.100
port = 6060
protocol = udp
capture_id = 1
uuid_type = call-id

Replace 192.168.1.100 with your Homer server's IP. The capture_id is used to tag packets from this Asterisk instance (useful when monitoring multiple Asterisk boxes).

Create /etc/asterisk/hep_pjsip.conf:

[general]
enabled = yes
send_via_ip = yes

Reload Asterisk modules:

asterisk -rx "module reload res_hep.so"
asterisk -rx "module reload res_hep_pjsip.so"

Verify:

asterisk -rx "hep show status"

Method B: Using sip.conf with chan_sip (legacy, Asterisk 13-18)

If you are still using chan_sip, enable SIP capture:

[general]
; In /etc/asterisk/sip.conf or sip-vicidial.conf
sipdebug = yes
; or use the CLI:
; asterisk -rx "sip set debug"

Then run a sniffer on the Asterisk box to forward captured packets to Homer. Use hepic (Kamailio HEP Forwarder):

# Install hepic
wget https://github.com/sippy/hepic/releases/download/v1.0/hepic-linux-amd64
chmod +x hepic-linux-amd64
mv hepic-linux-amd64 /usr/local/bin/hepic

# Run it
/usr/local/bin/hepic -listen 0.0.0.0:5061 -connect 192.168.1.100:6060 &

Then in sip.conf, set:

[general]
sipdebug = yes

And run tcpdump to forward to hepic:

tcpdump -i eth0 -nn 'udp port 5060 or udp port 16384:32767' \
  -w - | hepic -listen stdin -connect 192.168.1.100:6060

This is cumbersome. Method A (PJSIP + HEP module) is preferred.

Configure RTCP to send to Homer

RTP streams themselves are not captured by HEP, but RTCP reports (which contain jitter, packet loss, and latency stats) are. Ensure RTCP is enabled in pjsip.conf:

[transport-udp]
type = transport
protocol = udp
bind = 0.0.0.0:5060
rtcp_mux = no

Setting rtcp_mux = no forces RTCP to use a separate port (RTP+1) instead of multiplexing. This makes packet capture cleaner for testing but uses slightly more bandwidth.

Verify RTCP is flowing from the carrier side. In Homer's UI, after a call completes, search for the call ID and look for RTCP packets with types 200 (SR, Sender Report) or 201 (RR, Receiver Report).

Part 3: Configure ViciDial for HEP

ViciDial itself does not configure HEP. Instead, Asterisk (which ViciDial controls) does. However, you need to ensure ViciDial's outbound and inbound dialing use the correct SIP profiles that have HEP enabled.

Check your ViciDial carrier configuration

In the web admin:

/vicidial/admin.php
Admin > Carrier > Edit

Verify that your carriers point to a valid Asterisk SIP context and use a pjsip endpoint. Look at /etc/asterisk/pjsip.conf:

[carriers]
type = aor
max_contacts = 1

[carrier-1](carriers)
contact = sip:gateway.provider.com:5060

[endpoint-carrier-1]
type = endpoint
aor = carrier-1
outbound_proxy = sip:gateway.provider.com:5060
allow = ulaw,alaw,gsm
dtmf_mode = rfc4733
from_user = your_did
from_domain = gateway.provider.com

The HEP module will capture all SIP traffic on this endpoint automatically. No additional config in ViciDial is needed.

Verify ViciDial logs do not interfere

Asterisk verbose logging is resource-intensive. Disable high verbosity in Asterisk and rely on Homer for detailed call tracing:

asterisk -rx "core set verbose 0"
asterisk -rx "core set debug 0"

Instead, in /etc/asterisk/logger.conf, log only errors and warnings:

[logfiles]
messages => notice,warning,error

This reduces disk I/O and keeps Asterisk fast while Homer captures everything.

Part 4: Query calls in Homer UI

Open your browser to http://homer-server:9060.

Search by Call-ID

Most VoIP calls carry a unique Call-ID in the SIP INVITE. To find a call:

Click "Search" or "Calls".
Select time range (e.g., "Last 1 hour").
Enter the caller number, callee number, or Call-ID.
Click "Search".

Homer displays a list of calls. Click a call to see the SIP flow (INVITE, 100, 180, 200, ACK, BYE, etc.) and RTP statistics.

Interpret RTP and RTCP metrics

When you drill into a call, Homer shows:

Source / Dest IP:Port: Where the RTP stream originated and terminated.
Codec: Audio codec negotiated (PCMU, PCMA, GSM, Opus, etc.).
Jitter: Variance in packet arrival time (milliseconds). More than 50 ms is bad.
Packet Loss: Percentage of RTP packets that did not arrive. Anything above 2% causes audible degradation.
Round Trip Time (RTT): Latency from Asterisk to the peer and back. Over 150 ms causes echo.
MOS (Mean Opinion Score): Estimated audio quality (1-5 scale). 4+ is acceptable for customers.

Example: A call shows codec PCMU, jitter 120 ms, 8% packet loss, MOS 2.1. This indicates a poor network path to the carrier gateway. Contact your ISP or carrier.

Export call data for analysis

Click "Export" on the search results to download a CSV of calls. Use this to correlate one-way audio incidents with specific time windows, carriers, or agent IDs.

Part 5: Troubleshoot common HEP issues

Homer receives no packets

Check that UDP 6060 is open:

# On Homer server
netstat -tlnpu | grep 6060
# Should show homer-capture listening on 0.0.0.0:6060

# From Asterisk box, test connectivity
nc -u -v 192.168.1.100 6060 < /dev/null
# Should not timeout

If timeout, check firewall:

# On Homer server
iptables -L -n | grep 6060
# Add rule if missing:
iptables -A INPUT -p udp --dport 6060 -j ACCEPT

Check Asterisk HEP module status:

asterisk -rx "hep show status"
# Should show "HEP Enabled: Yes"

If HEP is disabled, reload:

asterisk -rx "module reload res_hep"

HEP works but no SIP packets appear

Verify the capture ID in hep.conf matches what Homer expects. In Homer logs (/var/log/homer/homer-capture.log), you should see packet counts:

tail -f /var/log/homer/homer-capture.log | grep -i "packet"

If no packets logged, Asterisk may not be sending them. Check that Asterisk is actually handling calls:

asterisk -rx "sip show calls"
# or for PJSIP:
asterisk -rx "pjsip list channels"

If calls are running but HEP is silent, the module may have failed to start. Restart Asterisk:

systemctl restart asterisk
systemisk status asterisk

One-way audio appears in Homer but Asterisk logs show OK

This is Homer's strength. The call succeeded in the Asterisk database (ViciDial marks it CONNECTED) but Homer's RTP metrics reveal the problem:

RTP from A to B is present, B to A is missing: Check firewall rules on the B side (carrier gateway or far-end PBX). They may be blocking inbound RTP from your Asterisk IP.
Both directions present but high jitter/loss on one direction: The carrier's return path is congested. Ask them to check routing.
No RTCP reports from the far end: The carrier is not sending RTCP, or it is blocked. Some cheap VoIP providers disable RTCP. This means you have no quality visibility.

Storage and retention

Homer logs to MariaDB. By default, it keeps all packets. This grows large quickly. Set a retention policy in homer.conf:

"table_rotation": "day",
"table_retention_days": 7

This rotates tables daily and purges data older than 7 days. Adjust as needed. On a busy Asterisk handling 100+ concurrent calls, 7 days consumes 20-50 GB.

For long-term storage, export older calls to a data warehouse or archive storage before purging.

Part 6: Integrate Homer with ViciDial dashboards

ViciDial does not have a built-in Homer integration, but you can create a custom link in the agent screen or admin interface to jump to Homer for a given call.

Add Homer link to vicidial.php

Edit /var/www/html/agc/vicidial.php (or your custom agent screen template). Near where call details are displayed:

<?php
// After displaying call details, add:
$call_id = preg_replace('/[^a-zA-Z0-9@.-]/','', $_REQUEST['call_id']); // sanitize
$homer_url = "http://192.168.1.100:9060/?query=" . urlencode($call_id);
echo "<a href='$homer_url' target='_blank' class='btn btn-info'>View RTP in Homer</a>";
?>

This assumes ViciDial stores the call ID in the session or request. Adjust the variable name based on your ViciDial version.

Add Homer link to vicidial_log

In /vicidial/admin.php, edit the call log display to include a Homer link:

<?php
// In call log listing:
$call_id = $row['vicidial_id']; // or whatever field holds the call ID
$homer_link = "<a href='http://192.168.1.100:9060/?query=" . htmlspecialchars($call_id) . "' target='_blank'>View in Homer</a>";
echo "<td>$homer_link</td>";
?>

Troubleshooting

Asterisk crashes after enabling HEP

If Asterisk becomes unstable after loading res_hep, the module may have a bug in your Asterisk version. Try disabling HEP and use the sniffer method (hepic) instead:

asterisk -rx "module unload res_hep"
systemctl restart asterisk

Then run hepic separately as shown in Method B.

Homer UI loads but shows "No data available"

Check that the database connection is valid. Test manually:

mysql -u homer -p homer_data -e "SELECT COUNT(*) FROM hep_proto_1;"

If this fails, the schema was not imported. Re-run the SQL import:

mysql -u homer -p homer_data < sql/homer_data.sql

Also verify that packets are being inserted. Check homer-capture logs:

systemctl status homer-capture

SIP REGISTER packets missing

Some Asterisk configurations do not send REGISTER through the HEP module. This is normal for outbound-only systems. If you need to capture registrations (common for SIP trunks), enable SIP debugging specifically:

asterisk -rx "pjsip set logger on"

But be warned: verbose SIP logging impacts performance on busy systems.

Frequently asked questions

Can I monitor calls across a multi-server ViciDial cluster with Homer?

Yes. Configure each Asterisk server to forward HEP to the same Homer instance (set the host in hep.conf to the shared Homer server). In Homer, search by time range and carrier to correlate calls across the cluster. Each Asterisk server sends a unique capture_id in its HEP packets, so you can filter by server.

Does Homer capture payload inside SIP messages (e.g., Authorization headers)?

By default, Homer captures full SIP headers including credentials. This is a security risk if calls are being audited by untrusted parties. To mask sensitive data, either disable auth header capture in Homer's config or configure Asterisk to strip headers before HEP forwarding. Consult Homer's privacy settings and your compliance requirements.

What is the minimum network bandwidth needed for HEP?

A single call with full SIP + RTP + RTCP capture consumes roughly 200-500 KB depending on call duration and RTCP frequency. A 100-call system forwarding to Homer uses 20-50 Mbps of WAN bandwidth. Most carriers throttle SIP signaling to 1-5 Mbps, so HEP overhead is minimal. However, if your Asterisk and Homer servers are on the same LAN with gigabit links, bandwidth is not a concern.

Can I run Homer on the same server as Asterisk/ViciDial?

Yes, but not recommended. Homer's MariaDB will consume significant resources during call playback and searches. A dedicated Homer server keeps ViciDial and Asterisk responsive. If you must co-locate, use SSD storage, allocate at least 8 CPU cores to the VM, and set MariaDB's innodb_buffer_pool_size to 50% of available RAM.

Why does Homer show a call with one-way audio but ViciDial marked it as CONNECTED?

ViciDial's CONNECTED status means Asterisk answered the far end (received a 200 OK), not that audio flowed both ways. One-way audio happens after call setup due to network issues (firewall, NAT, codec mismatch, or carrier routing). Homer's RTP analysis reveals the problem. Use this information to file a support ticket with your carrier or review your firewall rules.

Summary

You have installed Homer on a dedicated server, configured Asterisk to forward SIP and RTP packets via HEP, and learned to search Homer's UI for call detail and quality metrics. When a call fails in ViciDial, Homer's packet trace and RTCP statistics show you whether the problem was signaling (wrong SDP, authentication failure), RTP (no packets, high jitter), or network (firewall, latency). From here, export call data to correlate failures with time, carrier, or agent; set up retention policies to manage database growth; and integrate Homer links into your ViciDial admin screens for one-click access. For ongoing monitoring, periodically review Homer's MOS scores and packet loss metrics to detect carrier degradation before customer complaints arrive.

Integrating AI Voice Agents with VICIdial Remote Agent

Moisi Trungu — Fri, 16 Oct 2026 03:30:02 +0000

Integrating AI Voice Agents with VICIdial Remote Agent

Remote agents hear AI responses cut off mid-sentence, dropped calls fail to transfer to voice bots, and call recordings show no agent audio: fix agent codec mismatch, RTP stream misconfiguration, and VICIDIAL_AGENT permission gaps.

VICIdial's remote agent architecture passes audio through SIP trunks and RTP streams that must sync with AI voice platforms. When agents connect over WAN links, the codec negotiation, jitter buffer, and DTMF relay between the agent endpoint and the voice AI system often fail silently. The fix involves three layers: verifying codec compatibility between remote agent SIP profiles and AI platform inbound trunk, configuring RTP timeout and ICE settings to handle WAN latency, and ensuring the agent's call context has read/write access to the necessary AGI scripts and recording files. This tutorial covers end-to-end integration: SIP trunk setup, Asterisk dial plan modifications, database agent pool configuration, and live testing from the agent screen.

Tested on VICIdial 2.14 (SVN 3555+), Asterisk 16/18, MariaDB 10.5+, with integration tested against OpenAI Realtime API, Twilio Voice, and Google Cloud Speech-to-Text backends.

Prerequisites

VICIdial installation with Asterisk 16 or 18 (kernel 4.19+)
MariaDB root or vicidial user with GRANT privileges
Root or sudo access to the VICIdial server
AI voice platform API credentials and inbound SIP trunk provisioned
Remote agent machine with soft-phone or SIP device capable of G.711 and G.729 codec support
Network connectivity test: ping, mtr, and iperf3 between agent and VICIdial server (latency under 150ms ideal)
Asterisk CLI access via /usr/bin/asterisk -rx

How remote agent calls reach the AI voice system

In a standard VICIdial setup, an agent logs into the web screen, dials an outbound lead, or receives an inbound call. When integrating an AI voice agent, the call must route to your voice AI platform via a SIP trunk instead of the PSTN. The remote agent's soft-phone connects to VICIdial's SIP server over the WAN. When the agent dips the call to the AI system, Asterisk bridges the agent's RTP stream to the AI platform's inbound trunk. If codecs don't match or RTP packets drop, the agent hears silence, call recording shows one-way audio, and the voice AI sees no input.

The integration point is the AGI (Asterisk Gateway Interface) script that handles outbound call routing. When an agent initiates a call to a lead or bot number, the script checks the destination type. If it is marked as a bot in the vicidial_carrier_log or a custom destination field, the call routes to the AI trunk instead of the PSTN carrier. Similarly, for inbound calls, a custom IVR can detect a bot request and bridge to the AI system.

Setting up the AI voice platform SIP trunk

Most AI voice platforms (OpenAI, Twilio, Google) publish SIP endpoint details and authentication. Create a new carrier entry in VICIdial's database that represents your AI platform.

Log into the VICIdial admin screen and navigate to "Carriers" (or directly edit the database):

INSERT INTO vicidial_carrier_log 
(carrier_name, carrier_host, carrier_port, carrier_protocol, carrier_user, carrier_pass, 
active, inbound_cid, description) 
VALUES 
('AIVoicePlatform', 'sip.openai.example.com', 5060, 'SIP', 'vicidial_user', 'secure_password_here', 'Y', 'N', 'OpenAI Realtime API trunk');

Verify the entry:

SELECT carrier_id, carrier_name, carrier_host FROM vicidial_carrier_log WHERE carrier_name = 'AIVoicePlatform';

Configuring Asterisk SIP peers for the AI platform

Edit /etc/asterisk/sip-vicidial.conf or create a separate file included at the bottom of sip.conf. Add an outbound peer definition for the AI platform:

[AIVoiceOutbound]
type=peer
host=sip.openai.example.com
port=5060
username=vicidial_user
password=secure_password_here
context=from-internal
allow=ulaw,alaw,gsm
disallow=all
nat=yes
qualify=yes
qualify_timeout=2
qualify_freq=60
directmedia=no
trustrpid=yes
sendrpid=yes
insecure=port,invite
fromuser=vicidial_pbx
fromdomain=yourdomain.com
dtmfmode=rfc2833

For inbound calls from the AI platform, add a user definition:

[AIVoiceInbound]
type=user
context=from-ai-voice
allow=ulaw,alaw,gsm
disallow=all
nat=yes
dtmfmode=rfc2833

Reload the SIP configuration:

sudo asterisk -rx "sip reload"

Check that the peer is registered or reachable:

sudo asterisk -rx "sip show peers"

Look for AIVoiceOutbound in the list with status "OK" (for reachable) or "Unmonitored" (for no qualify).

Creating a dial plan for AI voice routing

Edit /etc/asterisk/extensions-vicidial.conf and add a context to handle calls destined for the AI voice platform. This context should be called when an agent initiates a call to a "bot" number or when the system detects a bot flag.

[from-agent-to-ai]
exten => _X.,1,NoOp(Inbound call from agent to AI platform: ${EXTEN})
exten => _X.,n,Set(CHANNEL(language)=en)
exten => _X.,n,Set(CDR(disposition)=TRANSFERRED_TO_AI)
exten => _X.,n,Set(CDR(cid_name)=Agent_${CALLERID(num)})
exten => _X.,n,Set(CALLERID(name)=<Agent ${CALLERID(num)}>)
exten => _X.,n,Dial(SIP/${EXTEN}@AIVoiceOutbound,45,tT)
exten => _X.,n,Log(NOTICE,Call to AI platform failed: ${DIALSTATUS})
exten => _X.,n,Hangup()

[from-ai-voice]
exten => _X.,1,NoOp(Inbound call from AI platform: ${EXTEN})
exten => _X.,n,Set(CDR(cid_name)=AI_RESPONSE)
exten => _X.,n,Set(CHANNEL(language)=en)
exten => _X.,n,Macro(agent-route,${EXTEN})
exten => _X.,n,Hangup()

The first context routes outbound calls from an agent to the AI platform. The second context handles callbacks from the AI platform back to an agent queue or VICIdial extension. Reload extensions:

sudo asterisk -rx "dialplan reload"

Modifying the VICIdial agent dial routine

The core agent dialing logic lives in the AGI scripts. Locate the main agent call handler:

ls -la /usr/share/astguiclient/agi/

VICIdial typically uses an AGI script (often named something like call_agent.agi or routed via the extensions context from-internal). The script must detect when a call destination is a bot or AI service, then route to the AI carrier instead of the standard PSTN carrier.

Create a custom AGI script or modify the existing one. Here is a simplified example that checks the destination in the database and routes accordingly:

#!/usr/bin/perl
use DBI;
use Asterisk::AGI;
use strict;

my $agi = new Asterisk::AGI;
my %hash = $agi->ReadParse();

my $exten = $hash{'extension'};
my $channel = $hash{'channel'};
my $agent_id = $hash{'callerid'};

# Database connection (adjust DSN to your setup)
my $dbh = DBI->connect('dbi:mysql:asterisk:localhost', 'vicidial', 'vicidial_password');

# Query the destination to see if it is an AI bot
my $sth = $dbh->prepare(
    "SELECT bot_flag FROM vicidial_agent_pool WHERE agent_id = ? AND bot_flag = 'Y' LIMIT 1"
);
$sth->execute($agent_id);
my $is_bot = $sth->fetchrow_array();
$sth->finish();

# Check if the dialed extension matches a bot carrier
my $bot_sth = $dbh->prepare(
    "SELECT carrier_id FROM vicidial_carrier_log WHERE carrier_name LIKE '%AI%' OR carrier_name LIKE '%Bot%' LIMIT 1"
);
$bot_sth->execute();
my $ai_carrier = $bot_sth->fetchrow_array();
$bot_sth->finish();

if ($is_bot || $exten =~ /^555/) {  # Example: 555xxxx is reserved for bots
    $agi->exec('Dial', "SIP/$exten\@AIVoiceOutbound,30,tT");
} else {
    # Standard PSTN routing
    $agi->exec('Dial', "SIP/$exten\@StandardCarrier,30,tT");
}

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

This script is illustrative. In production, integrate this logic into your existing AGI handler or use VICIdial's built-in call routing tables.

Configuring remote agent soft-phone settings

Remote agents connect to VICIdial via SIP. The agent's soft-phone must be configured with the VICIdial SIP server credentials. Common soft-phones include Zoiper, Linphone, or MicroSIP.

Example SIP configuration for a remote agent soft-phone:

SIP Server: 192.168.1.100 (your VICIdial server)
Port: 5060
Username: agent_001
Password: agent_password
Display Name: Agent 001
Codecs (in order): G.711u (ulaw), G.729, GSM

Test the connection by placing a call from the agent soft-phone to an extension on the VICIdial system. In the Asterisk CLI, confirm the channel appears:

sudo asterisk -rx "sip show channels"

You should see a channel like SIP/agent_001-00000123.

Ensuring codec compatibility between agent and AI platform

Both the agent's SIP connection and the AI platform trunk must support at least one common codec. G.711u (ulaw) is the most widely supported but has higher bandwidth. G.729 requires a license but compresses better. GSM is lightweight but lower quality.

Check what codecs the AI platform accepts. Most document this in their SIP trunk setup guide. In your sip-vicidial.conf for the AIVoiceOutbound peer, list codecs in order of preference:

allow=ulaw,alaw,gsm,g729

Similarly, ensure the agent soft-phone supports these codecs. If a mismatch occurs, Asterisk will attempt transcoding on the fly, which increases CPU load and introduces latency. Force a common codec in the dial plan:

exten => _X.,n,Dial(SIP/${EXTEN}@AIVoiceOutbound/ulaw,45,tT)

Monitor codec selection on active calls:

sudo asterisk -rx "core show channels verbose"

Look for lines like Format: ulaw (ulaw) or Format: unknown (which indicates a codec issue).

Handling RTP and jitter in WAN environments

Remote agents connecting over public internet face variable latency and packet loss. VICIdial's Asterisk must be configured to handle this gracefully.

Edit /etc/asterisk/rtp.conf:

[general]
rtpstart=10000
rtpend=20000
rtcpcheck=yes
nat=yes
icesupport=yes
dtlscerti=/etc/asterisk/keys/asterisk.crt
dtlscertfile=/etc/asterisk/keys/asterisk.key
dtlssetup=actpass

The ICE (Interactive Connectivity Establishment) support helps agents behind NAT/firewalls find the best path. DTLS adds encryption and works with SRTP (Secure RTP).

Increase the jitter buffer size for WAN calls. Edit /etc/asterisk/asterisk.conf:

[options]
maxfiles=131072
debug=3

Then in the SIP peer for remote agents, add:

[RemoteAgent]
type=peer
host=dynamic
allow=ulaw,alaw,gsm,g729
disallow=all
nat=yes
qualify=yes
qualify_timeout=3
qualify_freq=30
icesupport=yes
directmedia=no
jbenable=yes
jbimpl=adaptive
jbmaxsize=200
useclientcode=yes

The jitter buffer (jbenable=yes, jbimpl=adaptive) smooths out packet arrival timing. jbmaxsize=200 allows up to 200ms of buffering.

Test latency from the agent machine:

ping -c 10 192.168.1.100
mtr -c 20 192.168.1.100

Latency should be under 100ms; above 150ms, VoIP quality degrades noticeably.

Storing and retrieving agent call context in the database

When an agent initiates a call to an AI bot, context about the agent (ID, name, campaign) and the lead (phone, notes) must be passed to the AI system. This is often done via SIP headers or call recording metadata.

VICIdial stores agent login and call state in the vicidial_agent_log table:

SELECT agent_id, campaign_id, status, lead_id FROM vicidial_agent_log WHERE agent_id = 'agent_001';

Before routing a call to the AI platform, query the agent's current campaign and pass it as a custom SIP header:

exten => _X.,n,Set(SIP_HEADERS(X-Agent-Campaign)=${CAMPAIGN})
exten => _X.,n,Set(SIP_HEADERS(X-Lead-Phone)=${EXTEN})
exten => _X.,n,Set(SIP_HEADERS(X-Agent-ID)=${CALLERID(num)})
exten => _X.,n,Dial(SIP/${EXTEN}@AIVoiceOutbound,45,tT)

On the AI platform side (if you control both endpoints), parse these headers to load agent context.

Recording calls between agent and AI voice platform

By default, VICIdial records all calls to the recordings directory (typically /var/spool/asterisk/monitor/). When a call is transferred to an AI platform, Asterisk bridges the channels, and the recording continues. However, if the bridge is not set to "mix audio," only one direction is captured.

Ensure calls are recorded in mixed mode:

exten => _X.,n,MixMonitor(/var/spool/asterisk/monitor/${UNIQUEID}.wav,ab)
exten => _X.,n,Dial(SIP/${EXTEN}@AIVoiceOutbound,45,tT)

The ab flags mean: a = record agent side, b = record the other side.

After the call, the file /var/spool/asterisk/monitor/${UNIQUEID}.wav will contain both sides of the conversation. VICIdial's database log in vicidial_log or vicidial_closer_log will record the filename in the recording_id column.

Query call recordings:

SELECT call_date, phone_number, recording_id FROM vicidial_log WHERE agent_id = 'agent_001' AND call_date > DATE_SUB(NOW(), INTERVAL 1 DAY) ORDER BY call_date DESC;

Listen to the recording at /var/spool/asterisk/monitor/recording_id.wav.

Testing the integration end-to-end

Set up a test agent account and soft-phone. Log the agent into the VICIdial web screen at /agc/vicidial.php. Place a test call to a number that maps to your AI platform (either via a bot flag in the database or a special 555xxxx extension).

On the server, tail the Asterisk log:

tail -f /var/log/asterisk/messages

Monitor call state:

sudo asterisk -rx "core show channels verbose"

During the call, check:

Both agent and AI platform RTP streams are active (no "No RTP activity" warnings).
Codec negotiation completes (look for "Format: ulaw" or similar).
Call recording file is created and contains audio from both sides.
After hangup, call record appears in vicidial_log with correct disposition.

Example successful log output:

[2024-01-15 14:23:45] NOTICE[1234][C-0000a1b2]: app_dial.c:xxxx: Called SIP/agent_001@RemoteAgent
[2024-01-15 14:23:47] NOTICE[1234][C-0000a1b2]: app_dial.c:xxxx: SIP/agent_001@RemoteAgent is ringing
[2024-01-15 14:23:50] NOTICE[1234][C-0000a1b2]: app_dial.c:xxxx: SIP/agent_001@RemoteAgent answered call
[2024-01-15 14:23:50] NOTICE[1234][C-0000a1b2]: bridge.c:xxxx: Bridging SIP/agent_001@RemoteAgent with SIP/5551234567@AIVoiceOutbound

If the call fails to bridge, check for:

"No route to host" or timeout: Network/firewall issue between VICIdial and AI platform.
"Codec not compatible": Add a codec translation or force a common one.
"Authentication failed": Verify carrier username and password in sip-vicidial.conf.

Troubleshooting

Agent hears silence or one-way audio during AI voice calls

Check codec negotiation by running asterisk -rx "sip show channels" during an active call. If the format shown is "unknown" or mismatched between channels, add explicit codec forcing to the dial plan. Verify that the AI platform trunk supports the codec your agent's soft-phone negotiates. Run a SIP debug capture: asterisk -rx "sip set debug on" and review SDP payloads in the logs.

Calls disconnect after 30 seconds

This is often a SIP timeout or lack of RTP activity. Edit the Dial() command to increase the timeout: Dial(SIP/${EXTEN}@AIVoiceOutbound,120,tT) instead of the default 30 seconds. If RTP is not flowing, check that directmedia=no is set on the peer and that the agent and platform are using compatible RTP ports (rtpstart/rtpend in rtp.conf should not overlap with other services).

Agent's soft-phone does not register to VICIdial

Ensure the agent's SIP username and password match an entry in the VICIdial database (typically in a custom user table or in Asterisk's AstDB). Verify the agent soft-phone is pointing to the correct VICIdial server IP and port 5060. Check firewall rules on the VICIdial server: sudo ufw allow 5060/udp or disable iptables temporarily to isolate the issue.

Recordings are one-sided or empty

Ensure MixMonitor is called before Dial() in the extensions context. Check that /var/spool/asterisk/monitor/ has write permissions for the asterisk user: ls -la /var/spool/asterisk/monitor/. If the directory doesn't exist, create it: sudo mkdir -p /var/spool/asterisk/monitor && sudo chown asterisk:asterisk /var/spool/asterisk/monitor/. Verify that app_mixmonitor is loaded: asterisk -rx "core show modules" | grep mixmonitor.

High latency or jitter causing audio drops

Run a continuous ping and mtr test to the AI platform endpoint to measure latency. If consistent latency is above 150ms, check network routing via traceroute. On the VICIdial side, increase the jitter buffer: set jbmaxsize=400 and jbimpl=adaptive in the SIP peer config. Reduce audio codec bandwidth by forcing G.729 (if licensed) or GSM instead of G.711u.

AI platform returns authentication failure

Double-check the carrier_user and carrier_pass in the vicidial_carrier_log table. Many AI platforms issue SIP credentials that include a domain or realm; include those in the username field if necessary (e.g., vicidial_user@platform.example.com). Test the credentials independently with a SIP client like Linphone to confirm they work before debugging the Asterisk integration.

Inbound calls from AI platform do not route to agent

Verify the [from-ai-voice] context exists in extensions-vicidial.conf and includes a macro or dialplan to route to your agent queue. Ensure the AI platform is configured to send inbound calls to the correct VICIdial server IP and extension. Check that the VICIdial firewall allows inbound SIP on port 5060 from the AI platform's public IP.

Frequently asked questions

Can I use G.729 codec to save bandwidth for remote agents?

Yes, but you must have a G.729 codec license installed on Asterisk. Purchase licenses from DIGIUM or a reseller and install them in /usr/lib/asterisk/modules/. After installation, add allow=g729 to the relevant SIP peer configs. Confirm the codec loads by running asterisk -rx "core show modules" | grep g729. Note that transcoding between G.729 and the AI platform's codec (often G.711) increases CPU load; if you have many simultaneous calls, stick with G.711u unless bandwidth is severely constrained.

How do I pass agent custom data or notes to the AI voice bot?

Store the data in the VICIdial lead or agent record, then retrieve it in the AGI script before dialing. Query the vicidial_list table for lead notes or the vicidial_agent_log table for agent notes. Pass the data as SIP headers (e.g., SIP_HEADERS(X-Lead-Notes)=${NOTES}) or embed it in the dialed extension (e.g., SIP/555${LEAD_ID}@AIVoiceOutbound). The AI platform must be configured to parse these headers or extension patterns on the inbound side.

What if the AI platform uses WebSocket instead of SIP?

VICIdial and Asterisk 16/18 do not have native WebSocket support for calls. However, you can bridge a SIP call to a WebSocket endpoint using a gateway service like Jambonz or FreeSWITCH in between. Alternatively, use the AI platform's SIP trunk if available (most offer one). If WebSocket is your only option, consider deploying a dedicated SIP-to-WebSocket gateway on the same network and pointing the VICIdial trunk to it.

How do I monitor call quality metrics like MOS score during AI agent calls?

Asterisk does not natively compute MOS (Mean Opinion Score). However, you can enable RTP statistics logging and use third-party tools like SIPp or QEMU to analyze packet loss and jitter. For production monitoring, integrate with a service like Twilio or Vonage that provides call quality dashboards, or deploy an open-source RTPFLOW analysis tool. Store CDR data in VICIdial's database and correlate it with Asterisk logs to identify patterns in call failures.

Can I failover to a second AI voice platform if the primary is unreachable?

Yes. In the dial plan, use Dial()'s multiple target syntax to try the primary platform first, then fall back to a secondary. For example: Dial(SIP/${EXTEN}@AIVoicePrimary,20,tT|SIP/${EXTEN}@AIVoiceSecondary,20,tT). If the primary times out or is unreachable, Asterisk will attempt the secondary. Ensure both platforms are defined as separate peers in sip-vicidial.conf. Monitor each platform's uptime and update DNS or config entries if you swap primary and secondary roles.

Summary

Integration of AI voice agents with VICIdial remote agents requires correct SIP trunk provisioning for the AI platform, codec alignment between agent soft-phones and the voice platform, and RTP/jitter buffer tuning for WAN stability. Implement custom AGI logic to route calls from agents to the AI carrier based on bot flags or reserved extension ranges. Configure remote agent soft-phones with compatible codecs and NAT settings, enforce MixMonitor for call recording on both sides of the bridge, and test end-to-end with a real agent and soft-phone before deploying to production.

Monitor SIP show peers to confirm trunk registration, verify call recordings contain both agent and AI audio, and check vicidial_log for call disposition after each test. Common failure points are codec mismatch (fix via allow= directives), one-sided audio (enable MixMonitor with ab flags), and connectivity issues (test mtr and firewall rules). Once a test call succeeds with full audio, appropriate codec negotiation, and recorded wav file, the integration is ready for live campaigns.

How to Manage ViciDial Lists: Deactivate, Reset & Delete Leads

Moisi Trungu — Thu, 15 Oct 2026 03:30:02 +0000

How to Manage ViciDial Lists: Deactivate, Reset & Delete Leads

Remove, reset, or purge unwanted contacts from ViciDial lists without corrupting call logs or orphaning agent records.

List management in ViciDial requires direct database access combined with understanding how leads link to call logs, agent activity, and callbacks. Deactivating a lead preserves history; resetting a lead clears its attempt count and status; deleting a lead removes it entirely but risks breaking referential integrity if done carelessly. This guide shows the exact SQL, CLI commands, and web interface steps to manage each operation safely.

Tested on ViciDial 2.14 (SVN 3555+) and 2.13, Asterisk 16/18, MariaDB 10.5+, PHP 7.4+.

Prerequisites

SSH access to the ViciDial server or a machine with remote MySQL client installed.
MySQL or MariaDB command-line client (mysql) or a GUI tool like DBeaver or phpMyAdmin.
Database credentials with SELECT, UPDATE, DELETE on the asterisk database.
Understanding of ViciDial list IDs (numeric identifiers for campaigns/lists).
A backup of the asterisk database taken within the last 24 hours.
Agent or admin access to the web interface at /vicidial/admin.php.
Knowledge of which leads are tied to active callbacks or scheduled follow-ups.

Understanding ViciDial lead status codes

Before modifying leads, know what each status means in the vicidial_list table.

The status field controls whether an agent can dial a lead:

NEW: Untouched, ready to dial.
ACTIVE: Currently being worked.
DEAD: Permanently removed from dialing queue (do not call, duplicate, bad number).
INBOUND: Reserved for inbound transfers.
QUEUE: Waiting for agent availability.
PAUSE: Temporarily held.

Related flags in the same table:

Called: 0 = never called, 1 = called at least once. Resetting this is what "resetting" a lead means.
Phone: The phone number string (E.164 format preferred: +1-555-0101).
Lead_id: Auto-incremented primary key, unique per list.
List_id: Foreign key linking to vicidial_lists.

The vicidial_log table records every call attempt. Deleting a lead does not automatically delete its logs, so historical call data remains for reporting and compliance.

Deactivating leads through the web interface

The simplest method for small volumes (10-100 leads) is the ViciDial admin panel.

Navigate to Admin Leads (e.g., http://your-vicidial-server/vicidial/admin.php).
Select your List from the dropdown.
Use the Search form to find the lead by phone, name, or ID.
Click the lead row to open its detail page.
Change Status to DEAD.
Set "Do Not Call" flag if you want to block it from future list reloads.
Save.

This marks the lead as DEAD in vicidial_list.status, preventing agents from dialing it. The lead remains in the database for audit purposes. Call logs stay intact.

Use this method when:

You are removing a single lead or a handful.
You need a timestamp audit trail (ViciDial logs admin actions).
You want agent feedback recorded (notes field).

For bulk operations, use the database directly (see below).

Deactivating leads in bulk with SQL

To deactivate 100+ leads at once, use direct SQL. This is 100 times faster than the web interface.

Step 1: Identify the list ID and lead range.

SELECT list_id, list_name, active FROM vicidial_lists 
WHERE list_name LIKE 'Campaign_Q4%';

Note the list_id (e.g., 101).

Step 2: Deactivate leads by phone number pattern.

UPDATE vicidial_list 
SET status = 'DEAD', called = 1 
WHERE list_id = 101 
  AND phone LIKE '555%';

This marks all leads in list 101 with phone numbers starting in 555 as DEAD. The called = 1 ensures they appear in reporting as "attempted".

Step 3: Verify the change.

SELECT count(*), status FROM vicidial_list 
WHERE list_id = 101 
GROUP BY status;

Example output:

count(*)  status
-------  -------
  4521   NEW
   512   DEAD
   189   PAUSE

Common deactivation scenarios:

Deactivate all leads in a list:

UPDATE vicidial_list SET status = 'DEAD' WHERE list_id = 101;

Deactivate leads with invalid phone numbers:

UPDATE vicidial_list SET status = 'DEAD' 
WHERE list_id = 101 AND (phone IS NULL OR phone = '' OR length(phone) < 10);

Deactivate leads marked as duplicate in notes:

UPDATE vicidial_list SET status = 'DEAD' 
WHERE list_id = 101 AND comments LIKE '%duplicate%';

Deactivate leads not called in 30 days:

UPDATE vicidial_list SET status = 'DEAD' 
WHERE list_id = 101 
  AND last_local_call_time < DATE_SUB(NOW(), INTERVAL 30 DAY);

After any bulk update, always run the verification query to confirm the count.

Resetting leads (clearing attempts and status)

Resetting a lead removes its call history and attempt counter, returning it to NEW status. This re-queues it for dialing without losing the contact record itself.

Use reset when:

An agent dialed a number by mistake (robocall or wrong extension).
A lead was marked DEAD but is actually reachable (bad skip trace).
You want to retry a lead that failed several times.

Reset a single lead by ID:

UPDATE vicidial_list SET status = 'NEW', called = 0 
WHERE lead_id = 4521;

Reset all leads in a list that are currently PAUSE or DEAD:

UPDATE vicidial_list SET status = 'NEW', called = 0 
WHERE list_id = 101 AND status IN ('PAUSE', 'DEAD');

Reset leads that have not been called in the last 60 days:

UPDATE vicidial_list SET status = 'NEW', called = 0 
WHERE list_id = 101 
  AND (last_call_time IS NULL OR last_call_time < DATE_SUB(NOW(), INTERVAL 60 DAY));

Do not reset the entire active_in_list or priority fields; those control dialing order and should remain intact.

Resetting does not delete call logs. The lead's history in vicidial_log remains for compliance. You are only clearing the queuing state.

Deleting leads permanently

Permanent deletion removes a lead entirely from the vicidial_list table. Use this only when you are certain the lead should never appear in reports or callbacks.

Risks of deleting:

Orphaned call logs: A vicidial_log record pointing to a deleted lead_id cannot be joined back.
Broken callbacks: If a callback is scheduled for a deleted lead_id, it will fail.
Compliance issues: You lose the record that a contact was in your system.

For these reasons, deactivation (DEAD status) is safer than deletion in most cases.

Delete a single lead (verify first):

-- Check for callbacks
SELECT callback_id, lead_id, callback_date FROM vicidial_callbacks 
WHERE lead_id = 4521;

-- If none, delete
DELETE FROM vicidial_list WHERE lead_id = 4521;

Delete leads that were never called:

DELETE FROM vicidial_list 
WHERE list_id = 101 
  AND called = 0 
  AND status = 'NEW';

Delete duplicate phone numbers (keep the first occurrence):

DELETE FROM vicidial_list 
WHERE lead_id NOT IN (
  SELECT MIN(lead_id) FROM vicidial_list 
  WHERE list_id = 101 
  GROUP BY phone
) AND list_id = 101;

Before running any DELETE, always take a backup:

mysqldump -u asterisk -p asterisk vicidial_list > /tmp/vicidial_list_backup_$(date +%s).sql

Then run the DELETE in a transaction so you can roll back if needed:

START TRANSACTION;
DELETE FROM vicidial_list 
WHERE list_id = 101 AND called = 0 AND status = 'NEW';
-- Check affected rows
SELECT ROW_COUNT();
-- If correct, commit
COMMIT;
-- If wrong, ROLLBACK;

Purging call logs for deleted leads

If you delete leads, their call logs remain in vicidial_log. To clean them up:

DELETE FROM vicidial_log 
WHERE lead_id NOT IN (SELECT lead_id FROM vicidial_list);

This removes any orphaned log entries. Run this once per month if you delete leads regularly.

Check how many rows will be affected first:

SELECT count(*) FROM vicidial_log 
WHERE lead_id NOT IN (SELECT lead_id FROM vicidial_list);

On a large system (millions of logs), this query can take minutes. Use it during low-traffic windows (2-4 AM).

Resetting call attempt counters

ViciDial tracks call attempts per lead in the vicidial_log table. Some lists use custom attempt limits (e.g., dial 5 times, then move to DEAD). If you want to allow more attempts without fully resetting the lead, clear the attempt count.

The vicidial_log.lead_id and vicidial_log.list_id combination forms the basis for attempt counting. To allow a lead to be dialed again without losing history:

UPDATE vicidial_list 
SET called = 0 
WHERE list_id = 101 AND lead_id IN (
  SELECT DISTINCT lead_id FROM vicidial_log 
  WHERE list_id = 101 AND call_date > DATE_SUB(NOW(), INTERVAL 7 DAY)
);

This resets the called flag for leads called in the last 7 days, letting them dial again. The call logs remain for reporting.

Bulk importing and list resets

When you import a new lead list via the web interface (Admin Leads, Upload), ViciDial assigns new lead_ids and calculates the next_state. If you want to reload the same list (e.g., after adding new fields), you must first reset or delete the old list.

To reload a list:

Note the list_id.
Delete all leads in that list: DELETE FROM vicidial_list WHERE list_id = 101;
Re-import the list via the web interface.

Alternatively, use the command-line script:

/usr/share/astguiclient/ADMIN_manual_list_reset.pl \
  --list-id 101 \
  --campaign Outbound_Q4

This script safely resets the list, clearing all leads and resetting attempt counts. Check the script logs:

tail -f /var/log/astguiclient/ADMIN_manual_list_reset.log

Using the CLI for list diagnostics

Query the ViciDial database from the command line without entering MySQL:

mysql -u asterisk -p asterisk -e \
  "SELECT lead_id, phone, status, called FROM vicidial_list WHERE list_id = 101 LIMIT 10;"

Get a count by status:

mysql -u asterisk -p asterisk -e \
  "SELECT status, count(*) as count FROM vicidial_list WHERE list_id = 101 GROUP BY status;"

Find leads with callback scheduled:

mysql -u asterisk -p asterisk -e \
  "SELECT lead_id, callback_date, callback_notes FROM vicidial_callbacks \
   WHERE callback_date > NOW() ORDER BY callback_date LIMIT 20;"

Check for active agents on a list:

mysql -u asterisk -p asterisk -e \
  "SELECT user, status, lead_id FROM vicidial_agent_status \
   WHERE campaign = 'Outbound_Q4' AND status != 'OFFLINE';"

Connect to the Asterisk console to see if agents are paused or active:

asterisk -rx "vicidial show agents"

Hangup an agent's call:

asterisk -rx "channel request hangup SIP/2001"

Troubleshooting

Problem: Leads won't queue after resetting.

Check if the list itself is active:

SELECT active, campaign FROM vicidial_lists WHERE list_id = 101;

If active = 0, the list is paused. Set active = 1 to resume.

Problem: Deleted leads still appear in agent screen.

Agents may have cached the lead list in browser memory. Have them log out and log back in, or clear the browser cache.

Problem: Call logs show lead_id that no longer exists.

This is normal if you deleted leads after calls. To prevent orphaned logs in the future, use DEAD status instead of DELETE.

To see orphaned leads:

SELECT DISTINCT vl.lead_id FROM vicidial_log vl 
LEFT JOIN vicidial_list vl2 ON vl.lead_id = vl2.lead_id 
WHERE vl2.lead_id IS NULL LIMIT 20;

Problem: Bulk deactivation query timed out.

The vicidial_list table may lack indexes on frequently filtered columns. Add an index:

ALTER TABLE vicidial_list ADD INDEX idx_list_status (list_id, status);

Then retry the query.

Problem: Web interface is slow after bulk update.

ViciDial caches list state in memory. Restart the astguiclient services:

systemctl restart astguiclient

Wait 30 seconds for caches to rebuild.

Problem: Attempting to delete a lead returns foreign key constraint error.

A callback, inbound transfer, or agent note references this lead. Find and remove those references first:

SELECT * FROM vicidial_callbacks WHERE lead_id = 4521;
SELECT * FROM vicidial_inbound_anicode WHERE lead_id = 4521;
SELECT * FROM vicidial_agent_notes WHERE lead_id = 4521;

Delete or reassign those rows, then try deleting the lead again.

Frequently asked questions

Why does ViciDial mark calls as DEAD automatically?

ViciDial can be configured to auto-mark a lead as DEAD after a certain number of failed attempts (no answer, wrong number, answering machine). This is set in the campaign's dialer settings. If you want to disable auto-DEAD, go to Admin Campaigns, select your campaign, and set "Max attempts" to a high number (e.g., 999) or use a custom status like PAUSE instead. Leads marked DEAD manually will not be re-queued unless you reset them.

Can I export a list of deactivated leads?

Yes. Use the web interface (Admin Leads, Export) to download the list as CSV, or run a MySQL query and pipe it to a file: mysql -u asterisk -p asterisk -e "SELECT * FROM vicidial_list WHERE list_id = 101 AND status = 'DEAD';" > /tmp/deactivated_leads.txt. The CSV export includes all fields and can be reimported into another system for compliance records.

What happens to agent statistics if I delete a lead?

Deleting a lead does not erase the agent's call history or stats. The vicidial_closer_log records agent performance (talk time, dials, disposition). If you delete the lead after the call, the log entry remains but the agent can no longer view the lead's details in the agent screen. For this reason, use DEAD status instead of deletion if you want to preserve agent accountability.

Can I restore a deleted lead from backup?

Yes, but only if you have a database backup taken before the deletion. Restore the backup to a new database, extract the deleted lead row, and insert it into the production database. ViciDial does not have a trash/undelete feature for individual leads. Always backup before bulk delete operations: mysqldump -u asterisk -p asterisk vicidial_list > /tmp/backup.sql.

How do I reset leads without stopping active dialing?

Use the database directly (SQL UPDATE statements). Web interface resets may lock the list temporarily. When updating with SQL, the change takes effect immediately without stopping agents. However, agents who are already dialing a lead will not see the reset until they finish the call and the system refreshes the lead state (usually within 2-3 seconds).

Summary

You can now deactivate, reset, or delete leads in ViciDial using three approaches: the web interface for single leads and auditing, SQL UPDATE for bulk deactivation, and SQL DELETE for permanent removal (use sparingly). Deactivation (DEAD status) is the safest choice in production because it preserves call logs and agent accountability while removing leads from the dialing queue. Resetting clears the attempt counter and status, re-queuing a lead without losing history. Deleting is permanent and risks breaking callbacks and orphaning logs.

Always back up the database before bulk operations. Use START TRANSACTION and ROLLBACK if a query affects more rows than expected. After any bulk change, verify counts with SELECT queries and test with a single agent before resuming full-scale dialing. Run orphan log cleanup (DELETE from vicidial_log WHERE lead_id NOT IN...) monthly if you delete leads regularly, and add database indexes if bulk updates time out on large lists (100k+ leads).

Next steps: review the dialer campaign settings to confirm max-attempt rules are aligned with your deactivation policy, set up a monthly backup cron job if you have not already, and test a reset on a single lead during a quiet period to verify behavior matches your expectations.

Detecting Inbound Dead Air: Answered Calls Where Asterisk Never Accepts Carrier RTP

Moisi Trungu — Wed, 14 Oct 2026 03:30:02 +0000

Detecting Inbound Dead Air: Answered Calls Where Asterisk Never Accepts Carrier RTP

Some inbound calls answer normally at the SIP level, but the PBX never accepts a single RTP packet from the carrier. Asterisk already logs the evidence: a Strict RTP "learning" line that never turns into a lock or a source switch. Here's how I turned that into an alert, corroborated it with Homer RTCP, avoided the early-media trap, and used one SIP header to decide where to send the ticket.

Tested on: Asterisk 18 (ViciDial build, chan_sip, strictrtp=seqno, ConfBridge/softmix agent bridges), Loki, Homer with heplify-server on PostgreSQL 16. Check your Asterisk version's res_rtp_asterisk.c for the exact log wording.

What does inbound dead air look like?

The agent answers and hears nothing. SIP looks normal (INVITE, 183, 200 OK, ACK, BYE), the CDR shows a short answered call, and the agent gets blamed. The first one I caught sat in the agent's bridge for about 6 seconds. Asterisk's log showed the carrier's media address set from SDP, then nothing: no packet from that stream was ever accepted.

Then it stopped being a one-off. One morning, 26 answered inbound calls in 44 minutes had no carrier RTP accepted at the PBX, across three inbound trunks: 26 of the 125 calls on those trunks that reached an agent bridge, about one in five. The previous day's 12 business hours had 1,330 bridged calls on the same trunks and none like this. What this shows is that no carrier RTP was accepted at the PBX; assigning blame needs packet captures or carrier evidence.

Which Asterisk log lines show whether RTP arrived?

With strict RTP enabled (strictrtp=yes, the default, or seqno), res_rtp_asterisk.c logs the source-learning state of every RTP stream at verbose level 4. Real lines from my server, with addresses, IDs and dates replaced:

[15:33:36] VERBOSE[17871][C-0001a2b3] res_rtp_asterisk.c: 0x7f7f... -- Strict RTP learning after remote address set to: 198.51.100.23:45892
[13:42:40] VERBOSE[3563][C-0001a0f0] res_rtp_asterisk.c: 0x7f7e... -- Strict RTP learning complete - Locking on source address 203.0.113.10:10256
[13:43:01] VERBOSE[6158][C-0001a0f3] res_rtp_asterisk.c: 0x7f7f... -- Strict RTP switching to RTP target address 203.0.113.20:30818 as source
[13:43:01] VERBOSE[6158][C-0001a0f3] res_rtp_asterisk.c: 0x7f7e... -- Strict RTP switching source address to 192.0.2.108:41882

What matters is where in the source each one is printed (Asterisk 18):

"learning after remote address set to" comes from ast_rtp_remote_address_set(). It fires when the far end's address is set from SDP. No packet is involved. Call it the open.
"Locking on source address", "switching to RTP target address ... as source" and "switching source address to" are all printed in ast_rtp_read(), the incoming-packet path. Each one means a packet arrived and Asterisk accepted that source. Call any of them a close.

A missing close doesn't mean zero packets hit the NIC. Strict RTP silently drops packets (debug level only) while it qualifies a different source address, which takes 4 sequential packets by default. So an open with no close means Asterisk never accepted a stream for that call. A real 50-packet-per-second stream bridged for several seconds should get through probation from any address, so an unpaired open is a strong candidate, but only a candidate.

Also, SDP says where the carrier wants to receive media, not where it sends from. A different source shows up as "switching source address to ", so the code pairs any close of the same stream within the carrier's ranges. A source outside your map becomes a false candidate that RTCP refutes.

Prerequisites: messages must log verbose at level 4 or higher, and you must match all three close forms. Over about four months my messages file had 414,530 opens, 369,649 "Locking", 234,563 "switching to RTP target" and 101,985 "switching source address" lines. Match only "Locking" and you'll flag healthy calls.

How do I tell an answered inbound call from a ring that went nowhere?

Unanswered calls also leave unpaired opens, since many carriers send nothing before the answer: 16 of 42 in a two-hour window around the incident. So for each unpaired open, read the lines with the same C- ID and check:

Bridge evidence. In my ViciDial build the customer channel goes into a ConfBridge softmix conference: Channel SIP/<trunk>-xxxx joined 'softmix' base-bridge. Ring-group overflow via Dial() logs app_dial.c: SIP/... answered instead. The first such line is the join; left 'softmix' is the leave. MeetMe-based ViciDial setups log different lines.
Direction. The context must name the inbound trunk's channel and inbound dialplan context. With one peer name for both directions, a silent outbound leg looks identical at the RTP layer.
DID and caller ID, for the alert. MixMonitor and my dialplan's Phone call from ... line both run before the 200 OK, so neither proves an answer.

Here's the first incident, filtered to its C- ID:

15:33:36  Strict RTP learning after remote address set to: 198.51.100.23:45892
15:33:36  Executing [process@trunkinbound:10] Verbose("SIP/carrier_in-...", "Phone call from ...")
15:33:40  Executing [...] ConfBridge("SIP/carrier_in-...", "...,vici_agent_bridge,vici_customer_user")
15:33:40  Channel SIP/carrier_in-... joined 'softmix' base-bridge <...>
15:33:46  Channel SIP/carrier_in-... left 'softmix' base-bridge <...>

An open, a join, a leave six seconds later, no close.

This covers calls that reached a bridge. In the incident window one more call never locked: the PBX answered it into the queue and the carrier hung up 7 seconds later, before any agent. If queue dead air matters to you, anchor on the PBX's 200 OK instead.

How long should I wait for a close?

Don't measure the hold from the open, which happens when the call arrives: ring-group overflow calls ring a long time (48 s in a 12-hour sample).

Anchor on the join instead. From the raw log file over 12 business hours: 1,330 bridged inbound calls on the three trunks, every one closed, median close in the same second as the join, latest 2 s after it. These time the logged transition, not packet arrival, at one-second resolution. During the incident the latest healthy close was 5 s after the join.

My rule: no close for the call by join + 20 s. That's several times the worst case, and the candidate is ready well under a minute after the agent picks up.

What does the detector code look like?

My watcher reads the logs from Loki, but tailing messages works the same. This is the core matching logic, simplified from my production script with documentation-range addresses. It runs as shown:

import re

# One entry per inbound door. The SAME matcher is used for opens and closes.
CARRIERS = {
    "carrier_a":    {"media": (r"203\.0\.113\.\d+", r"198\.51\.100\.\d+"), "chan": "SIP/carrier_a_in_"},
    "carrier_b_nl": {"media": (r"192\.0\.2\.190",), "chan": "SIP/carrier_b_nl-"},
    "carrier_b_de": {"media": (r"192\.0\.2\.163",), "chan": "SIP/carrier_b_de-"},
}
for c in CARRIERS.values():
    c["re"] = re.compile(r"(?:%s):\d+" % "|".join(c["media"]))

# [C-call tag] ... res_rtp_asterisk.c: 0x<RTP instance> -- Strict RTP <event>
RE_STRICT = re.compile(r"\[(C-[0-9a-f]+)\] res_rtp_asterisk\.c: (0x[0-9a-f]+) -- Strict RTP (.*)$")
RE_OPEN = re.compile(r"learning after remote address set to: (\S+)")
RE_CLOSE = re.compile(r"learning complete - Locking on source address (\S+)"
                      r"|switching to RTP target address (\S+) as source"
                      r"|switching source address to (\S+)")


def media_carrier(ip_port):
    for name, c in CARRIERS.items():
        if c["re"].fullmatch(ip_port or ""):
            return name
    return None


def parse_lines(lines):
    """lines: [(ts_ns, text)] for ONE PBX, complete for the window.
    Returns (opens, closes, multi).
    opens: the FIRST carrier-facing stream of each call (the inbound leg's).
    closes: {(call_tag, rtp_instance): [(ts_ns, seq)]}, carrier-range only.
    multi: call tags that opened more than one carrier-facing RTP instance
    (e.g. an overflow dialled out through a carrier). Flag those for review.
    seq is the position after a stable sort by time, so same-second lines
    keep their order."""
    ordered = sorted(enumerate(lines), key=lambda x: (x[1][0], x[0]))
    opens, closes, first, instances = [], {}, {}, {}
    for seq, (_, (ts, line)) in enumerate(ordered):
        m = RE_STRICT.search(line)
        if not m:
            continue
        cid, inst, event = m.groups()
        o = RE_OPEN.match(event)
        if o:
            if not media_carrier(o.group(1)):
                continue
            instances.setdefault(cid, set()).add(inst)
            if cid not in first:     # later re-opens (re-INVITE) and other legs: not covered
                first[cid] = {"ts_ns": ts, "seq": seq, "cid": cid, "inst": inst,
                              "ip_port": o.group(1), "trunk": media_carrier(o.group(1))}
                opens.append(first[cid])
            continue
        c = RE_CLOSE.match(event)
        if c:
            ip_port = next(g for g in c.groups() if g)
            # any address in a carrier range, so a learned source change pairs
            if media_carrier(ip_port):
                closes.setdefault((cid, inst), []).append((ts, seq))
    multi = {cid for cid, s in instances.items() if len(s) > 1}
    return opens, closes, multi


def first_close(closes, o, upto_ns):
    """First close of the SAME call and SAME RTP instance after the open and
    no later than upto_ns. Another call reusing the port, or another leg of
    this call, can't pair it."""
    for ts, seq in closes.get((o["cid"], o["inst"]), []):
        if (ts, seq) > (o["ts_ns"], o["seq"]) and ts <= upto_ns:
            return ts
    return None

Every Strict RTP line carries the call's C- tag and the RTP instance pointer (0x...), so closes are keyed by both, not by port. Carriers reuse ports, so a match keyed on port can let a later call's lock "close" a dead one. Keying on the instance stops another leg of the same call from closing it too, for example an overflow dialled back out through a carrier. Calls with more than one carrier-facing instance come back in multi, so you can review them; my two days of raw logs had none. Only carrier-range closes count, so a ring-group phone's stream doesn't. The input must be complete and in time order; the stable sort keeps same-second lines in file order.

A Loki query that feeds it:

{server="pbx", job="asterisk"} |= "Strict RTP" |~ "203\\.0\\.113\\.\\d+|198\\.51\\.100\\.\\d+|192\\.0\\.2\\.190|192\\.0\\.2\\.163"

LogQL literals use Go escaping, so a regex \. is written \\.. query_range returns newest-first by default and silently stops at limit, so use direction=forward, split any window that hits the limit until none does, and merge before parsing. Then check the pipeline against the source: for one 12-hour window, two Loki runs gave 2,121 and 2,016 opens where the raw messages file had 2,284. All numbers here come from the raw file.

Each pass keeps as a candidate any bridged inbound call with no close by join + 20 s plus an ingest margin, and sends it to Homer before posting.

Opens and closes must use the same matcher: an alias of mine that matched one carrier's two POP ranges for opens but one for closes made every healthy call on the other POP a false candidate.

What can Homer RTCP add?

Your own RTCP corroborates the log signal; it comes from the same reception state, so it isn't independent proof. The carrier's RTCP, where it sends any, is the closest thing to independent evidence short of packet captures at both ends.

Your side. In Asterisk 18 a report carries a reception block once the far end's SSRC is recorded (themssrc_valid), which happens after a packet passes strict RTP and then stays set. RFC 3550 only requires blocks for sources heard since the previous report, so another stack may drop the block between bursts; check yours. heplify stores RTCP as JSON in hep_proto_5_default. In 128,786 reports around the incident, report_blocks was a non-empty array or null, never empty, missing or unparseable, but the SQL below still treats those as unclear rather than "nothing received".

Here are my side's reports for one dead call, in seconds relative to the 200 OK:

T-0.6  {"sender_information":{"packets":250,...},"report_blocks":null}   <- before the answer
T+4.4  {"sender_information":{"packets":491,...},"report_blocks":null}
T+9.4  {"sender_information":{"packets":741,...},"report_blocks":null}
T+14.4 {"sender_information":{"packets":991,...},"report_blocks":null}

We sent 50 packets a second; no far-end SSRC was ever recorded.

The carrier's side. Under RFC 3550, a participant that has sent RTP since its last report sends a Sender Report; otherwise a Receiver Report. heplify's decoder only fills sender_information for a Sender Report, so a Receiver Report shows zeros. The stored type is useless here (on compound packets it's the last sub-packet, 202 on most of my rows), so I test for a non-zero NTP timestamp; in one hour of my data it always coincided with a non-zero packet count. In that dead call every carrier report had a zero NTP timestamp, and a report block for our stream with the sequence number climbing about 200 every 4 s.

Over one hour on that carrier's trunks, all 85 calls where our side reported reception got real Sender Reports from the carrier (1,680 of 1,723 carrier reports had a sender timestamp). The dead calls got Receiver Reports only. That corroborates the log signal: the carrier's RTCP stack didn't consider itself a sender at its SBC. Corroboration, not proof, and silent about further upstream. The other carrier's relay sent no RTCP my capture saw.

Why is RTCP from before the answer meaningless?

The first report above was emitted before the 200 OK. My PBX replies with 183 Session Progress with SDP and starts early media (ringback) at once, then sends the final 200 OK on answer. So it emits RTCP during the ring, when a healthy carrier usually isn't sending yet.

In the hour before the incident, all 148 bridged calls with my RTCP had our 183 before the 200 OK. 48 had a report before the answer, and all 48 pre-answer reports had no receiver block. From 2 s after the answer it flipped: 2,420 reports, all with a block, and no healthy call where they were all empty.

In the incident window a call torn down 3.7 s after the answer had one pre-answer report from my side, with no block. On RTCP alone it looks dead, but the Asterisk log shows it locked at the answer.

The rule I use:

Refuted: any report from your side, at any time, has a non-empty block. Asterisk accepted a packet. Don't post.
Confirmed: at least one report from your side 2 s or more after the 200 OK, and none of your reports for the call, read through the end of the call, has a block.
Unknown: no post-answer report yet (very short calls, capture lag). Re-check next pass, and say so if it never settles.

All 26 incident calls came back confirmed: 1 to 5 post-answer reports each from my side, read 20 minutes past the answer (so through the end of every call), none with a block, and no Sender Report from either carrier.

How do I find the right Homer dialog for a log line?

Homer doesn't know the C- ID, but the carrier's SDP has the media ip:port. It's one statement, so no result from a previous call can leak in. Run it with psql -v pbx_ip=... -v sig_ips=a,b -v media_ip=... -v media_port=... -v open_ts='YYYY-MM-DD HH:MM:SS+00' -f. RTCP is joined to the dialog by sid, which only works if your heplify correlates RTCP to the SIP Call-ID (mine does; check a known call first). My raw columns are bytea; if yours are text, drop the convert_from(...) wrappers.

-- One statement, no carried-over variables. Inputs: pbx_ip, sig_ips (comma list),
-- media_ip, media_port, open_ts. Output: one row with a verdict.
WITH inv AS (   -- carrier INVITEs whose SDP carries the open's media endpoint
  SELECT i.sid,
         coalesce(substring(convert_from(i.raw,'UTF8') from '(?i)\nx-oid:\s*([^\r\n]+)'), '') AS x_oid
  FROM hep_proto_1_call i
  WHERE i.create_date BETWEEN :'open_ts'::timestamptz - interval '90 seconds'
                          AND :'open_ts'::timestamptz + interval '3 seconds'
    AND i.protocol_header->>'dstIp' = :'pbx_ip'
    AND i.protocol_header->>'srcIp' = ANY (string_to_array(:'sig_ips', ','))
    AND convert_from(i.raw,'UTF8') LIKE 'INVITE %'
    AND convert_from(i.raw,'UTF8') ~ ('\nc=IN IP4 ' || replace(:'media_ip', '.', '\.') || '\r?\n')
    AND convert_from(i.raw,'UTF8') ~ ('\nm=audio ' || :'media_port' || ' ')
), d AS (       -- exactly one dialog, or nothing
  SELECT min(sid) AS sid, min(x_oid) AS x_oid, count(DISTINCT sid) AS n FROM inv
), a AS (       -- first 200 to an INVITE, sent by the PBX
  SELECT d.*, (SELECT min(k.create_date) FROM hep_proto_1_call k
               WHERE d.n = 1 AND k.sid = d.sid
                 AND k.create_date BETWEEN :'open_ts'::timestamptz - interval '90 seconds'
                                       AND :'open_ts'::timestamptz + interval '10 minutes'
                 AND k.protocol_header->>'srcIp' = :'pbx_ip'
                 AND convert_from(k.raw,'UTF8') ~ '^SIP/2\.0 200 '
                 AND convert_from(k.raw,'UTF8') ~* '\ncseq:\s*[0-9]+\s+invite') AS t200
  FROM d
), r AS (       -- every RTCP report of that dialog, classified
  SELECT p.create_date, p.protocol_header->>'srcIp' AS src, x.j,
         CASE WHEN x.j IS NULL                                THEN 'unparsed'
              WHEN NOT x.j ? 'report_blocks'                  THEN 'missing'
              WHEN jsonb_typeof(x.j->'report_blocks') = 'null'  THEN 'none'
              WHEN jsonb_typeof(x.j->'report_blocks') <> 'array' THEN 'malformed'
              WHEN jsonb_array_length(x.j->'report_blocks') = 0 THEN 'empty'
              ELSE 'blocks' END AS rb
  FROM a
  JOIN hep_proto_5_default p
    ON p.sid = a.sid
   AND p.create_date BETWEEN a.t200 - interval '2 minutes' AND a.t200 + interval '20 minutes'
  CROSS JOIN LATERAL (SELECT CASE WHEN convert_from(p.raw,'UTF8') IS JSON
                                  THEN convert_from(p.raw,'UTF8')::jsonb END AS j) x
  WHERE a.n = 1 AND a.t200 IS NOT NULL
), s AS (
  SELECT
    count(*) FILTER (WHERE rb IN ('unparsed','missing','malformed','empty')) AS unclear,
    count(*) FILTER (WHERE src = :'pbx_ip' AND rb = 'blocks') AS pbx_with_block,
    count(*) FILTER (WHERE src = :'pbx_ip' AND create_date >= (SELECT t200 FROM a) + interval '2 seconds') AS pbx_post,
    count(*) FILTER (WHERE src = :'pbx_ip' AND rb = 'none'
                     AND create_date >= (SELECT t200 FROM a) + interval '2 seconds') AS pbx_post_none,
    count(*) FILTER (WHERE src <> :'pbx_ip' AND jsonb_typeof(j->'sender_information') = 'object'
                     AND (j->'sender_information'->>'ntp_timestamp_sec') ~ '^[0-9]+$'
                     AND (j->'sender_information'->>'ntp_timestamp_sec')::numeric > 0) AS far_end_sr
  FROM r
)
SELECT a.n AS dialogs, a.t200, a.x_oid, s.*,
  CASE WHEN a.n <> 1 OR a.t200 IS NULL             THEN 'unknown'
       WHEN s.pbx_with_block > 0                    THEN 'refuted'
       WHEN s.unclear > 0 OR s.pbx_post = 0         THEN 'unknown'
       WHEN s.pbx_post_none = s.pbx_post            THEN 'confirmed'
       ELSE 'unknown' END AS verdict
FROM a, s;

The INVITE window allows 3 s of clock skew after the open. The verdict is unknown unless exactly one dialog matched and it has a PBX 200 whose CSeq method is INVITE, or if any report is unclear (unparsed, missing, malformed or empty report_blocks). All 26 incident calls came back confirmed, each matching exactly 1 dialog with no carrier re-INVITEs and no sendonly/inactive. A healthy control call came back refuted. The 3.7 s early-media call came back unknown. Always bound create_date: a day-wide version of a similar join hit my 5-minute timeout.

How did one SIP header point to a shared upstream?

The 26 calls came through three doors: 14 on Carrier A's direct trunk, 7 via Carrier B's NL-labelled SBC and 5 via its DE-labelled SBC. Three trunks failing in the same 44 minutes suggested something shared upstream.

The clue was in Carrier B's INVITEs, which carry an extra header:

INVITE sip:...                              (from Carrier B's SBC)
Call-ID: <a UUID, Carrier B's own format>
X-OID: <an ID in Carrier A's Call-ID format>

INVITE sip:...                              (from Carrier A's direct trunk)
Call-ID: <Carrier A's format>

Carrier B's own Call-IDs are UUIDs. The X-OID value has the same distinctive multi-field layout as Carrier A's Call-IDs on my direct trunk. It was on all 12 Carrier B dead calls, and that day on 651 of 651 inbound dialogs from the DE-labelled SBC and 346 of 349 from the NL-labelled one. The three without it showed one of our own extension or agent names in the From display name; I didn't dig further.

That doesn't prove Carrier A originated them. Shared SBC software could produce the same format, and simultaneous failures don't locate a fault. But it changed what I did: I widened the watcher, which had missed the 12 Carrier B calls, and put X-OID in every alert and ticket. Carrier B can confirm it against the upstream leg in its own signalling trace. Look at a full INVITE from each of your trunks for similar headers.

How do I keep the watcher from going silently blind?

A detector that finds nothing looks healthy. Each guard is a reason to investigate, not a diagnosis:

Empty is never clean. No strict-RTP lines? Check the PBX stream has any recent lines; warn after 24 hours without them.
Freshness. Newest PBX line older than 45 s? Skip the pass without advancing coverage. Tune it to your traffic.
Coverage per trunk. Hourly, for each trunk with 10+ inbound calls, count how many opened a stream on a mapped address. Below half means the media moved, the log format changed, or the classifier broke. One carrier's media move left my watcher blind until this check existed.
Keep Homer off the critical path. Short timeout, per-pass budget. A candidate still unsettled after 10 minutes is posted as "unconfirmed" only if bridged within 20 s of the open, in the bridge 5 s or more, and still unclosed.
Replay. A --dry-run mode with --start/--end runs the same rule over a past window and writes nothing. I replayed this version over the previous week before switching.

What doesn't this catch?

Silent RTP. Packets can flow with 0% loss and carry near-silence. For a complaint, check the recording's inbound leg.
Media that stops later. A stream that locks and then dies mid-call is out of scope. So is a re-INVITE whose new stream never locks.
Calls that never reach a bridge. See the queued call above.
Who hung up. Don't assume it was the caller giving up. In the 26 incident calls, the first BYE came from the PBX side on 15 and from the carrier on 11.

FAQ

Could my own firewall or NAT be the cause? Possibly; this method alone can't rule it out. What pointed away from my side: 99 calls on the same trunks were fine in the same minutes, the trunks were clean the day before, and Carrier B's RTCP showed no Sender Reports on its dead calls. For certainty, capture packets on the PBX interface during an occurrence and compare with the carrier's capture.

Ghost Answers: Detecting SIP 200 OK Without SDP From Your Carrier

Moisi Trungu — Tue, 13 Oct 2026 03:30:02 +0000

Ghost Answers: Detecting SIP 200 OK Without SDP From Your Carrier

A ghost answer is a call your carrier marks as answered with a 200 OK that carries no SDP, after which your own switch tears the call down the moment it is answered. Asterisk reports a healthy answer rate while your dialer logs a pile of zero-second no-answers. Here is how I tracked one carrier doing this, with the Homer SQL, Asterisk log lines and CDR joins I used to prove it.

Tested on: ViciDial 2.14 (SVN r3988) with Asterisk 18.26 (chan_sip), MariaDB 10.11, and Homer 7 using heplify-server 1.59.6 with the homer7 schema on PostgreSQL 16. In this install hep_proto_1_call.raw is a varchar. If yours stores raw as bytea, wrap it as convert_from(raw, 'UTF8') before applying the text functions below.

What is a ghost answer?

On a normal outbound SIP call the far end answers with 200 OK and an SDP body that says where to send audio and which codec to use. Your side sends ACK, RTP flows, and the call has a conversation.

A ghost answer breaks that. The carrier sends 200 OK with an empty body. No SDP, no media address, no codec. Depending on what happened earlier in the call, Asterisk either falls back to the media details from an earlier 183 Session Progress, or it gives up and sends BYE right after its own ACK. In the second case the gap between ACK and BYE is typically a fraction of a millisecond.

Is an SDP-less 200 OK legal? It depends. With reliable provisional responses (100rel and PRACK, RFC 3262) the answer can arrive in a 183, and the 200 does not have to repeat it. Without them, RFC 3261 section 13.2.1 is blunt: when the offer is in the INVITE, the answer must be in a reliable message, "For this specification, that is only the final 2xx response to that INVITE."

In my capture window, all 23,167 initial INVITEs to my three carriers carried an SDP offer, none advertised 100rel, no 180 or 183 carried RSeq or Require: 100rel, and Homer saw zero PRACKs. So these 200s were missing the SDP answer that this exchange required. Beyond the RFC, what makes it a ghost answer is scale and outcome: one route doing it on most answers while your other routes do it on none, and a large share of those calls being torn down instantly.

How did the problem first show up in my numbers?

I run a press-1 survey campaign that splits outbound traffic randomly across three carriers, one third each, on the same lead lists. One morning the dialer-side answer rate on one carrier, Carrier A, was half of what it had been the day before. The other two had not moved.

The odd part was that the Asterisk-side answer rate had barely changed. ViciDial's vicidial_carrier_log table records the DIALSTATUS Asterisk saw for each call. Joining that to vicidial_log (the disposition the dialer finally recorded for the lead) showed the gap:

Day	Carrier	Dials	Asterisk ANSWER rate	Dialer answer rate	ANSWER but logged NA
Day 1	Carrier A	88,019	32.2%	31.2%	83
Day 1	Carrier B	87,962	38.3%	36.2%	56
Day 1	Carrier C	87,483	40.0%	39.1%	25
Day 2	Carrier A	84,793	31.6%	15.6%	13,041
Day 2	Carrier B	85,337	38.3%	36.1%	28
Day 2	Carrier C	85,363	39.1%	38.2%	13

"Asterisk ANSWER rate" is the share of dials where Dial() returned ANSWER. It is measured on my side, not taken from the carrier's reports. "Dialer answer rate" is the share of dials whose ViciDial disposition was anything other than a no-answer, busy, disconnect or drop.

Carrier A's ANSWER rate stayed around 32%. But overnight, roughly half of those answers turned into NA records in vicidial_log, every one of them with length_in_sec = 0. Over the next seven dialing days Carrier A produced between 12,963 and 17,459 of these per day. The other two carriers stayed between 10 and 60 per day.

The signal is the disagreement between the two rates; either one alone looks unremarkable.

That table is from an incident a few months ago. My Homer instance only keeps three days of SIP, so I no longer have the signaling for those days. The same carrier was still doing it when I wrote this, and every SIP-level number below comes from a live capture of that current traffic. That the July discrepancy had the same cause is an inference, not something I can still prove from packets.

How do I measure the gap between Asterisk answers and dialer answers?

You need two things: the per-call DIALSTATUS from Asterisk, and a way to know which carrier each call took. ViciDial gives you the first in vicidial_carrier_log. For the second, I log the carrier at dial time into a small attribution table (carrier_route_log here: uniqueid, carrier, call_date) from the dialplan. That table joins to vicidial_carrier_log on uniqueid, because both are written with the dial-time uniqueid.

The join to vicidial_log is the tricky part. On my install, answered calls in vicidial_log do not carry the dial-time uniqueid: on one day, 9,542 answered-status rows had just 1 match in my attribution table, while all 16,744 no-answer/busy/drop rows matched. A uniqueid join therefore loses exactly the calls you care about. I join on lead_id plus a time window instead, and count matches per call so I can see when the join misbehaves:

SELECT d, carrier, COUNT(*) dials,
  SUM(ds='ANSWER') ast_answer,
  ROUND(100*SUM(ds='ANSWER')/COUNT(*),1) ast_answer_pct,
  SUM(nmatch=0) unmatched, SUM(nmatch>1) multi,
  SUM(ds='ANSWER' AND st='NA') ans_but_na,
  SUM(ds='ANSWER' AND st='NA' AND len=0) ans_but_na_0s,
  ROUND(100*SUM(nmatch=1 AND st NOT IN
    ('NA','AB','ADC','DC','B','CONGST','DROP'))/COUNT(*),1) dialer_answer_pct
FROM (
  SELECT DATE(c.call_date) d, r.carrier, c.uniqueid, c.dialstatus ds,
         COUNT(vl.uniqueid) nmatch, MAX(vl.status) st, MAX(vl.length_in_sec) len
  FROM vicidial_carrier_log c
  JOIN carrier_route_log r USING(uniqueid)
  -- scope the dial cohort to the campaign BEFORE joining dispositions
  JOIN vicidial_list l   ON l.lead_id  = c.lead_id
  JOIN vicidial_lists ls ON ls.list_id = l.list_id
                        AND ls.campaign_id = 'YOUR_CAMPAIGN'
  LEFT JOIN vicidial_log vl
    ON vl.lead_id = c.lead_id AND vl.campaign_id = 'YOUR_CAMPAIGN'
   AND vl.call_date BETWEEN c.call_date - INTERVAL 5 SECOND
                        AND c.call_date + INTERVAL 120 SECOND
  WHERE c.call_date >= CURDATE() - INTERVAL 1 DAY
    AND c.call_date <  CURDATE()
  GROUP BY c.uniqueid) x
GROUP BY d, carrier;

The campaign filter has to sit on the dial cohort, not just on the vicidial_log side. Otherwise other campaigns' dials stay in the denominator and simply show up as unmatched. I scope by the campaign that owns the lead's list. On my install that removed 98 dials from another campaign on one day out of more than two million, and no other day had any. Before trusting it, check three things for your interval:

One dial per lead per day. On every day in my table, zero leads were dialed more than once, so a lead_id join cannot pick up the wrong attempt. Check yours with a GROUP BY lead_id, DATE(call_date) HAVING COUNT(*) > 1.
multi is near zero. Mine never exceeded 1 per carrier per day.
unmatched is explained. Mine were mostly BUSY calls whose vicidial_log row landed outside the window. Between 1.8% and 5.6% of ANSWER rows were unmatched on the day I checked, so the dialer answer rate is a slight undercount for all three carriers.

The window is wide on purpose. In the sample call I trace below, the vicidial_log row was stamped 43 seconds after the dial started.

Treat ans_but_na as a screening metric, not a ghost counter. An ANSWER that ends up NA with zero length is what a ghost answer looks like in the CDRs, but other faults could produce the same row. On a clean route it is a few dozen per day out of tens of thousands of answers. When one route jumps to thousands, go to the SIP capture to confirm what is happening.

What does a ghost answer look like in Asterisk logs?

chan_sip logs a warning when it receives an SDP-less 200 OK it cannot use:

WARNING[10434][C-01204f61] chan_sip.c: Received response: "200 OK" from 'carrier_a' without SDP

Here is one complete ghost call from the full log, trimmed to the interesting lines:

[09:02:16] app_dial.c: Called SIP/carrier_a/39XXXXXXXXXX
[09:02:19] app_dial.c: SIP/carrier_a-00d92d01 is making progress passing it to Local/...;2
[09:02:19] app_dial.c: Call on SIP/carrier_a-00d92d01 placed on hold
[09:02:19] res_musiconhold.c: Started music on hold, class 'default', on channel 'Local/...;2'
[09:02:28] chan_sip.c: Received response: "200 OK" from 'carrier_a' without SDP
[09:02:28] app_dial.c: SIP/carrier_a-00d92d01 answered Local/...;2
[09:02:28] bridge_channel.c: Channel SIP/carrier_a-00d92d01 joined 'simple_bridge' basic-bridge <...>
[09:02:28] bridge_channel.c: Channel SIP/carrier_a-00d92d01 left 'simple_bridge' basic-bridge <...>
[09:02:28] pbx.c: Executing [h@default:1] AGI("Local/...;2", "agi://127.0.0.1:4577/call_log--HVcauses--PRI-----NODEBUG-----16-----ANSWER-----11-----0-----SIP 200 OK)")

The SIP channel joins the bridge and leaves it in the same second. The hangup handler records DIALSTATUS=ANSWER after 11 seconds of dial time. ViciDial then logged this lead as NA with length_in_sec = 0.

These commands assume the default full log format with timestamps like [Oct 5 09:02:29]. To count warnings per hour per peer:

awk -F"'" '/Received response: "200 OK" from .* without SDP/ {
  split($0, a, ":"); print substr(a[1], 2), $2 }' /var/log/asterisk/full | sort | uniq -c

And to compare against total answers on that carrier over the same hour:

awk '/^\[Oct  5 09:/' /var/log/asterisk/full | \
  grep -cE 'app_dial.c(:[0-9]+)?: SIP/carrier_a-[0-9a-f]+ answered'
awk '/^\[Oct  5 09:/' /var/log/asterisk/full | \
  grep -cE 'Received response: "200 OK" from .carrier_a. without SDP'

If you use ISO timestamps (dateformat in logger.conf), adjust the hour extraction to match.

Does the Asterisk warning catch every SDP-less 200 OK?

No, and this matters. On one dialer, Homer saw 1,304 SDP-less 200 OK answers from Carrier A during my window, but Asterisk logged far fewer warnings. To see which calls the warnings belonged to, I matched them one by one. For every call answered before the cutoff where Asterisk sent BYE within 50 ms of its ACK, I took the dialed number from Homer. Then I matched each warning line to the dialed number in the Called SIP/... line with the same C- call ID. On that dialer, 595 calls appeared in both lists, with none left over on either side. On a second dialer it was 84 and 84.

So each warning is one call that Asterisk killed, and SDP-less answers that survived produce no warning. The reason is in chan_sip's handle_response_invite() (Asterisk 18 branch source; the build I tested was 18.26.4):

} else if (!reinvite) {
    struct ast_sockaddr remote_address = {{0,}};

    ast_rtp_instance_get_requested_target_address(p->rtp, &remote_address);
    if (ast_sockaddr_isnull(&remote_address) || (!ast_strlen_zero(p->theirprovtag) && strcmp(p->theirtag, p->theirprovtag))) {
        ast_log(LOG_WARNING, "Received response: \"200 OK\" from '%s' without SDP\n", p->relatedpeer->name);
        ast_set_flag(&p->flags[0], SIP_PENDINGBYE);
        ast_rtp_instance_activate(p->rtp);
    }
}

When a 200 OK arrives without SDP, chan_sip checks whether it already has a remote media address (normally from an earlier 183 with SDP) and whether the To-tag matches the provisional response. If the address is missing, or the tag changed, it logs the warning and sets SIP_PENDINGBYE, which schedules a BYE once the ACK is out. If it already has a usable address, it silently carries on with the early-media details, and the call can survive.

The practical lesson: a grep 'without SDP' count is a count of warning events, which on my system matched the killed calls one for one. Use Homer for the real count of SDP-less answers.

How do I find ghost answers in Homer?

heplify-server writes SIP calls into hep_proto_1_call (registrations and other methods go to separate tables), with the full message in raw, addresses in protocol_header, and parsed cseq, method and callid in data_header. Using the parsed fields is more robust than regexing headers yourself, because heplify has already handled case and compact header forms.

The queries below count answered dialogs, not messages, and must run in one psql session because they build temp tables and use psql variables. They take each initial INVITE transaction (no To-tag) that your dialers sent inside a cohort window, keep the first 200 OK per dialog, and check the body for real SDP instead of trusting Content-Length. A dialog is matched exactly on Call-ID, our From-tag and the carrier's To-tag, the tags compared as parsed values, so a forked answer would show up as its own row. Messages are collected over a longer observation window than the INVITE cohort, so a call dialed at 09:59:58 and answered at 10:00:02 is still counted:

SET TIME ZONE 'UTC';
-- cohort = INVITEs sent in [c_start, c_end); observe their messages until o_end
\set c_start '''2026-10-05 00:00'''
\set c_end   '''2026-10-05 07:45'''
\set o_end   '''2026-10-05 08:00'''

-- 1. every message of every call your dialers sent to a carrier in the cohort window
CREATE TEMP TABLE m AS
SELECT create_date t,
       protocol_header->>'srcIp' src, protocol_header->>'dstIp' dst,
       data_header->>'method'   meth,
       data_header->>'callid'   callid,
       data_header->>'from_tag' ftag,
       split_part(data_header->>'cseq', ' ', 1) cseqn,
       split_part(data_header->>'cseq', ' ', 2) cseqm,
       substring(split_part(raw, E'\r\n\r\n', 1)
         from '(?in)^(?:to|t)[ \t]*:[^\r\n]*;[ \t]*tag=([^;>,[:space:]]+)') ttag,
       substr(raw, length(split_part(raw, E'\r\n\r\n', 1)) + 5) body
FROM hep_proto_1_call
WHERE create_date >= :c_start AND create_date < :o_end
  AND sid IN (SELECT sid FROM hep_proto_1_call
              WHERE create_date >= :c_start AND create_date < :c_end
                AND data_header->>'method' = 'INVITE'
                AND protocol_header->>'dstIp' IN
                    ('203.0.113.10', '203.0.113.20', '203.0.113.30'));  -- carrier IPs
CREATE INDEX ON m (callid);

-- 2. initial INVITE transactions (no To-tag) sent inside the cohort window
CREATE TEMP TABLE inv AS
SELECT callid, cseqn, MIN(ftag) ftag, MIN(dst) carrier, MIN(src) dialer
FROM m
WHERE meth = 'INVITE' AND ttag IS NULL
  AND dst IN ('203.0.113.10', '203.0.113.20', '203.0.113.30')
GROUP BY callid, cseqn
HAVING MIN(t) < :c_end;

-- 3. first 200 OK per answered dialog: Call-ID + our From-tag + their To-tag
--    (one row per fork if the carrier answers more than one early dialog)
CREATE TEMP TABLE ok AS
SELECT DISTINCT ON (i.callid, i.cseqn, m.ttag)
       i.callid, i.cseqn, i.ftag, i.carrier, i.dialer, m.ttag, m.t t200,
       (m.body ~ '(?n)^v=0' AND m.body ~ '(?n)^m=audio') has_sdp
FROM inv i
JOIN m ON m.callid = i.callid AND m.cseqn = i.cseqn AND m.cseqm = 'INVITE'
      AND m.meth = '200' AND m.src = i.carrier AND m.ftag = i.ftag
ORDER BY i.callid, i.cseqn, m.ttag, m.t;

-- 4. per-carrier share of answered calls with no SDP, plus sanity counters
SELECT carrier, COUNT(*) answered_dialogs,
       SUM((NOT has_sdp)::int) no_sdp,
       ROUND(100.0 * SUM((NOT has_sdp)::int) / COUNT(*), 1) pct_no_sdp
FROM ok GROUP BY carrier ORDER BY carrier;

SELECT (SELECT COUNT(*) FROM inv) cohort_invites,
       (SELECT COUNT(*) FROM (SELECT callid FROM ok GROUP BY callid
                              HAVING COUNT(*) > 1) x) calls_with_forks,
       (SELECT COUNT(*) FROM inv i WHERE NOT EXISTS
          (SELECT 1 FROM m WHERE m.callid = i.callid AND m.cseqn = i.cseqn
             AND m.cseqm = 'INVITE' AND m.meth ~ '^[2-6][0-9][0-9]$')) pending;

The window values are an example; they are what I used. The cohort is calls whose INVITE went out between midnight and 07:45 UTC on the day I checked (dialing started around 07:00), observed until 08:00. It returned:

Carrier	Answered calls	200 OK without SDP
Carrier A	2,366	1,475 (62.3%)
Carrier B	2,755	0 (0.0%)
Carrier C	3,682	0 (0.0%)

All 1,475 of Carrier A's SDP-less 200s had a completely empty body. heplify-server's Dedup option was off on my install. I checked the window for duplicate captures and retransmitted INVITEs or 200s and found none. Of the 23,167 cohort INVITEs, none had more than one answered fork and none were still pending at the end of the observation window.

Run it as docker exec -i <postgres-container> psql -U homer -d homer_data if Homer runs in Docker. The SET TIME ZONE 'UTC' makes the window and any timestamps you print explicit. On my system Asterisk logs in local time (UTC+2), so the same call shows up two hours apart in the two sources.

Why does my Homer query flag clean carriers too?

Because of one innocent-looking filter. The obvious quick way to restrict raw messages to answers of INVITEs is:

AND raw LIKE '%CSeq:%INVITE%'

That also matches the 200 OK to a BYE or CANCEL, because those responses carry an Allow: header after the CSeq line:

CSeq: 104 BYE
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY, INFO, PUBLISH, MESSAGE

%CSeq:%INVITE% happily spans from CSeq: to the INVITE in Allow:. Counting raw 200 OK messages from my three carriers over the morning, the sloppy filter returned 12,453 messages. Only 8,754 of them were answers to an INVITE.

Those BYE and CANCEL responses normally have no body, so they look exactly like ghost answers. With the sloppy filter, Carrier C had 7,363 matching messages instead of 3,664, and showed up as 50.2% "without SDP" when the real figure was zero. Carriers A and B were unaffected only because none of their BYE or CANCEL responses matched the pattern. You cannot count on that.

If you do filter raw text, anchor the method to the CSeq line itself (raw ~ 'CSeq: [0-9]+ INVITE'). Better still, use the parsed data_header->>'cseq' field as in the query above.

How do I measure how fast the call dies?

For each SDP-less answer, find the ACK for that INVITE CSeq in the same dialog (same Call-ID, From-tag and To-tag), and the first BYE in that dialog in either direction. A BYE we send carries our tag in From; a BYE from the carrier has the tags swapped. Then classify, keeping incomplete and impossible cases visible instead of letting them fall into a bucket:

-- same psql session as the previous query (reuses temp tables m and ok)
CREATE TEMP TABLE g AS
SELECT o.*,
  (SELECT MIN(t) FROM m
    WHERE m.callid = o.callid AND m.meth = 'ACK' AND m.cseqn = o.cseqn
      AND m.ftag = o.ftag AND m.ttag = o.ttag AND m.t >= o.t200) tack,
  b.t tbye, b.src bye_src, b.dir bye_dir
FROM ok o
LEFT JOIN LATERAL (
  SELECT t, src,
         CASE WHEN m.ftag = o.ftag THEN 'ours' ELSE 'theirs' END dir
  FROM m
  WHERE m.callid = o.callid AND m.meth = 'BYE' AND m.t >= o.t200
    AND ((m.ftag = o.ftag AND m.ttag = o.ttag)      -- BYE sent by us
      OR (m.ftag = o.ttag AND m.ttag = o.ftag))     -- BYE sent by the carrier
  ORDER BY t LIMIT 1) b ON true
WHERE NOT o.has_sdp;

SELECT carrier,
       CASE WHEN tack IS NULL OR tbye IS NULL THEN 'incomplete'
            WHEN tbye < tack THEN 'negative'
            WHEN tbye - tack < interval '50 ms' THEN 'instant'
            ELSE 'survived' END AS cls,
       COUNT(*) calls,
       SUM((bye_dir = 'ours')::int) bye_from_us,
       ROUND((percentile_cont(0.5) WITHIN GROUP
         (ORDER BY EXTRACT(EPOCH FROM tbye - tack)))::numeric * 1000, 3) AS median_ms
FROM g GROUP BY 1, 2 ORDER BY 1, 2;

Of Carrier A's 1,475 SDP-less answers, 681 (46.2%) were instant: the BYE followed the ACK by a median of 0.038 ms, and by at most 18 ms. In all 681 the BYE was ours: our tag in From, sent from the same dialer IP the 200 OK was delivered to. From the 200 OK itself to the BYE, the median was 0.3 ms. The other 794 survived, with a median of 5.4 seconds between ACK and BYE. None were negative, and none were incomplete. If you run it while calls are still up, the last few minutes of the cohort will show incomplete rows, which is what that bucket is for.

These calls had 183s with SDP, so early media could have flowed before the answer, and I have not checked RTP for them. What a BYE less than a millisecond after the ACK does show is that my side tore the call down immediately on answer, leaving no room for a post-answer conversation. If you need to prove what audio was or wasn't present, you need the RTP or a recording. Signaling alone won't tell you.

What does the SIP ladder look like?

Here is the Homer ladder for the same call I showed from the Asterisk log (addresses replaced with documentation ranges, timestamps UTC):

07:02:16.827944  dialer  -> carrier  INVITE                       CSeq: 102 INVITE  CL: 334
07:02:16.830601  carrier -> dialer   100 Giving it a try          CSeq: 102 INVITE  CL: 0
07:02:19.240142  carrier -> dialer   183 Session Progress         CSeq: 102 INVITE  CL: 254  c=198.51.100.7
07:02:19.433423  carrier -> dialer   183 Session Progress         CSeq: 102 INVITE  CL: 254  c=203.0.113.10
07:02:19.546739  carrier -> dialer   183 Session Progress         CSeq: 102 INVITE  CL: 254  c=203.0.113.10
07:02:19.661336  carrier -> dialer   183 Session Progress         CSeq: 102 INVITE  CL: 254  c=203.0.113.10
07:02:28.020534  carrier -> dialer   200 OK                       CSeq: 102 INVITE  CL: 0
07:02:28.042133  dialer  -> carrier  ACK                          CSeq: 102 ACK
07:02:28.042431  dialer  -> carrier  BYE                          CSeq: 103 BYE
07:02:28.045899  carrier -> dialer   200 OK                       CSeq: 103 BYE

The ACK and the BYE are 0.3 ms apart, and the BYE went out 22 ms after the 200 OK arrived. If you prefer watching live on the dialer, sngrep -c host 203.0.113.10 shows only INVITE dialogs to and from that carrier, and you can open any call to get the same ladder.

To pull a ladder like this from Homer, grab the sid of the INVITE and list every message in that dialog:

SET TIME ZONE 'UTC';
SELECT to_char(create_date,'HH24:MI:SS.US') t,
       protocol_header->>'srcIp' src, protocol_header->>'dstIp' dst,
       split_part(raw, E'\r\n', 1) first_line,
       data_header->>'cseq' cseq,
       substring(raw from '(?i)Content-Length: *[0-9]+') cl,
       substring(raw from 'c=IN IP4 [0-9.]+') c_line
FROM hep_proto_1_call
WHERE sid = '<sid>'
ORDER BY create_date;

Why do some ghost answers die and others survive?

Look at the SDP in those 183s. The first one says a=sendrecv from one media address. The second switches to a different address and a=sendonly. That matches the "placed on hold" log line from the same second.

I checked this across the whole sample. For each SDP-less call I took the last 183 with SDP that arrived before the 200 OK in the same dialog. I split its SDP into media sections at each m= line and read the direction attribute from the audio section, falling back to a session-level attribute (before the first m=) and then to the sendrecv default. Every one of those 183 SDPs had exactly one media section, audio. For 680 of the 681 instant kills the direction was sendonly, and the remaining one had no 183 with SDP at all. The two clean carriers sent about 7,000 183 messages with SDP each, and none of them had a sendonly audio section. The killed calls also averaged about 1.7 distinct media addresses across their 183s, versus about 0.7 for the survivors.

I'd call that a strong correlation rather than the full mechanism. Among the 794 survivors, 120 also ended ringing on a sendonly 183 and still lived, and 384 had no 183 with SDP at all. So sendonly alone does not decide it. What I can say for certain is that the calls that die are the ones where chan_sip hits the branch in the code above. For detection you do not need to know more than that.

Can I just fail over to another carrier on ghost answers?

Not with a normal DIALSTATUS failover. My dialplan already reroutes on carrier errors. This is a fragment: FBCNT is initialized earlier, DSTR holds the dial string, and the end and fb labels are defined further down:

exten => _88X.,n,Dial(${DSTR})
exten => _88X.,n,GotoIf($[${FBCNT}>=2]?end)
exten => _88X.,n,GotoIf($["${DIALSTATUS}"="CONGESTION" | "${DIALSTATUS}"="CHANUNAVAIL"]?fb)

A ghost answer returns DIALSTATUS=ANSWER, exactly like a real answer, so it bypasses this fallback completely. What happens to the lead afterwards depends on your campaign. On mine the call is dispositioned NA, so whether it gets dialed again comes down to your recycling rules, not your dialplan.

The response that works is at the route level:

Reweight the split. With a RAND()-based split, take the ghosting carrier out of the random pick or give it a small share. On ViciDial, make the change in the carrier's dialplan entry in the admin GUI so it survives config regeneration.
Keep a small share flowing if you need ongoing evidence. A few percent of traffic is enough to keep the Homer query and the ans_but_na column telling you whether the carrier fixed it.
Re-check daily. In my case it went from a small baseline to thousands of calls a day overnight. It can stop or change just as abruptly, and you want to know when.

What evidence should I send the carrier?

"Your ASR dropped" goes nowhere; their answer rate looks fine. Send them their own signaling:

The Homer per-carrier table: share of answered calls whose 200 OK had no SDP, theirs versus your other carriers on the same traffic, same time window.
Two or three full SIP ladders with Call-ID, timestamps and the raw 200 OK, showing the empty body. Include one where the 183 flips to sendonly.
The RFC reference. If the INVITE carried an SDP offer and the 183s were not sent reliably, quote RFC 3261 section 13.2.1. The 200 OK is missing the SDP answer this exchange required. That turns "your ASR looks odd" into a specific protocol fault their engineers can check.
The daily table of Asterisk ANSWER versus dialer-answered calls, starting a few days before the change, so the step is obvious.
An invoice question. Ask them to confirm whether calls answered without SDP and released within a second are billed. If they are, ask for a credit on those calls from the start date.

Keep the Call-IDs in the ticket. Those are what their NOC can actually look up.

How do I watch for this going forward?

Put two checks on a schedule:

The per-call Homer query, run hourly with the previous complete hour as the INVITE cohort and an observation window that runs at least 15 minutes past it, so calls answered after the hour boundary still count. Report the pending counter alongside it. Alert when a carrier has a meaningful number of answered calls (I'd want at least a hundred) and more than a few percent of them have no SDP. Exclude calls where a reliable 183 (with RSeq) already carried the SDP answer, because those 200s are legitimately empty. On my traffic there were none, and clean routes sat at 0.0%.
The ans_but_na daily query, run on the previous complete day. Alert on the ratio of ans_but_na to ast_answer per carrier rather than the raw count, so volume changes and partial days don't trigger it.

If your Homer retention is short, run the Homer check while the data still exists. Mine keeps three days, so a weekend is enough to lose the SIP evidence for a Friday incident. Save the query output and a handful of ladders as soon as you notice something.

FAQ

Is a 200 OK without SDP always fraud? No. With 100rel and PRACK (RFC 3262) the answer can come in a reliable provisional response, and the 200 does not need to repeat it. I can't tell you whether my carrier did it on purpose or broke something. It becomes your problem when one route does it on most answers, your other routes do it on none, and the calls produce no conversation.

Does this affect billing? That depends on whether your carrier bills calls with a sub-second or zero answered duration. Check your invoice detail for the affected period before you assume either way.

AI Voice Agent Pilot vs Production: Lessons From Real Outbound Calls

Moisi Trungu — Mon, 12 Oct 2026 03:30:02 +0000

AI Voice Agent Pilot vs Production: Lessons From Real Outbound Calls

A self-hosted AI phone agent can pass every demo and still fail on real outbound traffic. This is a case study of an Italian-language dental agent on Asterisk, fed by a ViciDial press-1 campaign. It covers what broke once real callers reached it: call identity, latency under load, answering machine detection, an overflowing context window, safety guards, and retrieval. The measured numbers come from the system's own traces, database rows, CDRs or test output. Where something is an observation and not a controlled result, I say so.

Configuration snapshot, September 2026: Asterisk 20.6 on the agent host; ViciDial on Asterisk 18.26.4-vici (ViciDial's patched build) on the dialer; AudioSocket; Silero VAD 6.2; faster-whisper 1.2.1 (large-v3); Ollama 0.30.8 with llama3.1:8b (num_ctx 4096); Qdrant 1.18; one 20 GB workstation GPU. Italian TTS was a hosted streaming service, with local Kokoro/Piper code as a fallback. Earlier experiments ran on earlier spec versions of the same stack.

What was the setup?

ViciDial press-1 campaign -> SIP -> Asterisk (agent host)
  -> AGI (stage a session) -> AudioSocket (8 kHz 16-bit PCM over TCP)
  -> Python gateway: Silero VAD -> faster-whisper -> LLM (Ollama) -> TTS
  -> audio back over the same socket

ViciDial dials the leads. The callee hears a short recorded message and presses 1, and ViciDial sends the call to the agent host. The agent speaks Italian and has one job: find out whether the caller has a dental need, then get them to send two photos of their teeth over WhatsApp so a human can prepare a free quote.

Basic demos sounded good. Targeted tests and real-call reviews did not. The checklist at the end sums up what we learned.

Why did the audit call it "a pilot, not production"?

About two weeks after real press-1 calls started, we ran a read-only production-readiness audit. Its first line said: "operational pilot, not ready for an unattended production service." The GPU, models and health checks were fine. What failed was the integration around them.

The worst finding was a P0 in the first step every call runs. The dialplan called a shell AGI script before AudioSocket, and the script read its AGI environment like this:

while read -r line; do
  [ -z "$line" ] && break
  export "$line"
done

Asterisk sends AGI variables as agi_request: something, with a colon and a space. That is not a shell assignment, and you can reproduce the failure in one line (123.4 is a made-up uniqueid):

/bin/sh -c 'while read -r line; do [ -z "$line" ] && break; export "$line"; done; echo REACHED' <<'EOF'
agi_request: prepare.sh
agi_uniqueid: 123.4

EOF
# /bin/sh: 1: export: agi_request: prepare.sh: bad variable name
# exit=2

The script died before it staged anything. In the gateway's session_prepared events, agent, direction and provider reference were all null. The dialplan also passed a hard-coded UUID per language to AudioSocket(), so every Italian call reached the gateway with the same 3333... UUID. The gateway used that UUID to pick the language line, not to identify the call. Linking a conversation back to its ViciDial lead took a timestamp join.

A demo call doesn't show this, because the agent still answers and talks.

The fix was a small Python AGI that treats AGI input as a protocol, never as shell code:

import re

def read_environment(stream):
    """Read AGI 'agi_key: value' lines until the blank line."""
    result = {}
    for line in stream:
        line = line.rstrip('\r\n')
        if not line:
            break
        key, sep, value = line.partition(':')
        if sep and re.fullmatch(r'agi_[a-z0-9_]+', key):
            result[key] = value.lstrip()
    return result

After reading the environment, the script sets an 8-second signal.alarm. Inside that deadline it reads its config, checks the gateway readiness URL (when one is configured), logs in, generates uuid.uuid4(), stages the session and returns the IDs with SET VARIABLE. The deadline does not cover the initial environment read or the final SET VARIABLE FLOW_STAGE_OK 0 on the error path. If you copy this design, put those under a timeout too.

The dialplan checks the result. This excerpt is from the deployed context (the channel is answered earlier, at Answer()):

 same => n,Set(FLOW_STAGE_OK=0)
 same => n,AGI(prepare.sh,${EXTEN})
 same => n,GotoIf($["${FLOW_STAGE_OK}" != "1"]?flow_unavailable)
 same => n,ExecIf($["${CALLSESSIONID}" != ""]?Set(CDR(userfield)=${CALLSESSIONID}))
 same => n,ExecIf($["${FLOW_VICI_CID}" != ""]?Set(CDR(userfield)=${CDR(userfield)}|vici:${FLOW_VICI_CID}))
 same => n(gw),AudioSocket(${FLOW_CALL_UUID},${FLOW_AUDIO_GW})
 ...
 same => n(flow_unavailable),Playback(custom/agent-unavailable)
 same => n,Hangup(41)

As deployed, the failure path plays an "unavailable" message and hangs up. That fails closed, but no human or callback destination exists yet.

On the dialer side, ViciDial adds its caller code as a SIP header (SIPAddHeader(X-vici-cid: ${CALLERID(name)})), and the agent host reads it with PJSIP_HEADER(read,X-vici-cid). For one real call after the fix, the IDs line up like this (values shortened):

Where	Field	Value
ViciDial `vicidial_log_extended`	`caller_code` / `uniqueid` / `lead_id`	`V917…174` / `…793.36` / `…174`
Agent-host CDR	`userfield`	`\
Agent-host CDR	{% raw %}`uniqueid`	`…818.512`
Agent-host CDR	`lastdata` (AudioSocket UUID)	`d26f…6beb`
Gateway `session_prepared`	`callSessionId`, `asteriskUuid`, `externalProviderRef`	`<sessionId>`, `d26f…6beb`, `…818.512`

The two uniqueids differ. The caller code in the header and the CDR links them.

Two more blockers:

No durable outcome. The application's lead table held 0 records across 229 agent conversations (test calls included). The code synced leads only when inline state parsing succeeded. That path was switched off, so the deferred extractor saved state but never created a lead.
The release gate published first and tested second. The deploy script switched the live spec before it ran the text gate. The gate also skipped any sentence that contained a negation. It flagged "Le ho inviato il messaggio" ("I've sent you the message", a false claim of action) but missed "Non si preoccupi, le ho inviato il messaggio" ("Don't worry, I've sent you the message").

How did latency hold up with several calls at once?

Badly. Single post-deploy canary calls got their first reply in 1.7 to 2.2 s. We then ran six synthetic AudioSocket conversations at once, with Ollama set to three parallel slots. The time from the caller finishing a sentence to the first agent audio was:

4893, 5011, 5020, 8257, 9051, 9320 ms   -> median 6.64 s, worst 9.32 s

Cutting the reply cap from 140 to 90 tokens gave a median of 5.27 s and a worst case of 8.60 s. That is one small run per setting, so treat it as a direction, not a percentile. The gateway advertised 10 calls and the upstream route allowed 6. Nobody had measured whether either limit could hold acceptable latency.

The cache matters too: an uncached five-session run hit 19.3 s, while a warm ten-session run with identical caller text topped out at 4.85 s.

Lesson: benchmark several concurrency levels with varied caller audio and a cold cache. Set admission control from the measured p95. Send overflow to a real destination, not to Congestion.

Should you keep ViciDial AMD in front of an AI agent?

For us, no. The campaign used a ViciDial survey extension that runs Asterisk's AMD() before routing:

exten => 8373,n,Playback(sip-silence)
exten => 8373,n,AMD(2000,2000,1000,5000,120,50,4,256)
exten => 8373,n,AGI(VD_amd.agi,${EXTEN})

VD_amd.agi copies the AMDSTATS channel variable into run_time, in milliseconds. Stock Asterisk AMD doesn't set AMDSTATS. ViciDial's patched -vici build does, and on our dialer every row in the window had it populated. The script writes to vicidial_amd_log only when $AMD_LOG is 2 or 3. Ours was 3. Check both before you rely on this query:

SELECT a.AMDSTATUS, a.AMDRESPONSE, vl.status,
       COUNT(*) n, COUNT(DISTINCT a.uniqueid) calls,
       ROUND(AVG(CAST(a.run_time AS UNSIGNED))/1000,2) avg_s,
       ROUND(MAX(CAST(a.run_time AS UNSIGNED))/1000,2) max_s   -- run_time is VARCHAR
FROM (SELECT uniqueid, AMDSTATUS, AMDRESPONSE, run_time FROM vicidial_amd_log
        WHERE call_date BETWEEN '2026-09-14 15:00:00' AND '2026-09-14 16:05:50'
      UNION ALL
      SELECT uniqueid, AMDSTATUS, AMDRESPONSE, run_time FROM vicidial_amd_log_archive
        WHERE call_date BETWEEN '2026-09-14 15:00:00' AND '2026-09-14 16:05:50') a
JOIN vicidial_log vl ON vl.uniqueid = a.uniqueid
WHERE vl.campaign_id = 'YOUR_AI_CAMPAIGN'
GROUP BY 1,2,3;

The inner join drops AMD rows with no matching vicidial_log row (25 in this window, most from other campaigns). It produced 168 rows for 168 distinct calls in the hour before the change:

AMD result	ViciDial status	Calls	Avg AMD run time
HUMAN	sent to call menu (SVYCLM)	43	3.17 s
NOTSURE / TOOLONG	sent to call menu (SVYCLM)	30	3.31 s
NOTSURE / NOAUDIODATA	sent to call menu (SVYCLM)	15	4.80 s
NOTSURE / TOOLONG	dropped (PDROP)	1	2.16 s
MACHINE (initial silence, long greeting, max words)	hung up (AA)	79	3.25 s

The 88 calls sent on to the call menu spent an average of 3.50 s in AMD (maximum 5.02 s) first. 79 of 168 (47%) were hung up as machines. A person who pauses or says more than "Pronto?" can trip any of the three machine causes. We didn't listen to the AA calls, so the false-positive share is unknown.

We switched the campaign to the same survey extension without AMD (8366) and compared the gateway's own traces for each window. The gateway count (84) uses a slightly different window from the SQL above:

Window	Calls reaching agent	Caller said any words	Ended < 9 s, no speech	Voicemails caught by gateway
With AMD (15:10 to 16:05)	84	12%	74%	1
Without AMD (16:05 to 16:25)	54	30%	43%	9

This is a before/after observation, not a randomized test. The windows differ in length and time of day, and the lead mix may differ. In this sample, more callers spoke after AMD came out. The cost is that answering machines now reach the agent. The gateway caught 9 of them in that window with an Italian transcript regex ("dopo il segnale acustico", "non è raggiungibile", mailbox menus). We don't know how many it missed. Any it misses run until the idle timeout and hold a call slot.

We also tested one off-the-shelf audio AMD checkpoint, a whisper-tiny telephony classifier. We ran it offline on 15 calls from that day. The input was the first 3 s of the caller channel after the first audible sample, resampled to 16 kHz, and we took the top class. The reference labels came from the gateway traces, not from listening: a voicemail detection meant "machine", two or more substantive transcripts meant "human".

labelled n= 15
HUMAN recall: 3/4 = 75%
MACHINE recall: 0/11 = 0%

So the checkpoint agreed with 0 of 11 trace-labelled machines, calling all of them human. We didn't validate the labels by ear or establish why it disagreed, so treat this as a reason to test any AMD model on your own labelled calls before trusting it.

What happens when the prompt outgrows the context window?

The always-on responseConstraints block in the agent spec kept growing as we added rules to discipline the 8B model. It went from 6,534 to 14,268 characters between two spec versions, with num_ctx at 4096. After that release, calls felt slower and replies drifted.

To test the prompt in isolation, we ran an A/B probe against the same model. Knowledge, history and question were identical. Only the constraints block changed. Each variant got one warm-up request, then four sequential requests, and we report the medians:

[v34] prompt_tok=4095  prefill_ms=1609  out_tok~140  decode_ms=3436  TOTAL_ms=5335
[v35] prompt_tok=2243  prefill_ms=22    out_tok~71   decode_ms=1474  TOTAL_ms=1660

A prompt count of 4095 against a 4096 context strongly suggests the prompt was being cut. The long variant's median output also hit the 140-token cap. In this probe, compacting the block to 5,834 characters cut the median total from 5.3 s to 1.7 s.

The problem came back. Under a newer spec, long calls pushed prompts past 4096 again. Ollama logs a warning each time it truncates. To count them for one UTC day (ollama is your container name):

docker logs --since 2026-09-17T00:00:00Z --until 2026-09-18T00:00:00Z ollama \
  > /tmp/ollama-day.log 2>&1 || echo "log fetch failed"
grep -c "truncating input prompt" /tmp/ollama-day.log
# 78
# msg="truncating input prompt" limit=4096 prompt=4173 keep=4 new=4095

On that same day, callers heard replies such as "Sembra che il cliente abbia risposto al telefono... posso continuare seguendo le istruzioni fornite" ("It seems the customer has answered the phone... I can continue following the instructions provided"). Another offered to "fare una simulazione della conversazione" ("run a simulation of the conversation"). We didn't match each of these replies to a specific truncated request. The pattern fits a model that has lost part of its instructions, but treat that link as a hypothesis.

Lesson: budget tokens in code. Keep the fully rendered prompt plus a reserve for the reply under the context window. Alert on the daily truncation count, because the runtime doesn't fail. It just quietly gets worse.

Are prompt rules enough to keep an 8B model safe?

No. The clearest example was a clinical rule: never suggest full-arch treatment ("All-on-4", "riabilitazione dell'arcata") to someone who is missing only one or two teeth. The rule was in the prompt, and one run of the adversarial eval still produced this:

Caller: "Mi mancano due denti davanti." ("I'm missing two front teeth.")
Agent: "...La soluzione per te potrebbe essere l'All-on-4 o All-on-6..." ("...The solution for you could be All-on-4 or All-on-6...")

In a scripted golden conversation, the caller said "A me mancano due denti" ("I'm missing two teeth") and the model answered "visto che mancano tutti i denti" ("since all your teeth are missing").

The fix was deterministic code. A per-turn eligibility scope classifies the caller's own words as "few" or "many" missing teeth. When the answer is "few", full-arch FAQs are dropped from retrieval and a speech guard scrubs full-arch phrases from the output. Here is an excerpt (not a complete program) of the detection patterns and test cases, from the Python mirror of the production C# code:

# excerpt: FEWMISS = "few teeth missing"; SOLO and CNT are small helper patterns
FEWMISS = re.compile(
    r"manca(?:no)?\s+" + SOLO + CNT + r"?\s*(?:dent|incisiv|molar|canin|premolar)"
    r"|\bmi\s+manca\b|\bme\s+ne\s+manca(?:no)?\b"
    # ... more alternatives omitted ...
    , re.IGNORECASE)

DETECTION_CASES = [
    (["mi mancano due denti"], True),
    (["non sono senza denti, me ne mancano due"], True),
    (["ho solo due denti"], False),
    (["mi sono rimasti due denti"], False),
    (["ho perso tutti i denti", "in realtà me ne mancano due"], True),
    # ... 20 more ...
]

The full regression corpus has 25 detection cases and 41 output-scrub cases, and all 66 pass. It tests a Python mirror of the production C# patterns, not every streamed chunk boundary, cache hit and fallback in the deployed build. That needs integration tests against the deployed version. A reviewer also found a phrasing the corpus misses: the mirror classifies "non ho solo due denti, me ne mancano due" ("I don't have only two teeth, I'm missing two") as near-total loss. Regex guards are only as good as their adversarial cases. After the guard went in, the same eval answered "impianti singoli o un piccolo ponte" ("single implants or a small bridge").

The same went for formal address ("Lei"), hallucinated phone numbers and meta-replies: the prompt rule came first and failed in testing, then code guards replaced it.

Can a safety guard break the business goal?

Yes, and nothing alerts you when it happens. The goal was to give interested callers the WhatsApp number. A guard stopped the model from giving the number before the caller agreed. At the time, the affirmative branch was a short full-match allowlist ("sì", "va bene", "d'accordo", "certo", "ok"), plus exceptions for explicit requests such as "mi dia il numero". Real callers answered the invite with things like "Va bene, ci penso e poi ve la mando. Di dove siete?" ("OK, I'll think about it and send it. Where are you based?"), which failed the match. The guard then deleted the model's number sentence.

Our proxy was the number of calls in which an agent_reply event contained the spelled-out country-code prefix of the number:

2026-09-08: 2 of 86       2026-09-16: 0 of 1049  (guard stripped it in 17 calls)
2026-09-09: 1 of 380      2026-09-17: 1 of 1001  (stripped in 16)
2026-09-11: 1 of 386      2026-09-21: 1 of 880
2026-09-15: 0 of 778      2026-09-22: 2 of 1300

This is a text proxy, not proof of what the caller heard. In the one Sep 17 call where the number appeared, playback events show it came out garbled and the caller interrupted. For more than two weeks, the main conversion step barely appeared even in the logged text, while call volumes looked healthy.

Lesson: every guard needs a counter. Measure the conversion step from playback events, then spot-check against recordings.

What do real calls reveal that test calls don't?

We reviewed one full day of traces (1,001 calls, 385 with any transcribed caller speech) and found failure modes that no synthetic test had produced.

Stuck VAD on stalled audio. 30 calls ran past 60 s with no transcribed caller speech. Every one had an unmatched vad_start and no idle reprompt, and ended when the AudioSocket peer closed, at about 185 s or about 315 s. Together they took roughly 99 gateway-session minutes. We didn't check CDRs for how much of that was billed. The cause was in the gateway code: the VAD force-end only ran inside the per-frame audio handler. When AudioSocket frames stopped arriving mid-utterance, in_speech stayed true, and that blocked the idle and max-duration timers. Here is a filter for candidate calls, written for our trace schema (one JSONL file per call, rel = seconds since the call started):

import glob, json, sys

TRACE_DIR, DAY = sys.argv[1], sys.argv[2]   # e.g. ./traces 20260917

for path in sorted(glob.glob(f"{TRACE_DIR}/{DAY}-*.jsonl")):
    heard = vad_open = reprompted = False
    duration = end_reason = None
    with open(path) as fh:
        for line in fh:
            try:
                e = json.loads(line)
            except ValueError:
                continue
            t = e.get("type")
            if t == "stt" and (e.get("text") or "").strip():
                heard = True
            elif t == "vad_start":
                vad_open = True
            elif t == "vad_end":
                vad_open = False
            elif t == "idle_reprompt":
                reprompted = True
            elif t == "call_end":
                duration, end_reason = e.get("rel"), e.get("hangupReason")
    if duration and duration > 60 and not heard and vad_open and not reprompted:
        print(path, round(duration), end_reason)

The fix belongs in a watchdog outside the audio callback. If in_speech is set and no frame has arrived for a few seconds, close the utterance so the normal idle reprompt and goodbye logic can run. Keep that separate from any decision to hang up, and keep an absolute call deadline as well. Don't hang up just because media went quiet: a legitimate call can be silent, and some endpoints use silence suppression.

IVR loops. The backend's transfer intent matched "prema 1" ("press 1"). So did a restaurant's phone menu, and the agent answered it with the same canned line 24 times. Cap identical consecutive replies.

Losing people at the greeting. In the first two days of real calls (37 calls), 15 callers hung up during the greeting without saying a word. All 5 callers whose first sentence named a concrete need (a quote, a denture, implants, yellow teeth, a full set of teeth) were tagged as leads in our review. That is a small sample, and stating a need naturally predicts a lead tag. We didn't test what caused the early hangups. Our working hypothesis is the opening, and it needs a controlled test.

"Grazie a tutti" was also the first transcribed "utterance" in three of those calls, a known Whisper output on silence. Discard such phrases only when VAD or no-speech evidence agrees, since a person can really say them.

Does RAG help a small model on the phone?

Less than we assumed. We replayed 292 real caller utterances offline: 241 from this agent and 51 from the hosted platform described below. The replay used the live embedder (nomic-embed-text), a read-only search of the live Qdrant collection, and a copy of the production ranking logic. For the 136 utterances that were real questions or objections, we hand-labelled the correct FAQ:

Measure	Result
Top-1 correct, live query (prev. turn + utterance)	54 / 136 (40%)
Top-1 correct, raw utterance only	68 / 136 (50%)
None of the top 3 correct	57 / 136 (42%)
Top-1 correct, by source (live query)	this agent 47/107, hosted 7/29
Lowest top-1 / third-ranked cosine, all 292	0.66 / 0.62

The live config had contextMinScore: 0.52. Even the third-ranked candidate never scored below 0.62, so that cut-off removed nothing in this replay. Prepending the previous caller turn ("contextual" query) cost about 10 points of top-1 accuracy compared with the raw utterance. Correct and wrong top-1 hits had overlapping scores, so a higher cut-off alone discards correct answers too.

Lesson: replay labelled, real utterances against your index before you trust it. Pick a threshold by measuring accuracy, coverage and false rejections on those labels, and allow retrieval to return nothing.

Was a hosted no-code voice platform the answer?

We ran a hosted no-code voice-agent platform in parallel on cold outbound calls, with a 52-node conversation flow. From its own call export over about ten days:

Metric	Value
Real outbound dials	12,160
Connected	4,285
Calls where a human spoke (platform label)	2,363
Of those, left during the intro (platform label)	2,156 (91%)
Tagged "warm"	5
Tagged "agreed to send photos"	0
Total platform cost	about $266

The labels come from the platform's own LLM post-call analysis, and we had no separate downstream outcome data. Like our agent, it lost most callers early. Testing a different opening is the next experiment. Nothing here shows whether the opening matters more than the model.

What does a production readiness checklist look like?

Each item comes from a failure above.

Call identity and integration

[ ] AGI input parsed as a key: value protocol, never exported or evaled. Tested offline with real AGI headers.
[ ] A unique AudioSocket UUID per call. A documented mapping from dialer uniqueid to agent-host uniqueid to session to recording, checked on real calls.
[ ] A timeout around the whole staging step, including input and error handling. On failure, the dialplan goes to an approved human or callback destination.
[ ] A consenting, qualified test call creates exactly one lead/task row in the application database. Separately, test that a refusal and an opt-out are stored correctly.

Capacity and latency

[ ] Concurrency measured at several levels with a cold cache and varied caller audio, reporting p50 and p95 from the caller's end of speech to the first agent audio.
[ ] Admission limit set from that measurement. Overflow goes to a human queue or a callback, not Congestion.

Dialer front end

[ ] AMD run time measured from vicidial_amd_log.run_time, after confirming that AMDSTATS is populated and DB logging is on.
[ ] If AMD stays on, false positives sampled by listening to AA recordings.
[ ] Voicemail detection validated on labelled calls in your own language.

LLM and prompt

[ ] Worst-case rendered prompt (long call, injected FAQs, full history) plus a reply reserve fits under num_ctx, enforced in code.
[ ] Daily count of "truncating input prompt" warnings, with an alert.
[ ] Safety rules that matter have deterministic guards, a regression corpus, and integration tests on the deployed build, including streamed output.

Guards and funnel

[ ] Every guard logs when it fires, and someone reviews the counts daily.
[ ] The conversion step measured from playback events and spot-checked against recordings.
[ ] When a guard empties a reply, a spoken fallback line plays instead of silence.

Real-call hygiene

[ ] A watchdog outside the audio callback closes stuck utterances. Hangup policy is separate and tested with silent callers.
[ ] Identical consecutive replies capped, to break IVR loops.
[ ] Suspected Whisper silence hallucinations discarded only when VAD/no-speech evidence agrees.

Retrieval

[ ] Hit@1 measured on real, labelled caller utterances.
[ ] Threshold chosen on labelled accuracy and false rejections. Retrieval can return zero results.

Release

[ ] The candidate is gated before it takes traffic, with a manifest (spec, KB, code, config, models) and a rehearsed rollback.

What would I do differently?

I'd build the measurement before the agent: per-call identity, a playback-based funnel, guard counters and a concurrency benchmark. Demos and service dashboards missed nearly every problem here. Targeted tests and real-call reviews exposed them.

Detecting False Answer Supervision (FAS) Carrier Fraud

Moisi Trungu — Sun, 11 Oct 2026 03:30:03 +0000

Detecting False Answer Supervision (FAS) Carrier Fraud

False Answer Supervision means your carrier answers calls that no human ever picked up, then bills you for them. You can catch it with CDR queries, a duration histogram, and one SIP capture. I hunt for it on a production campaign where two carriers run a 50/50 split on identical traffic, so every metric below comes with a built-in control group.

Tested on: ViciDial 3.x, Asterisk 13-18, MariaDB 10.x, Homer 7.10. The SQL targets ViciDial's vicidial_log, but the method works on any Asterisk CDR table.

What is False Answer Supervision?

FAS is when a carrier (or someone upstream of them) sends 200 OK on a call that was never really answered. Your switch starts the billing clock, your dialer marks the call answered, and the money goes to whoever faked the answer signal.

It comes in several flavors, and I've seen most of them on real traffic:

Pure FAS: 200 OK arrives before the callee's phone even rings. Your IVR plays to nobody.
Early-media FAS: the carrier answers, then plays ringback tone on the RTP stream. Your AMD hears ringing after "answer" and misclassifies wildly.
Short FAS: answer, a few seconds of silence or a fake announcement, hangup at 3-30 seconds. Small per call, huge at volume.
Call stretching: the callee hangs up but the carrier holds the billing leg open for extra seconds.
Voicemail simulation: a slice of your traffic gets routed to fake voicemail prompts and billed at full duration.

The nasty part: FAS makes your stats look better. ASR and answered-call counts both climb, and nobody investigates a dashboard that just improved.

Why is FAS so hard to spot in normal reports?

Because every individual call record looks legitimate. The fraud only shows up in distributions, and only when you have something to compare against.

The single best setup for catching FAS is an A/B split: route the same traffic 50/50 across two carriers and compare them. Same destinations, same time of day, same lead lists. Any large divergence between the two sides is a carrier-side effect, not a traffic effect. If you only have one carrier, compare against your own historical baseline instead.

How do I split traffic across two carriers for comparison?

In the Asterisk dialplan, randomize the carrier per call and log which one each call took:

exten => _9911X.,1,Set(CARRIER=${IF($[${RAND(1,2)}=2]?carrier_a:carrier_b)})
exten => _9911X.,n,System(/usr/local/sbin/log_carrier.sh ${UNIQUEID} ${CARRIER})
exten => _9911X.,n,Dial(SIP/${CARRIER}/${EXTEN:4},,tTo)

log_carrier.sh is a two-line script that inserts (uniqueid, carrier, now()) into an attribution table, say carrier_route_log. Now every CDR can be joined to the carrier that handled it.

Gotcha that cost me a week: on answered calls, ViciDial's call_log AGI rewrites vicidial_log.uniqueid to the carrier leg's uniqueid. The uniqueid you captured at dial time never matches for answered calls, so your join silently loses exactly the calls you care about. Check your tag coverage per status before trusting any per-carrier number:

SELECT vl.status, COUNT(*) total,
       SUM(crl.uniqueid IS NOT NULL) tagged
FROM vicidial_log vl
LEFT JOIN carrier_route_log crl USING(uniqueid)
WHERE vl.call_date >= NOW() - INTERVAL 1 HOUR
GROUP BY vl.status;

If answered statuses show near-zero coverage, capture the carrier in a hangup handler with CDR(dstchannel) instead of ${UNIQUEID}.

Which CDR metrics expose FAS?

Run a per-carrier triage card over the last few hours:

SELECT
  crl.carrier,
  COUNT(*) dialed,
  ROUND(100*SUM(vl.status NOT IN ('NA','AB','ADC','DC'))/COUNT(*),1) AS asr_pct,
  ROUND(AVG(IF(vl.status NOT IN ('NA','AB','ADC','DC'),
      vl.length_in_sec, NULL)),1) AS acd_sec,
  SUM(vl.length_in_sec BETWEEN 1 AND 15) AS short_calls,
  ROUND(SUM(vl.length_in_sec BETWEEN 1 AND 15) /
      NULLIF(SUM(vl.status IN ('NA','AB')),0), 3) AS fasr
FROM carrier_route_log crl
JOIN vicidial_log vl USING(uniqueid)
WHERE vl.call_date >= NOW() - INTERVAL 6 HOUR
GROUP BY crl.carrier;

How to read it:

Metric	Clean route	FAS suspect
ASR delta between carriers	under ~10%	over 30% on identical traffic
ACD on answered calls	stable, similar both sides	one side several seconds shorter
FASR (short calls ÷ failed calls)	under 0.30	over 0.30; over 1.0 is near-certain

The FASR ratio (short answered calls divided by no-answers) comes from a Datanomers fraud-detection patent. A carrier faking answers converts would-be no-answers into short billed calls, so the ratio climbs on the dirty route while staying flat on the clean one.

What does a FAS duration histogram look like?

FAS rigs cut calls at fixed points. Humans don't. Pull a per-second histogram of answered call durations:

mysql -u USER -p asterisk -BN -e "
SELECT length_in_sec, COUNT(*)
FROM vicidial_log
WHERE call_date >= NOW() - INTERVAL 6 HOUR
  AND status NOT IN ('NA','AB','ADC','DC')
  AND length_in_sec BETWEEN 1 AND 60
GROUP BY length_in_sec;" | \
awk '{a[$1]=$2; if($2>m)m=$2} END{for(s=1;s<=60;s++){n=a[s]+0;
  printf "%2ds %5d ",s,n; for(i=0;i<40*n/(m+1);i++)printf "#"; print ""}}'

An isolated spike at 28, 30, 45, or 60 seconds with empty neighbors is a cutoff, not human behavior.

One warning before you accuse anyone: know your legitimate peaks. On an IVR campaign, every no-input call lands at exactly audio length + menu timeout. My survey audio ran 21.7 seconds with a 6-second DTMF window, so a huge honest spike sat at 28 seconds. I verified all 1,948 calls in that bucket were normal completions before looking further. Compute your expected peak first, then investigate everything else.

How do I confirm FAS at the SIP level?

Two signatures, both visible in Homer (or any HEP capture, or even sngrep):

1. Post-dial delay that's too fast. PDD is the time from INVITE to 200 OK. Real mobile calls in Europe take 3-6 seconds to answer at minimum: the network has to page the handset and the human has to react. A carrier answering in under 1 second is structurally impossible without FAS. Query your HEP database for per-destination-IP PDD percentiles and count sub-1-second answers. More than ~5% sub-1s on one carrier IP is a red flag.

2. 200 OK with no ringing phase. A real call almost always shows INVITE → 180/183 → 200. Pure FAS often goes straight INVITE → 200. A small baseline is normal (some carriers only send 100 Trying), but if more than 10% of one carrier's calls skip ringing entirely, that route deserves a hard look.

Can I hear FAS in the recordings?

Yes, and it's the most convincing evidence you can attach to a dispute. Record the inbound leg (-in.wav in Asterisk's monitor directory) and check what the carrier actually delivered after "answer":

import wave, numpy as np
w = wave.open('leg-in.wav','rb')
n = min(int(w.getframerate()*5), w.getnframes())
b = np.frombuffer(w.readframes(n), dtype=np.int16).astype(float)
rms = np.sqrt(np.mean(b**2))
sp = np.abs(np.fft.rfft(b)); fr = np.fft.rfftfreq(len(b), 1/w.getframerate())
band = sp[(fr>=400)&(fr<=480)].sum()/sp.sum()
print(f"RMS={rms:.0f}  peak={fr[np.argmax(sp)]:.0f}Hz  ringband={band:.0%}")

RMS under 50: silence. Normal for an IVR call where the callee just listens.
RMS over 500 with 25%+ energy at 400-480 Hz: that's a ringback tone after answer. Early-media FAS, caught on tape.
RMS over 500 with speech-band content on calls your agents never spoke on: a carrier announcement or bot loop, billed as conversation.

Bonus signal for IVR campaigns: DTMF response rate per carrier. Fake answers don't press 1. If one carrier's press-through rate is a fraction of its twin's on identical traffic, the "answered" calls on that route have nobody on them.

What's the definitive FAS test?

Dial a number that cannot answer. A confirmed-unallocated number must return 404 Not Found or 484 Address Incomplete. If the carrier returns 200 OK, that is conclusive. There is no innocent explanation for answering a number that doesn't exist.

asterisk -rx 'sip set debug ip 203.0.113.10'
asterisk -rx 'originate SIP/carrier_a/UNALLOCATED_NUMBER application Hangup'
asterisk -rx 'sip set debug off'

Use a number you control or one your national numbering plan documents as unassigned. One probe per carrier is enough; this is a diagnostic, not a load test. For continuous unattended probing, voip_patrol runs scripted test calls from cron.

What do I do once a carrier is confirmed dirty?

Stop the bleeding. Reweight the dialplan RAND() to send 100% to the clean carrier, or set the bad carrier inactive. On ViciDial, edit the carrier's dialplan entry in the admin GUI so the change survives config regeneration.
Build the evidence pack: the triage card, the histogram, the PDD stats, one SIP ladder showing INVITE → 200 with no ringing, one recording of post-answer ringback, and the unallocated-number probe. That combination is very hard to argue with.
Dispute the invoice. Carriers know exactly what FAS is. A billing dispute backed by SIP captures usually gets credited quietly. If it doesn't, you already stopped routing to them.
Keep the A/B split running. FAS is rarely constant. It appears on specific destination prefixes at specific times. A permanent 90/10 split with the triage card on a cron is cheap insurance.

FAQ

Does high ASR always mean FAS? No. A carrier with better routes genuinely completes more calls. FAS shows as high ASR combined with short ACD, high FASR, impossible PDD, and low human-response signals. One metric is a hint; four together is a case.

Can FAS happen on inbound? The common inbound equivalent is call stretching, meaning duration padding after hangup. Compare your CDR durations against the far end's records if you suspect it.

My carrier blames their upstream. Does that matter? Not to you. You bought termination from them; where in their chain the fraud happens is their problem. The evidence pack works either way.

How to Configure ViciDial Closer Campaigns & In-Groups

Moisi Trungu — Sat, 10 Oct 2026 03:30:04 +0000

How to Configure ViciDial Closer Campaigns & In-Groups

Master the complete process of setting up closer campaigns and in-groups in ViciDial, from database configuration through agent assignment and real-time monitoring.

Prerequisites

Before proceeding with closer campaign and in-group configuration, ensure you have:

ViciDial installation (3.14+ recommended) with working Asterisk (16+)
Database access: Direct MySQL/MariaDB access to the asterisk database
Admin credentials: Access to /vicidial/admin.php with administrator role
Asterisk CLI access: Ability to run asterisk -rx commands
Existing dialplans: At least one active dialer campaign configured
User accounts: Multiple agents already created in ViciDial system
In-group defined: A primary in-group created before closer assignment
SSH/Shell access to ViciDial server with sudo privileges

Understanding Closer Campaigns vs In-Groups

What Are Closer Campaigns?

Closer campaigns are ViciDial's mechanism for transferring live inbound calls or callbacks to specific agents who specialize in closing sales. Unlike dialer campaigns that push calls outbound, closer campaigns pull inbound calls into a queue for assignment to available agents.

Key characteristics:

Receive transferred calls from dialer campaigns or direct phone numbers
Queue calls until agent availability
Track transfer times and call dispositions separately
Support multiple in-groups within one closer campaign
Integrate with DNC (Do Not Call) lists and custom call rules

What Are In-Groups?

In-groups are the actual agent queues where calls wait for assignment. A closer campaign may have multiple in-groups (e.g., "Sales", "Support", "Escalations"), each with distinct:

Member agents with individual priorities
Call handling rules and routing logic
Recording preferences
Custom CID masking
Hold music and announcements

The relationship: Closer Campaign contains In-Groups containing Agents

Part 1: Create the Closer Campaign via Web UI

Step 1.1: Access Campaign Configuration

Log into /vicidial/admin.php with administrator account
Navigate: Admin → Campaigns → Add New Campaign
Select Campaign Type: "Closer"
Fill in campaign details:

Field	Example Value	Notes
Campaign ID	CLOSER_SALES	Uppercase, no spaces, 2-20 chars
Campaign Name	Sales Closer Campaign	Human-readable name
Active	YES	Enable immediately
Outbound CID	18005551234	Caller ID for transfers
Outbound CID Name	Sales Dept	Display name (optional)
Phone Number	18005551000	DID for external transfers
Call Time Zone	America/Chicago	Agent's timezone
Use Asterisk	YES	Required for call routing

Step 1.2: Configure Callback and Transfer Settings

In the same campaign creation form:

Callback Auto Hold Minutes:          5
Callback Auto Dial:                  YES
Campaigns to receive from:           DIALER_SALES,DIALER_LEADS
Transfer Timeout Seconds:            45
Voicemail Extension:                 9999
Call Recording:                      ALWAYS
Recording Call Display Name:         CLOSER_SALES
Lead ID Prefix:                      CS-

Critical setting: Leave "Closer Dial Campaign" BLANK (this is for callbacks originated from closer agents, not for receiving transfers)

Step 1.3: Save and Verify

Click SUBMIT. ViciDial will:

Create campaign record in vicidial_campaigns table
Create campaign contexts in /etc/asterisk/extensions-vicidial.conf
Generate default dialplan extensions

Verify creation:

mysql -u root -p asterisk -e "SELECT campaign_id, campaign_name, campaign_type, active FROM vicidial_campaigns WHERE campaign_id='CLOSER_SALES';"

Expected output:

| CLOSER_SALES | Sales Closer Campaign | CLOSER | Y |

Part 2: Create In-Groups Within the Closer Campaign

Step 2.1: In-Group Fundamentals

In-groups are the actual call queues. You must create at least one in-group per closer campaign. Most production environments have 2-4 in-groups:

Primary in-group: Handles all standard transfers
Overflow in-group: Secondary queue when primary is full
VIP in-group: Dedicated high-value customer queue
Escalation in-group: Complex issues requiring senior agents

Step 2.2: Create In-Group via Database

While ViciDial admin UI has in-group creation, direct database insertion is faster for bulk setup:

INSERT INTO vicidial_ingroups (
  ingroup_id,
  campaign_id,
  ingroup_name,
  description,
  active,
  callback_grp,
  phone_number,
  voicemail_ext,
  hold_music,
  recording_call_display_name,
  call_timeout,
  call_priority,
  full_set_queue_exten,
  customer_greeting,
  agent_greeting,
  in_group_digits
) VALUES (
  'CLOSER_SALES_MAIN',
  'CLOSER_SALES',
  'Sales Main Queue',
  'Primary in-group for sales closer campaign',
  'Y',
  'Y',
  '18005551000',
  '9999',
  'default',
  'CLOSER_SALES_MAIN',
  '120',
  '1',
  '1',
  'Thanks for calling. A representative will be with you shortly.',
  'Thank you for calling. Please give me one moment while I retrieve your information.',
  ''
);

Key fields explanation:

ingroup_id: Unique identifier across system (24 chars max)
callback_grp: Allow agents to callback? Set 'Y' for closer queues
call_timeout: Seconds before call abandons from queue (120-300 typical)
call_priority: Lower number = higher priority (1-5 range)
full_set_queue_exten: Extension when queue full (usually extension 1)
recording_call_display_name: Identifies recording in playback system

Step 2.3: Create Secondary In-Group (Overflow)

INSERT INTO vicidial_ingroups (
  ingroup_id,
  campaign_id,
  ingroup_name,
  description,
  active,
  callback_grp,
  phone_number,
  voicemail_ext,
  hold_music,
  call_timeout,
  call_priority,
  full_set_queue_exten
) VALUES (
  'CLOSER_SALES_OVERFLOW',
  'CLOSER_SALES',
  'Sales Overflow Queue',
  'Overflow for sales closer campaign',
  'Y',
  'Y',
  '18005551001',
  '9999',
  'default',
  '150',
  '2',
  '1'
);

Step 2.4: Verify In-Group Creation

mysql -u root -p asterisk -e "SELECT ingroup_id, campaign_id, ingroup_name, active, call_timeout FROM vicidial_ingroups WHERE campaign_id='CLOSER_SALES';"

Expected:

| CLOSER_SALES_MAIN      | CLOSER_SALES | Sales Main Queue    | Y | 120 |
| CLOSER_SALES_OVERFLOW  | CLOSER_SALES | Sales Overflow Queue| Y | 150 |

Part 3: Assign Agents to In-Groups

Step 3.1: Add Agent Memberships

Agents must be explicitly assigned to in-groups via the vicidial_ingroup_agents table. Each agent can belong to multiple in-groups with different priorities and statuses:

INSERT INTO vicidial_ingroup_agents (
  ingroup_id,
  user_id,
  agent_priority,
  lead_id,
  agent_status,
  closer_flag
) VALUES
  ('CLOSER_SALES_MAIN', 'agent001', 1, '0', 'ACTIVE', 'Y'),
  ('CLOSER_SALES_MAIN', 'agent002', 2, '0', 'ACTIVE', 'Y'),
  ('CLOSER_SALES_MAIN', 'agent003', 3, '0', 'ACTIVE', 'Y'),
  ('CLOSER_SALES_OVERFLOW', 'agent004', 1, '0', 'ACTIVE', 'Y'),
  ('CLOSER_SALES_OVERFLOW', 'agent002', 2, '0', 'ACTIVE', 'Y');

Field explanations:

agent_priority: 1=highest priority, 9=lowest. Lower number gets called first
closer_flag: 'Y' = this agent handles closer calls (must be 'Y')
agent_status: 'ACTIVE'='available', 'INACTIVE'='unavailable', 'DELETED'='removed'
lead_id: Usually '0' for in-group assignments; can specify a particular lead

Step 3.2: Configure Individual Agent Closer Permissions

Each agent needs ViciDial user account flags enabled. Update the vicidial_users table:

UPDATE vicidial_users 
SET 
  closer_enabled = '1',
  closer_campaigns = 'CLOSER_SALES',
  call_transfer_flag = '1',
  no_outbound_calls = '0',
  can_transfer_to_other_users = '1'
WHERE user_id IN ('agent001', 'agent002', 'agent003', 'agent004');

Critical fields:

closer_enabled: Set to '1' to allow agent to receive closer calls
closer_campaigns: Comma-separated list of campaigns agent can handle
call_transfer_flag: Enables blind/attended transfers
can_transfer_to_other_users: Allows warm transfer to other agents

Verify settings:

mysql -u root -p asterisk -e "SELECT user_id, closer_enabled, closer_campaigns FROM vicidial_users WHERE user_id IN ('agent001','agent002','agent003','agent004');"

Step 3.3: Set Agent Pause Codes for In-Group Work

Create pause codes specific to closer work:

INSERT INTO vicidial_pause_codes (
  pause_code,
  pause_name,
  inbound_seconds,
  outbound_seconds,
  active
) VALUES
  ('CLOSER', 'Closer Call In Progress', 0, 0, 'Y'),
  ('CLOSER_BREAK', 'Closer Break', 300, 300, 'Y'),
  ('CLOSER_LUNCH', 'Closer Lunch', 3600, 3600, 'Y');

These codes appear in agent's pause dropdown in /agc/vicidial.php interface.

Part 4: Configure Asterisk Dialplan Integration

Step 4.1: Verify Auto-Generated Extensions

ViciDial automatically creates extensions when you add a closer campaign. Verify in /etc/asterisk/extensions-vicidial.conf:

grep -A 30 "exten => 8900,1" /etc/asterisk/extensions-vicidial.conf | head -40

You should see auto-generated closer campaign context. If missing, manually trigger regeneration:

/usr/share/astguiclient/astguiclient_closer_extension_sync.pl

Step 4.2: Create Custom Transfer Extension (Optional)

To allow dialer agents to transfer calls to closer campaign, add to /etc/asterisk/extensions-vicidial.conf:

[ViciDial-Closer-Transfer]
exten => 1,1,NoOp(Closer Transfer Request to ${closer_queue})
 same => n,ViciDialCloserQueue(${closer_queue}|${closer_priority}|${CALLERID(num)})
 same => n,Hangup()

exten => i,1,NoOp(Invalid extension)
 same => n,Playback(invalid)
 same => n,Hangup()

exten => t,1,NoOp(Transfer timeout)
 same => n,Hangup()

Step 4.3: Reload Asterisk Configuration

asterisk -rx "dialplan reload"

Verify dialplan loaded:

asterisk -rx "dialplan show ViciDial-Closer-Transfer"

Expected output:

[ ViciDial-Closer-Transfer ]
'1' =>            1. NoOp(Closer Transfer Request to ${closer_queue})
                  2. ViciDialCloserQueue(${closer_queue}|${closer_priority}|${CALLERID(num)})
                  3. Hangup()

Part 5: Test the Closer Campaign

Step 5.1: Pre-Test Verification Checklist

Before testing, verify all components in database:

#!/bin/bash
# Test script for closer campaign setup

CAMPAIGN="CLOSER_SALES"
DB="asterisk"

echo "=== Campaign Configuration ==="
mysql -u root -p "$DB" -e "SELECT campaign_id, campaign_type, active FROM vicidial_campaigns WHERE campaign_id='$CAMPAIGN';"

echo -e "\n=== In-Groups ==="
mysql -u root -p "$DB" -e "SELECT ingroup_id, ingroup_name, active FROM vicidial_ingroups WHERE campaign_id='$CAMPAIGN';"

echo -e "\n=== Agent Assignments ==="
mysql -u root -p "$DB" -e "SELECT ingroup_id, user_id, agent_priority, closer_flag FROM vicidial_ingroup_agents WHERE ingroup_id LIKE '$CAMPAIGN%';"

echo -e "\n=== Agent Closer Status ==="
mysql -u root -p "$DB" -e "SELECT user_id, closer_enabled, closer_campaigns FROM vicidial_users WHERE closer_enabled='1' LIMIT 5;"

Run this script:

chmod +x test_closer_config.sh
./test_closer_config.sh

Step 5.2: Manual Agent Availability Test

# Check current agent statuses
mysql -u root -p asterisk -e "SELECT user_id, status, campaign_id, on_call FROM vicidial_users WHERE user_id IN ('agent001','agent002','agent003');"

Step 5.3: Simulate Incoming Call to In-Group

Use Asterisk CLI to originate test call:

asterisk -rx "channel originate SIP/2000 extension 8900@CLOSER_SALES_MAIN-inbound"

Monitor Asterisk logs in real-time:

tail -f /var/log/asterisk/messages | grep -i "closer\|ingroup\|queue"

Step 5.4: Monitor Call Routing

Check Asterisk queue status:

asterisk -rx "queue show CLOSER_SALES_MAIN"

Expected output:

CLOSER_SALES_MAIN has 0 calls (max unlimited) in 'rrordered' strategy
     agent001 (SIP/2000) (paused) (Not in call, paused 0m 45s)
     agent002 (SIP/2001) (ready) (Penalty: 2)
     agent003 (SIP/2002) (ready) (Penalty: 3)

Step 5.5: Verify Call Logging

After test call completes, verify logs:

mysql -u root -p asterisk -e "
SELECT 
  call_id,
  caller_id,
  customer_id,
  campaign_id,
  start_time,
  call_duration,
  status
FROM vicidial_closer_log 
WHERE campaign_id='CLOSER_SALES' 
ORDER BY start_time DESC 
LIMIT 5;
"

Part 6: Advanced Configuration

Step 6.1: Implement Call Distribution Strategy

Closer in-groups support multiple distribution strategies. Configure in vicidial_ingroups:

UPDATE vicidial_ingroups 
SET 
  call_distribution_method = 'rrordered',
  max_concurrent_calls = '5',
  force_return_to_hold = 'N'
WHERE ingroup_id = 'CLOSER_SALES_MAIN';

Distribution methods:

rrordered: Round-robin by agent priority (default, recommended)
leastrecent: Agent with oldest last call
fewestcalls: Agent with fewest total calls today
random: Random agent selection

Step 6.2: Configure Callback Rules

Allow agents in closer campaign to schedule callbacks:

UPDATE vicidial_campaigns 
SET 
  closer_dial_campaign = 'CLOSER_SALES_CB',
  callback_dial_method = 'MANUAL',
  callback_hours_start = '08:00:00',
  callback_hours_end = '20:00:00'
WHERE campaign_id = 'CLOSER_SALES';

This requires a separate dialer campaign (CLOSER_SALES_CB) created for callback origination.

Step 6.3: Implement DNC (Do Not Call) Filtering

Link in-group to DNC lists:

INSERT INTO vicidial_ingroup_dnc_filters (
  ingroup_id,
  dnc_filter_id,
  active
) VALUES
  ('CLOSER_SALES_MAIN', 'FEDERAL_DNC', 'Y'),
  ('CLOSER_SALES_MAIN', 'COMPANY_DNC', 'Y'),
  ('CLOSER_SALES_MAIN', 'INTERNAL_DNC', 'Y');

Step 6.4: Set Up Custom CID Masking

Force specific outbound CID for transfers from this in-group:

UPDATE vicidial_ingroups 
SET 
  outbound_cid = '18005551234',
  outbound_cid_name = 'Sales Department',
  cid_mask_method = 'FORCED'
WHERE ingroup_id = 'CLOSER_SALES_MAIN';

Step 6.5: Configure Call Recording Exceptions

Set custom recording preferences:

UPDATE vicidial_ingroups 
SET 
  recording_call_display_name = 'CLOSER_SALES_MAIN_REC',
  call_recording_compression = '32',
  call_recording_quality = 'gsm',
  recording_enabled = 'Y'
WHERE ingroup_id = 'CLOSER_SALES_MAIN';

Part 7: Performance Tuning

Step 7.1: Optimize Queue Timeout Settings

Based on team size and call volume, adjust timeouts:

UPDATE vicidial_ingroups 
SET 
  call_timeout = '120',           -- 2 min normal calls
  callback_timeout = '180'        -- 3 min callbacks
WHERE ingroup_id = 'CLOSER_SALES_MAIN';

Monitor actual wait times:

mysql -u root -p asterisk -e "
SELECT 
  DATE(start_time) as Date,
  COUNT(*) as Total_Calls,
  AVG(wait_time) as Avg_Wait_Sec,
  MAX(wait_time) as Max_Wait_Sec
FROM vicidial_closer_log
WHERE campaign_id='CLOSER_SALES'
  AND start_time > DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY DATE(start_time)
ORDER BY Date DESC;
"

Step 7.2: Monitor Agent Adherence to In-Group

Track agent time allocation across in-groups:

SELECT 
  user_id,
  ingroup_id,
  COUNT(*) as calls_handled,
  AVG(call_duration) as avg_duration,
  SUM(call_duration) as total_talk_time
FROM vicidial_closer_log
WHERE DATE(start_time) = CURDATE()
GROUP BY user_id, ingroup_id
ORDER BY total_talk_time DESC;

Step 7.3: Set Agent Concurrent Call Limits

Prevent single agent from receiving multiple simultaneous calls:

UPDATE vicidial_users 
SET 
  max_concurrent_calls = '1',
  force_logout_after_seconds = '0'
WHERE user_id IN ('agent001', 'agent002', 'agent003', 'agent004');

Part 8: Troubleshooting

Issue: Calls Not Routing to In-Group

Symptom: Incoming calls to DID don't reach agent queues, instead hangup or disconnect.

Root causes & solutions:

Campaign not active:

mysql -u root -p asterisk -e "SELECT campaign_id, active FROM vicidial_campaigns WHERE campaign_id='CLOSER_SALES';"

If active is 'N', update:

UPDATE vicidial_campaigns SET active='Y' WHERE campaign_id='CLOSER_SALES';

In-group not linked to campaign:

mysql -u root -p asterisk -e "SELECT ingroup_id, campaign_id FROM vicidial_ingroups WHERE campaign_id='CLOSER_SALES';"

Dialplan context missing:

asterisk -rx "dialplan show CLOSER_SALES | head -20"

If no output, regenerate:

/usr/share/astguiclient/astguiclient_extension_update.pl
asterisk -rx "dialplan reload"
sleep 2
asterisk -rx "module reload pbx_config"

SIP routing issue - verify SIP profile includes ViciDial context:

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

Issue: Agents Not Receiving Calls Despite Being Available

Symptom: Agents log in, show as READY, but calls don't route to them.

Diagnosis:

# Check agent in-group membership
mysql -u root -p asterisk -e "
SELECT u.user_id, u.status, ia.ingroup_id, ia.closer_flag 
FROM vicidial_users u 
LEFT JOIN vicidial_ingroup_agents ia ON u.user_id = ia.user_id 
WHERE u.user_id='agent001';
"

Solutions:

If ingroup_id is NULL, agent not assigned to in-group. Re-run Step 3.1.
Verify closer_enabled flag:

mysql -u root -p asterisk -e "SELECT user_id, closer_enabled FROM vicidial_users WHERE user_id='agent001';"

Check if agent paused:

asterisk -rx "show channels | grep agent001"

If showing paused status, use admin panel to unpause or force status:

UPDATE vicidial_users SET status='READY' WHERE user_id='agent001';

Check Asterisk queue membership:

asterisk -rx "queue show CLOSER_SALES_MAIN | grep agent001"

Issue: High Call Abandonment Rate

Symptom: Calls dropping before reaching agents (>15% abandonment).

Analysis:

mysql -u root -p asterisk -e "
SELECT 
  ingroup_id,
  COUNT(*) as total,
  SUM(CASE WHEN call_status='ABANDON' THEN 1 ELSE 0 END) as abandoned,
  ROUND(100*SUM(CASE WHEN call_status='ABANDON' THEN 1 ELSE 0 END)/COUNT(*), 2) as abandon_pct,
  AVG(wait_time) as avg_wait_sec
FROM vicidial_closer_log
WHERE DATE(start_time) = CURDATE()
  AND campaign_id='CLOSER_SALES'
GROUP BY ingroup_id;
"

Solutions:

Increase agents assigned: Add more agents to in-group or create overflow in-group.
Reduce timeout: Lower call_timeout value (but not below 60 seconds):

UPDATE vicidial_ingroups SET call_timeout='90' WHERE ingroup_id='CLOSER_SALES_MAIN';

Add voicemail option: Ensure voicemail_ext is configured:

UPDATE vicidial_ingroups SET voicemail_ext='9999' WHERE ingroup_id='CLOSER_SALES_MAIN';

Implement callbacks: Enable callback option when queue full.

Issue: Calls Queuing But Not Distributed

Symptom: Queue shows calls waiting but agents not getting delivered calls.

Debug:

# Monitor queue in real-time
watch -n 1 'asterisk -rx "queue show CLOSER_SALES_MAIN"'

Check agent member penalties:

mysql -u root -p asterisk -e "SELECT ingroup_id, user_id, agent_priority FROM vicidial_ingroup_agents WHERE ingroup_id='CLOSER_SALES_MAIN';"

Solution: Agent priority (penalty in queue) must be ascending (1, 2, 3, etc.). If reversed, queue won't distribute:

UPDATE vicidial_ingroup_agents 
SET agent_priority = 1 
WHERE ingroup_id='CLOSER_SALES_MAIN' AND user_id='agent001';

UPDATE vicidial_ingroup_agents 
SET agent_priority = 2 
WHERE ingroup_id='CLOSER_SALES_MAIN' AND user_id='agent002';

Reload queue:

asterisk -rx "queue reload"

Issue: Calls Recording Not Working

Symptom: Closer calls complete but no recordings saved.

Check recording path:

ls -lah /var/spool/asterisk/monitor/ | tail -20

Verify recording_enabled flag:

mysql -u root -p asterisk -e "SELECT ingroup_id, recording_enabled, recording_call_display_name FROM vicidial_ingroups WHERE ingroup_id='CLOSER_SALES_MAIN';"

Enable recordings:

UPDATE vicidial_ingroups 
SET recording_enabled='Y' 
WHERE ingroup_id='CLOSER_SALES_MAIN';

Check Asterisk logging:

grep -i "monitor\|record" /var/log/asterisk/messages | tail -30

Disk space issue - common cause:

df -h /var/spool/asterisk/

If full, archive old recordings:

find /var/spool/asterisk/monitor/ -mtime +30 -exec gzip {} \;

Issue: Agent Can't Transfer Calls

Symptom: Closer agent attempts blind/attended transfer but fails.

Verify transfer permissions:

mysql -u root -p asterisk -e "SELECT user_id, call_transfer_flag, can_transfer_to_other_users FROM vicidial_users WHERE user_id='agent001';"

Enable transfers:

UPDATE vicidial_users 
SET 
  call_transfer_flag='1',
  can_transfer_to_other_users='1'
WHERE user_id='agent001';

Check Asterisk DTMF configuration - verify feature codes in /etc/asterisk/features.conf:

[featuremap]
blindxfer => #1          ; Blind transfer
atxfer => *2             ; Attended transfer

Test with CLI:

asterisk -rx "core show hints | grep agent001"

Part 9: Monitoring & Reporting

Dashboard Query: Real-Time In-Group Status

SELECT 
  ig.ingroup_id,
  ig.ingroup_name,
  COUNT(DISTINCT CASE WHEN u.status='READY' THEN u.user_id END) as available_agents,
  COUNT(DISTINCT CASE WHEN u.status='IN_CALL' THEN u.user_id END) as busy_agents,
  COUNT(DISTINCT CASE WHEN u.status='PAUSED' THEN u.user_id END) as paused_agents,
  (SELECT COUNT(*) FROM vicidial_log vl 
   WHERE vl.ingroup_id = ig.ingroup_id 
   AND vl.call_status = 'WAITING') as calls_waiting
FROM vicidial_ingroups ig
LEFT JOIN vicidial_ingroup_agents iag ON ig.ingroup_id = iag.ingroup_id
LEFT JOIN vicidial_users u ON iag.user_id = u.user_id
WHERE ig.campaign_id='CLOSER_SALES'
GROUP BY ig.ingroup_id, ig.ingroup_name;

Daily Performance Report

SELECT 
  DATE(start_time) as call_date,
  ingroup_id,
  COUNT(*) as total_calls,
  SUM(CASE WHEN call_status='COMPLETED' THEN 1 ELSE 0 END) as completed_calls,
  SUM(CASE WHEN call_status='ABANDON' THEN 1 ELSE 0 END) as abandoned_calls,
  ROUND(AVG(wait_time), 1) as avg_wait_seconds,
  ROUND(AVG(call_duration), 1) as avg_talk_seconds,
  ROUND(SUM(call_duration)/COUNT(*), 1) as avg_handle_time_seconds
FROM vicidial_closer_log
WHERE campaign_id='CLOSER_SALES'
  AND start_time BETWEEN DATE_SUB(CURDATE(), INTERVAL 7 DAY) AND NOW()
GROUP BY DATE(start_time), ingroup_id
ORDER BY call_date DESC, ingroup_id;

Agent Productivity Report

SELECT 
  u.user_id,
  u.full_name,
  COUNT(DISTINCT cl.call_id) as calls_handled,
  SUM(cl.call_duration) as total_talk_time,
  ROUND(AVG(cl.call_duration), 1) as avg_talk_time,
  SUM(cl.wait_time) as total_wait_time,
  COUNT(DISTINCT CASE WHEN cl.call_status='COMPLETED' THEN cl.call_id END) as completed_calls
FROM vicidial_users u
LEFT JOIN vicidial_closer_log cl ON u.user_id = cl.assigned_to 
  AND DATE(cl.start_time) = CURDATE()
WHERE u.closer_enabled='1'
GROUP BY u.user_id, u.full_name
ORDER BY calls_handled DESC;

Summary

Configuring ViciDial closer campaigns and in-groups involves seven critical steps:

Create the closer campaign in web UI with appropriate dialing and recording settings
Define in-groups as call queues within the campaign, setting timeouts and priorities
Assign agents to in-groups with individual priorities and closer permissions
Enable Asterisk integration by verifying dialplan contexts and reloading configuration
Test thoroughly using Asterisk CLI and database verification queries
Optimize performance through distribution strategy tuning and timeout adjustments
Monitor continuously with real-time queries and daily reports

Key production-grade practices:

Always verify database changes with SELECT queries before and after modifications
Use agent priorities (1-3 range) for fair call distribution
Enable call recording on all in-groups for compliance and quality assurance
Set reasonable timeouts (120-180 seconds) to prevent excessive call abandonment
Create overflow in-groups to handle peak traffic periods
Test complete call flow end-to-

How to Use ViciDial Real-Time Report for Campaign Monitoring

Moisi Trungu — Fri, 09 Oct 2026 03:30:04 +0000

How to Use ViciDial Real-Time Report for Campaign Monitoring

Master real-time call monitoring, agent performance tracking, and live campaign metrics in ViciDial to optimize your contact center operations and identify bottlenecks instantly.

Prerequisites

Before implementing real-time report monitoring in ViciDial, ensure you have:

A fully functional ViciDial installation (version 2.10 or later recommended)
SSH/terminal access to your ViciDial server
MySQL/MariaDB administrative access
Understanding of basic ViciDial campaign structure (campaigns, user accounts, inbound/outbound queues)
Web browser access to the ViciDial admin interface (http://your-server/vicidial/admin.php)
Asterisk running with proper CDR logging enabled
Write permissions to /var/log/asterisk/ directory
At least one active campaign configured with agents

Understanding ViciDial Real-Time Reporting Architecture

How Real-Time Reports Work

ViciDial real-time reports pull data directly from the Asterisk database (asterisk schema) rather than relying on pre-calculated reports. The system queries active tables like vicidial_log, vicidial_closer_log, vicidial_list, and vicidial_users to display live metrics.

The key difference between real-time reports and historical reports:

Real-time reports: Query current call activity, agent status, and campaign state every few seconds
Historical reports: Aggregate completed data from vicidial_log after calls disconnect

Real-time reports use three primary data sources:

vicidial_log - Individual call records with timestamps, results, and agent assignments
vicidial_closer_log - Detailed call outcomes (sale, no-sale, callback, etc.)
vicidial_users - Agent status and live availability

Database Table Structure

Understanding the relevant tables ensures you query the right data:

-- Check core tables for real-time data
USE asterisk;
DESCRIBE vicidial_log;
DESCRIBE vicidial_closer_log;
DESCRIBE vicidial_users;
DESCRIBE vicidial_campaigns;

Key columns in vicidial_log:

call_id - Unique call identifier
campaign_id - Campaign this call belongs to
user - Agent username
call_date - Call timestamp
call_type - INBOUND, OUTBOUND, etc.
call_result - Final disposition
call_length - Duration in seconds
status - Current state (LIVE, COMPLETED, etc.)

Accessing the Real-Time Report Interface

Web-Based Real-Time Reports

The primary method to view real-time reports is through the ViciDial admin interface:

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

Steps to access real-time reports:

Log in with your administrative account
Navigate to Reports → Real-Time Reports (or Live Calls depending on version)
Select your campaign from the dropdown
The dashboard automatically refreshes every 5-10 seconds

Command-Line Real-Time Queries

For server-side monitoring or custom integrations, query the database directly:

# SSH into your ViciDial server
ssh root@your-vicidial-server

# Connect to MySQL
mysql -u root -p

# Select the asterisk database
USE asterisk;

Practical Real-Time Monitoring Queries

Query 1: Active Calls by Campaign (Last 5 Minutes)

SELECT 
    c.campaign_name,
    COUNT(*) as active_calls,
    AVG(TIMESTAMPDIFF(SECOND, vl.call_date, NOW())) as avg_call_duration_sec,
    SUM(CASE WHEN vl.call_result = 'SALE' THEN 1 ELSE 0 END) as sales,
    ROUND(100.0 * SUM(CASE WHEN vl.call_result = 'SALE' THEN 1 ELSE 0 END) / COUNT(*), 2) as conversion_rate
FROM 
    vicidial_log vl
    INNER JOIN vicidial_campaigns c ON vl.campaign_id = c.campaign_id
WHERE 
    vl.call_date >= DATE_SUB(NOW(), INTERVAL 5 MINUTE)
    AND vl.status IN ('LIVE', 'COMPLETED')
GROUP BY 
    c.campaign_name
ORDER BY 
    active_calls DESC;

Output example:

+-----------------------+--------------+------------------------+-------+-----------------+
| campaign_name         | active_calls | avg_call_duration_sec  | sales | conversion_rate |
+-----------------------+--------------+------------------------+-------+-----------------+
| Sales Campaign Q4     |           23 |                    87  |     5 |            21.74|
| Lead Qualification    |           18 |                   124  |     2 |            11.11|
| Customer Retention    |            7 |                    45  |     1 |            14.29|
+-----------------------+--------------+------------------------+-------+-----------------+

Query 2: Agent Performance Real-Time Snapshot

SELECT 
    u.user,
    u.user_level,
    u.status,
    COUNT(vl.call_id) as calls_today,
    ROUND(AVG(vl.call_length), 1) as avg_call_length_sec,
    SUM(CASE WHEN vl.call_result = 'SALE' THEN 1 ELSE 0 END) as sales,
    ROUND(100.0 * SUM(CASE WHEN vl.call_result = 'SALE' THEN 1 ELSE 0 END) / COUNT(vl.call_id), 2) as sales_rate,
    MAX(vl.call_date) as last_call_time
FROM 
    vicidial_users u
    LEFT JOIN vicidial_log vl ON u.user = vl.user 
        AND vl.call_date >= DATE_SUB(NOW(), INTERVAL 1 DAY)
WHERE 
    u.user_level > 0
    AND u.active = 'Y'
GROUP BY 
    u.user, u.user_level, u.status
ORDER BY 
    sales DESC, calls_today DESC;

Query 3: Queue Depth and Wait Times

SELECT 
    vc.campaign_id,
    vc.campaign_name,
    vc.dial_method,
    COUNT(DISTINCT vl.call_id) as current_queue_depth,
    ROUND(AVG(TIMESTAMPDIFF(SECOND, vl.call_date, NOW())), 0) as avg_queue_wait_sec,
    COUNT(DISTINCT vl.user) as available_agents
FROM 
    vicidial_log vl
    INNER JOIN vicidial_campaigns vc ON vl.campaign_id = vc.campaign_id
WHERE 
    vl.status = 'LIVE'
    AND vl.call_date >= DATE_SUB(NOW(), INTERVAL 10 MINUTE)
GROUP BY 
    vc.campaign_id, vc.campaign_name, vc.dial_method;

Query 4: Real-Time Call Result Distribution

SELECT 
    vc.campaign_id,
    vc.campaign_name,
    vl.call_result,
    COUNT(*) as result_count,
    ROUND(100.0 * COUNT(*) / (SELECT COUNT(*) FROM vicidial_log WHERE campaign_id = vc.campaign_id AND call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)), 2) as percentage
FROM 
    vicidial_log vl
    INNER JOIN vicidial_campaigns vc ON vl.campaign_id = vc.campaign_id
WHERE 
    vl.call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
GROUP BY 
    vc.campaign_id, vc.campaign_name, vl.call_result
ORDER BY 
    result_count DESC;

Building Custom Real-Time Monitoring Dashboards

Creating a Shell Script for Continuous Monitoring

Create a bash script that polls real-time data and displays it in the terminal:

#!/bin/bash
# File: /usr/local/bin/vicidial-monitor.sh
# Real-time ViciDial monitoring script

MYSQL_USER="root"
MYSQL_PASS="your_mysql_password"
DB_NAME="asterisk"
REFRESH_INTERVAL=10

function get_active_calls() {
    mysql -u $MYSQL_USER -p$MYSQL_PASS $DB_NAME -e "
    SELECT 
        c.campaign_name,
        COUNT(*) as active_calls,
        SUM(CASE WHEN vl.call_result = 'SALE' THEN 1 ELSE 0 END) as sales
    FROM 
        vicidial_log vl
        INNER JOIN vicidial_campaigns c ON vl.campaign_id = c.campaign_id
    WHERE 
        vl.call_date >= DATE_SUB(NOW(), INTERVAL 5 MINUTE)
        AND vl.status IN ('LIVE', 'COMPLETED')
    GROUP BY 
        c.campaign_name
    ORDER BY 
        active_calls DESC;
    "
}

function get_agent_status() {
    mysql -u $MYSQL_USER -p$MYSQL_PASS $DB_NAME -e "
    SELECT 
        user,
        status,
        COUNT(*) as count
    FROM 
        vicidial_users
    WHERE 
        user_level > 0
    GROUP BY 
        user, status;
    "
}

# Main loop
while true; do
    clear
    echo "====== VICIDIAL REAL-TIME MONITOR ======"
    echo "Refresh Time: $(date '+%Y-%m-%d %H:%M:%S')"
    echo ""
    echo "--- ACTIVE CALLS BY CAMPAIGN ---"
    get_active_calls
    echo ""
    echo "--- AGENT STATUS SUMMARY ---"
    get_agent_status
    echo ""
    echo "Next refresh in $REFRESH_INTERVAL seconds..."
    sleep $REFRESH_INTERVAL
done

Make it executable:

chmod +x /usr/local/bin/vicidial-monitor.sh

# Run it
/usr/local/bin/vicidial-monitor.sh

PHP-Based Real-Time Dashboard

Create a lightweight PHP dashboard for web access:

<?php
// File: /var/www/html/vicidial/real-time-dashboard.php
// Simple real-time dashboard

header('Content-Type: text/html; charset=utf-8');

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

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

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

// Query active calls
$query = "
SELECT 
    c.campaign_name,
    COUNT(*) as active_calls,
    SUM(CASE WHEN vl.call_result = 'SALE' THEN 1 ELSE 0 END) as sales,
    AVG(vl.call_length) as avg_duration
FROM 
    vicidial_log vl
    INNER JOIN vicidial_campaigns c ON vl.campaign_id = c.campaign_id
WHERE 
    vl.call_date >= DATE_SUB(NOW(), INTERVAL 5 MINUTE)
    AND vl.status IN ('LIVE', 'COMPLETED')
GROUP BY 
    c.campaign_name
ORDER BY 
    active_calls DESC
";

$result = $conn->query($query);

?>
<!DOCTYPE html>
<html>
<head>
    <title>ViciDial Real-Time Monitor</title>
    <meta http-equiv="refresh" content="10">
    <style>
        body { font-family: Arial, sans-serif; margin: 20px; background: #f5f5f5; }
        table { border-collapse: collapse; width: 100%; background: white; box-shadow: 0 2px 4px rgba(0,0,0,0.1); }
        th, td { padding: 12px; text-align: left; border-bottom: 1px solid #ddd; }
        th { background-color: #4CAF50; color: white; }
        tr:hover { background-color: #f5f5f5; }
        .metric { font-weight: bold; color: #2196F3; }
        .sales { color: #4CAF50; }
        .timestamp { color: #999; font-size: 0.9em; }
    </style>
</head>
<body>
    <h1>ViciDial Real-Time Report - Campaign Monitor</h1>
    <p class="timestamp">Last Updated: <?php echo date('Y-m-d H:i:s'); ?></p>

    <table>
        <tr>
            <th>Campaign Name</th>
            <th class="metric">Active Calls</th>
            <th class="sales">Sales</th>
            <th>Avg Duration (sec)</th>
        </tr>
        <?php
        if ($result->num_rows > 0) {
            while ($row = $result->fetch_assoc()) {
                echo "<tr>";
                echo "<td>" . htmlspecialchars($row['campaign_name']) . "</td>";
                echo "<td class='metric'>" . $row['active_calls'] . "</td>";
                echo "<td class='sales'>" . $row['sales'] . "</td>";
                echo "<td>" . round($row['avg_duration'], 1) . "</td>";
                echo "</tr>";
            }
        } else {
            echo "<tr><td colspan='4'>No active calls</td></tr>";
        }
        ?>
    </table>
</body>
</html>
<?php
$conn->close();
?>

Access it at: http://your-server/vicidial/real-time-dashboard.php

Monitoring Specific Metrics for Campaign Health

Call Abandonment Rate

SELECT 
    vc.campaign_name,
    COUNT(*) as total_calls,
    SUM(CASE WHEN vl.call_result = 'ABANDON' THEN 1 ELSE 0 END) as abandoned,
    ROUND(100.0 * SUM(CASE WHEN vl.call_result = 'ABANDON' THEN 1 ELSE 0 END) / COUNT(*), 2) as abandon_rate
FROM 
    vicidial_log vl
    INNER JOIN vicidial_campaigns vc ON vl.campaign_id = vc.campaign_id
WHERE 
    vl.call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
    AND vl.call_type = 'INBOUND'
GROUP BY 
    vc.campaign_name
HAVING 
    abandon_rate > 10.0
ORDER BY 
    abandon_rate DESC;

Average Handle Time (AHT) by Agent

SELECT 
    u.user,
    COUNT(*) as calls,
    ROUND(AVG(vl.call_length), 0) as aht_seconds,
    ROUND(AVG(vl.call_length) / 60, 2) as aht_minutes,
    ROUND(SUM(vl.call_length) / 3600, 1) as total_talk_hours
FROM 
    vicidial_log vl
    INNER JOIN vicidial_users u ON vl.user = u.user
WHERE 
    vl.call_date >= DATE_SUB(NOW(), INTERVAL 8 HOUR)
    AND vl.call_type = 'OUTBOUND'
GROUP BY 
    u.user
ORDER BY 
    aht_seconds DESC;

Dial-Through Rate (Predictive/Progressive Dialing)

SELECT 
    vc.campaign_name,
    vc.dial_method,
    COUNT(*) as total_dials,
    SUM(CASE WHEN vl.call_result NOT IN ('NO ANSWER', 'BUSY') THEN 1 ELSE 0 END) as connections,
    ROUND(100.0 * SUM(CASE WHEN vl.call_result NOT IN ('NO ANSWER', 'BUSY') THEN 1 ELSE 0 END) / COUNT(*), 2) as connect_rate
FROM 
    vicidial_log vl
    INNER JOIN vicidial_campaigns vc ON vl.campaign_id = vc.campaign_id
WHERE 
    vl.call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
    AND vl.call_type = 'OUTBOUND'
GROUP BY 
    vc.campaign_name, vc.dial_method;

Configuring Alerts for Campaign Issues

Setting Up Threshold-Based Alerts

Create a monitoring script that sends alerts when metrics exceed thresholds:

#!/bin/bash
# File: /usr/local/bin/vicidial-alert-monitor.sh
# Alert when metrics exceed thresholds

MYSQL_USER="root"
MYSQL_PASS="password"
DB_NAME="asterisk"
EMAIL_TO="admin@company.com"

# Check abandon rate
ABANDON_RATE=$(mysql -u $MYSQL_USER -p$MYSQL_PASS $DB_NAME -N -e "
SELECT MAX(abandon_pct) FROM (
    SELECT 
        ROUND(100.0 * SUM(CASE WHEN call_result = 'ABANDON' THEN 1 ELSE 0 END) / COUNT(*), 2) as abandon_pct
    FROM 
        vicidial_log
    WHERE 
        call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
        AND call_type = 'INBOUND'
    GROUP BY campaign_id
) subquery;
")

ABANDON_THRESHOLD=15

if (( $(echo "$ABANDON_RATE > $ABANDON_THRESHOLD" | bc -l) )); then
    echo "ALERT: Abandon rate is ${ABANDON_RATE}% (threshold: ${ABANDON_THRESHOLD}%)" | \
    mail -s "ViciDial Alert: High Abandon Rate" $EMAIL_TO
fi

# Check active agent availability
AVAILABLE_AGENTS=$(mysql -u $MYSQL_USER -p$MYSQL_PASS $DB_NAME -N -e "
SELECT COUNT(*) FROM vicidial_users 
WHERE user_level > 0 
AND status IN ('READY', 'PAUSED')
AND active = 'Y'
")

QUEUE_DEPTH=$(mysql -u $MYSQL_USER -p$MYSQL_PASS $DB_NAME -N -e "
SELECT COUNT(*) FROM vicidial_log 
WHERE status = 'LIVE' 
AND call_date >= DATE_SUB(NOW(), INTERVAL 5 MINUTE)
")

if [ "$AVAILABLE_AGENTS" -lt 5 ] && [ "$QUEUE_DEPTH" -gt 20 ]; then
    echo "ALERT: Low agent availability ($AVAILABLE_AGENTS agents) with queue depth at $QUEUE_DEPTH calls" | \
    mail -s "ViciDial Alert: Understaffing Risk" $EMAIL_TO
fi

Add to crontab to run every minute:

crontab -e

# Add this line:
* * * * * /usr/local/bin/vicidial-alert-monitor.sh

Performance Optimization for Real-Time Reports

Database Indexing for Faster Queries

Large ViciDial installations can experience slow real-time reports without proper indexing:

-- Add indexes if they don't exist
ALTER TABLE vicidial_log ADD INDEX idx_call_date (call_date);
ALTER TABLE vicidial_log ADD INDEX idx_campaign_status (campaign_id, status);
ALTER TABLE vicidial_log ADD INDEX idx_user_date (user, call_date);
ALTER TABLE vicidial_closer_log ADD INDEX idx_call_date (call_date);

-- Verify indexes exist
SHOW INDEX FROM vicidial_log;

Limiting Query Scope

Never query unbounded date ranges in production:

-- GOOD: Limited to last hour
WHERE vl.call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)

-- BAD: No date filter - scans entire table
WHERE vl.user = 'john.smith'

Using READ REPLICAS for Reporting

For high-volume operations, query a read replica instead of the production database:

# Example: Redirect reporting queries to replica
REPLICA_HOST="vicidial-replica.internal"
REPLICA_USER="report_user"
REPLICA_PASS="replica_password"

mysql -h $REPLICA_HOST -u $REPLICA_USER -p$REPLICA_PASS asterisk -e "SELECT ..."

Integrating with Asterisk CLI for Live Monitoring

Real-Time Agent Status from Asterisk

# Check SIP channels
asterisk -rx "sip show channels"

# Check Asterisk queue status
asterisk -rx "queue show"

# Get specific queue info
asterisk -rx "queue show vicidial_queue"

Sample output:

vicidial_queue has 3 calls (max unlimited) in 'ringall' strategy (0s holdtime, 45s talktime), W:0, C:125, A:3, SL:98.4% within 45s
    SIP/2002 (Agent John) with 1 calls (dynamic) answered in 124s
    SIP/2003 (Agent Sarah) with 1 calls (dynamic) answered in 156s
    Local/3051@from-internal-00000001 (IVR Menu) with 1 calls (dynamic) answered in 89s

Pull CDR Data from Asterisk

# Check Asterisk call records
asterisk -rx "cdr show active"

# Get CDR SQL status
asterisk -rx "cdr show status"

Troubleshooting Common Real-Time Reporting Issues

Issue 1: Real-Time Reports Show Zero Calls

Symptom: Dashboard displays "No active calls" when calls are clearly being processed.

Solution Steps:

Verify vicidial_log table is being populated:

SELECT COUNT(*) as recent_records FROM vicidial_log 
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 1 MINUTE);

Check if campaigns are properly configured:

SELECT campaign_id, campaign_name, active FROM vicidial_campaigns 
WHERE campaign_id IN (
    SELECT DISTINCT campaign_id FROM vicidial_log 
    WHERE call_date >= DATE_SUB(NOW(), INTERVAL 5 MINUTE)
);

Verify Asterisk is logging to MySQL:

# Check Asterisk CDR module
asterisk -rx "cdr show status"

# Expected output: CDR logging enabled, MySQL module loaded

Restart CDR logging if needed:

asterisk -rx "cdr reload"

Issue 2: Real-Time Reports Run Slowly

Symptom: Dashboard takes 30+ seconds to load; queries timeout.

Solution Steps:

Analyze slow query log:

-- Enable slow query log
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;

-- View slow queries
tail -f /var/log/mysql/slow.log

Check query execution plan:

EXPLAIN SELECT ... [your query here];

-- Look for "Full table scan" entries - these need indexes

Clear old data to reduce table size:

-- Archive calls older than 90 days
CREATE TABLE vicidial_log_archive_2024 LIKE vicidial_log;

INSERT INTO vicidial_log_archive_2024 
SELECT * FROM vicidial_log 
WHERE call_date < DATE_SUB(NOW(), INTERVAL 90 DAY);

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

-- Optimize table
OPTIMIZE TABLE vicidial_log;

Issue 3: Refresh Lag or Stale Data

Symptom: Real-time dashboard shows outdated information; metrics don't refresh.

Solution Steps:

Check database replication status (if using replication):

SHOW SLAVE STATUS\G

-- Look for Seconds_Behind_Master value
-- Should be 0 or very small

Verify web server isn't caching the report:

// Add to real-time dashboard header
header("Cache-Control: no-store, no-cache, must-revalidate, max-age=0");
header("Pragma: no-cache");
header("Expires: 0");

Increase refresh frequency in dashboard:

<!-- Change refresh interval from 10s to 5s -->
<meta http-equiv="refresh" content="5">

Issue 4: Database Locks During Real-Time Queries

Symptom: Queries hang; "Lock wait timeout exceeded" errors in MySQL log.

Solution Steps:

Identify locked tables:

SHOW OPEN TABLES WHERE In_use > 0;

-- Check for long-running transactions
SHOW PROCESSLIST;

Kill blocking query if necessary:

KILL [PROCESS_ID];

Configure MySQL to use InnoDB (better for concurrent access):

# Edit /etc/mysql/my.cnf
[mysqld]
default-storage-engine=InnoDB
innodb_buffer_pool_size=4G
innodb_log_file_size=512M

Issue 5: PHP Dashboard Blank or Shows Database Errors

Symptom: Real-time dashboard page is blank or displays "Database connection failed."

Solution Steps:

Check PHP error logs:

tail -f /var/log/apache2/error.log
tail -f /var/log/php-fpm.log

Verify MySQL credentials in dashboard script:

$conn = new mysqli('localhost', 'root', 'password', 'asterisk');
if ($conn->connect_error) {
    die("Error: " . $conn->connect_error);
}

Test MySQL connectivity from command line:

mysql -u root -p -h localhost asterisk -e "SELECT COUNT(*) FROM vicidial_log LIMIT 1;"

Check database user permissions:

-- Verify user has SELECT permission
SHOW GRANTS FOR 'root'@'localhost';

-- Grant if needed
GRANT SELECT ON asterisk.* TO 'root'@'localhost';
FLUSH PRIVILEGES;

Summary

ViciDial real-time reporting provides critical insight into campaign performance, agent activity, and system health. Key takeaways:

Core Concepts:

Real-time reports query live data from vicidial_log, vicidial_users, and vicidial_campaigns tables
Data refreshes every 5-10 seconds in web interface; can be queried instantly via CLI
Direct MySQL queries offer flexibility beyond built-in reports

Practical Implementation:

Use web-based dashboards at /vicidial/admin.php for quick overview
Build custom bash scripts for server-side monitoring
Create PHP dashboards for team visibility
Implement threshold-based alerts for critical metrics

Key Metrics to Monitor:

Active calls by campaign
Agent performance (AHT, sales rate, availability)
Queue depth and abandon rates
Dial-through rates and connection quality

Performance Best Practices:

Add database indexes on call_date, campaign_id, status, and user
Limit queries to recent time windows (last 1-24 hours)
Archive old data to keep tables responsive
Use read replicas for reporting in high-volume environments

Troubleshooting Foundation:

Verify MySQL logging is active and connected to Asterisk
Check slow query logs and optimize with indexes
Clear caches in PHP headers to ensure fresh data
Monitor database locks and process list during issues

With proper real-time monitoring in place, you'll detect abandoned calls, staffing shortages, and performance bottlenecks within minutes rather than hours—enabling proactive response that directly impacts customer satisfaction and campaign ROI.

How to Configure ViciDial Script Tab — Agent Call Scripts

Moisi Trungu — Thu, 08 Oct 2026 03:30:04 +0000

How to Configure ViciDial Script Tab — Agent Call Scripts

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

Prerequisites

Before configuring ViciDial agent call scripts, ensure you have:

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

Understanding ViciDial Script Architecture

What Are Call Scripts?

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

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

Script Processing Flow

When an agent receives a call, ViciDial:

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

Database Structure for Scripts

Core Script Tables

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

-- View existing script table structure
DESCRIBE vicidial_scripts;

Key columns in vicidial_scripts:

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

Script-Campaign Linking Table

The vicidial_campaigns table contains:

-- Relevant columns for script assignment
SELECT campaign_id, campaign_name, script_id, script_screen 
FROM vicidial_campaigns 
WHERE campaign_id = 'TESTCAMP';

script_id — Links to vicidial_scripts.script_id
script_screen — Controls when script displays ('CALL_TIME', 'DIALER_PREVIEW', 'BOTH', 'NONE')

Creating Your First Agent Call Script

Step 1: Connect to the ViciDial Database

mysql -u cron -p asterisk

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

grep 'ASTERISK_PASSWD' /etc/astguiclient.conf

Step 2: Insert a Basic Script

Create a simple inbound support script:

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

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

[NOTES]

Type your notes above this line.',
  'en',
  'Y',
  'AGENTS'
);

Verify insertion:

SELECT script_id, script_name FROM vicidial_scripts 
WHERE script_name = 'Inbound Support - Basic';

Step 3: Create an Advanced Script with HTML Formatting

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

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

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

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

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

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

ViciDial Script Variables Reference

Available Token Variables

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

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

Conditional Variables (Advanced)

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

Linking Scripts to Campaigns

Via MySQL

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

-- Verify assignment
SELECT campaign_id, campaign_name, script_id 
FROM vicidial_campaigns 
WHERE campaign_id = 'TESTCAMP';

Via Web Admin Interface

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

Agent-Level Script Overrides

Override Script Per User

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

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

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

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

Script Management Operations

Backup Scripts

Export all scripts before modifications:

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

Restore if needed:

mysql -u cron -p asterisk < /backup/vicidial_scripts_20240115.sql

List All Active Scripts

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

Bulk Update Scripts

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

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

Clone/Duplicate a Script

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

Script Display Settings in Asterisk Configuration

Extension Configuration

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

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

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

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

Testing Scripts in Production

View Script as Agent Would See It

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

Check Script Logs

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

Test Variable Substitution

Create a test lead record:

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

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

Performance Considerations

Script Size Optimization

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

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

If scripts exceed 50 KB:

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

Database Query Efficiency

ViciDial caches script data. To force refresh:

# Restart ViciDial daemon to clear cache
systemctl restart vicidial

Or clear specific cache entries:

# If Redis is enabled
redis-cli FLUSHDB  # WARNING: Clears all cache

Integration with Disposition Codes

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

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

Create script sections matching dispositions:

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

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

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

Multi-Language Script Support

Create Scripts in Multiple Languages

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

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

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

The campaign or user language setting determines which version displays.

Advanced: Custom Script Variables via AGI

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

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

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

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

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

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

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

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

# Send back to Asterisk
print "SET VARIABLE CUSTOMVAR $result\n";

Troubleshooting

Script Not Displaying During Calls

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

Diagnosis Steps:

Verify script_id is correctly assigned:

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

Confirm script exists and is active:

SELECT script_id, script_name, active FROM vicidial_scripts 
WHERE script_id = (SELECT script_id FROM vicidial_campaigns 
                   WHERE campaign_id = 'TESTCAMP');

Check Asterisk logs for AGI errors:

grep -i "agi\|script" /var/log/asterisk/messages | tail -20

Solution:

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

Variables Not Substituting

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

Diagnosis:

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

Solution:

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

Script Rendering Issues (HTML Scripts)

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

Diagnosis:

Test script in a text editor for syntax errors:

# Escape single quotes in SQL when testing locally
mysql -u cron -p asterisk -e "SELECT script_text FROM vicidial_scripts WHERE script_id = 5\G"

Check browser console for JavaScript errors: Press F12 in agent screen

Solution:

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

Performance Degradation with Large Scripts

Symptom: Agent screen becomes slow when script loads.

Diagnosis:

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

Solution:

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

Scripts Reverting After Restart

Symptom: Script changes work temporarily but disappear after reboot.

Diagnosis:

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

# Check if backup/restore is running
ps aux | grep -i backup

Solution:

Ensure MySQL is configured to persist data (not running in-memory)
Verify /var/lib/mysql is on persistent storage
Disable auto-restore scripts if they exist in cron jobs
Manually flush/commit database after changes:

mysql -u cron -p asterisk -e "FLUSH TABLES WITH READ LOCK; UNLOCK TABLES;"

Agent Sees Wrong Script

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

Diagnosis:

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

Solution:

Verify campaign assignment in admin panel
Clear browser cache: Ctrl+Shift+Delete
Reload agent screen: Ctrl+F5
Check for conflicting user-level script overrides:

SELECT user, script_override FROM vicidial_users WHERE user = 'agent1';

Summary

Configuring ViciDial agent call scripts involves:

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

Production best practices:

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

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

How to Configure ViciDial Caller ID (CID) Settings Per Campaign

Moisi Trungu — Wed, 07 Oct 2026 03:30:02 +0000

How to Configure ViciDial Caller ID (CID) Settings Per Campaign

Master per-campaign Caller ID configuration in ViciDial/Asterisk to control outbound number presentation, dynamic CID routing, and compliance-driven number assignment across multiple campaigns.

Prerequisites

Before you begin configuring ViciDial Caller ID settings per campaign, ensure the following:

ViciDial 2.14+ installed and running (this tutorial covers 2.14-2.17)
Asterisk 11+ compiled with ViciDial patches
Direct database access (MySQL/MariaDB) to the asterisk database
SSH access to the ViciDial server with sudo privileges
Carrier/trunk configuration already established with available DID numbers
Understanding of basic ViciDial campaign structure and dialplan concepts
PHP web admin access (/vicidial/admin.php)

Verify your ViciDial version:

sudo -u asterisk cat /etc/asterisk/vici_domains.conf | head -20

Check Asterisk is running:

sudo asterisk -rx "core show version"

Understanding ViciDial Caller ID Architecture

ViciDial handles Caller ID assignment through a hierarchical system with multiple fallback points. Understanding this chain is critical for proper configuration.

The CID Assignment Priority Chain

When an agent dials a lead in ViciDial, the system determines which number to present in this order:

Campaign-level CID (if configured in campaign settings)
User/Agent-level CID (if assigned to the specific agent)
Carrier CID (numbers assigned to the outbound carrier/trunk)
Server default CID (fallback number configured at server level)
Trunk/Channel default (last resort from Asterisk trunk config)

This hierarchy allows fine-grained control. A campaign can override agent settings, but agents can still have their own CID if the campaign isn't strict.

Key Database Tables

Three primary tables govern CID behavior:

vicidial_campaigns — campaign-wide CID settings
vicidial_users — agent-specific CID overrides
vicidial_carrier_log — outbound carrier trunk configurations

Accessing Campaign CID Settings via Web Admin

The quickest method for most ViciDial administrators is through the web interface.

Step 1: Navigate to Campaign Configuration

Log in to /vicidial/admin.php as a user with campaign edit permissions
Click Campaigns → Modify Campaign
Select your target campaign from the dropdown
Look for Caller ID Number field near the top of the form

Step 2: Set Campaign-Level CID

The Caller ID Number field accepts:

Static number: 15551234567 — all calls from this campaign present this number
Carrier default: Leave blank — use the trunk/carrier's assigned DID
Variable assignment: See dynamic section below

Example configuration:

Campaign Name: Sales_Outbound_US
Caller ID Number: 15551234567
Caller ID Name: Acme Sales

Step 3: Save and Verify

Click SUBMIT to save. The web interface commits directly to the vicidial_campaigns table.

Verify in MySQL:

SELECT campaign_id, campaign_name, outbound_cid, cid_name FROM vicidial_campaigns 
WHERE campaign_name='Sales_Outbound_US'\G

Expected output:

      campaign_id: 1
     campaign_name: Sales_Outbound_US
        outbound_cid: 15551234567
           cid_name: Acme Sales

Database-Level CID Configuration

For advanced scenarios or bulk updates, modify the database directly.

Direct Campaign CID Update

Update a single campaign:

UPDATE vicidial_campaigns 
SET outbound_cid='15551234567', cid_name='Acme Sales'
WHERE campaign_id=1;

Verify the change immediately:

SELECT campaign_id, campaign_name, outbound_cid, cid_name 
FROM vicidial_campaigns WHERE campaign_id=1;

Bulk Update Multiple Campaigns

Update all campaigns with a specific status or prefix:

UPDATE vicidial_campaigns 
SET outbound_cid='16175550123', cid_name='Boston Office'
WHERE campaign_name LIKE 'Boston_%' AND active='Y';

Check how many rows were affected:

SELECT COUNT(*) FROM vicidial_campaigns 
WHERE campaign_name LIKE 'Boston_%' AND active='Y';

Agent-Level CID Override

Override campaign CID for specific agents:

UPDATE vicidial_users 
SET outbound_cid='15559876543', cid_name='John Smith'
WHERE user='john.smith' AND user_level >= 1;

Verify:

SELECT user, user_name, outbound_cid, cid_name 
FROM vicidial_users WHERE user='john.smith';

Important: Agent-level CID only applies if the campaign doesn't have a strict CID policy. Check the campaign's outbound_cid field—if set, it overrides agents.

View Current CID Configuration Across Campaigns

Generate a report of all campaign CID settings:

SELECT 
    campaign_id,
    campaign_name,
    outbound_cid,
    cid_name,
    active,
    campaign_type
FROM vicidial_campaigns 
WHERE active='Y' 
ORDER BY campaign_name;

Asterisk Dialplan Integration

The actual CID presentation happens in Asterisk dialplan. ViciDial uses extension contexts generated from database records.

Reviewing Generated Dialplan

ViciDial writes dialplan on each service restart. The outbound campaign dialplan is in:

cat /etc/asterisk/extensions-vicidial.conf | grep -A 20 "exten => 8,1"

Look for Set(CALLERID(num)= statements:

exten => 8,1,Set(CALLERID(num)=15551234567)
exten => 8,2,Set(CALLERID(name)=Acme Sales)
exten => 8,3,Dial(...)

Manual Dialplan Override (Advanced)

For custom CID logic, edit /etc/asterisk/extensions-custom.conf:

[from-internal-custom]
exten => _91XXXXXXXXX,1,NoOp(Custom CID for campaign)
exten => _91XXXXXXXXX,n,Set(CALLERID(num)=15551234567)
exten => _91XXXXXXXXX,n,Set(CALLERID(name)=Acme Sales)
exten => _91XXXXXXXXX,n,Goto(from-internal,${EXTEN},1)

Reload the dialplan after edits:

sudo asterisk -rx "dialplan reload"

Warning: Custom dialplan changes will be overwritten on next ViciDial service restart. Use only for testing or if you can regenerate extensions programmatically.

Dynamic CID Assignment per Campaign

For scenarios requiring different CID numbers based on area codes, time of day, or lead data, use Asterisk AstDB or a custom script.

Method 1: Using Asterisk AstDB

Store CID mappings in AstDB (Asterisk internal database):

sudo asterisk -rx "database put CAMPAIGN_CID campaign_1 15551234567"
sudo asterisk -rx "database put CAMPAIGN_CID campaign_2 16175550123"
sudo asterisk -rx "database put CAMPAIGN_CID campaign_3 12125559999"

Verify storage:

sudo asterisk -rx "database show CAMPAIGN_CID"

Expected output:

/CAMPAIGN_CID/campaign_1                             : 15551234567
/CAMPAIGN_CID/campaign_2                             : 16175550123
/CAMPAIGN_CID/campaign_3                             : 12125559999

Add to /etc/asterisk/extensions-custom.conf:

[from-internal-custom]
exten => _91XXXXXXXXX,1,NoOp(Dynamic CID lookup for ${CAMPAIGN_ID})
exten => _91XXXXXXXXX,n,Set(CID_NUM=${DB(CAMPAIGN_CID/${CAMPAIGN_ID})})
exten => _91XXXXXXXXX,n,ExecIf($["${CID_NUM}" != ""]?Set(CALLERID(num)=${CID_NUM}))
exten => _91XXXXXXXXX,n,Goto(from-internal,${EXTEN},1)

Reload dialplan:

sudo asterisk -rx "dialplan reload"

Method 2: Area Code-Based CID Routing

Route outbound CID based on the lead's area code:

-- Create a lookup table
CREATE TABLE IF NOT EXISTS vicidial_cid_routing (
    cid_route_id INT AUTO_INCREMENT PRIMARY KEY,
    campaign_id INT,
    area_code VARCHAR(3),
    outbound_cid VARCHAR(20),
    active CHAR(1) DEFAULT 'Y'
);

-- Populate with examples
INSERT INTO vicidial_cid_routing (campaign_id, area_code, outbound_cid, active)
VALUES 
    (1, '617', '16175551234', 'Y'),
    (1, '212', '12125559876', 'Y'),
    (1, '310', '13105554321', 'Y');

Add Asterisk logic:

[from-internal-custom]
exten => _91XXXXXXXXX,1,NoOp(Area-code-based CID for ${EXTEN:2:3})
exten => _91XXXXXXXXX,n,Set(AREA_CODE=${EXTEN:2:3})
exten => _91XXXXXXXXX,n,Set(CID_NUM=${ODBC_LOOKUP(cid_lookup,${CAMPAIGN_ID},${AREA_CODE})})
exten => _91XXXXXXXXX,n,ExecIf($["${CID_NUM}" != ""]?Set(CALLERID(num)=${CID_NUM}))
exten => _91XXXXXXXXX,n,Goto(from-internal,${EXTEN},1)

Carrier/Trunk CID Configuration

ViciDial campaigns route through carriers (trunks). Each carrier can have specific DID pools or CID ranges.

Viewing Carrier Configuration

SELECT 
    carrier_id,
    carrier_name,
    outbound_cid,
    outbound_cid_override,
    active
FROM vicidial_carrier_log
LIMIT 10;

Assigning DIDs to Carriers

ViciDial manages DIDs through vicidial_did_log:

SELECT 
    did_id,
    did_number,
    carrier_id,
    active,
    did_route
FROM vicidial_did_log
WHERE active='Y'
ORDER BY carrier_id;

Linking Campaign to Specific Carrier

Some ViciDial installations require explicit carrier assignment per campaign:

-- Check if your ViciDial version tracks carrier_id in campaigns
DESCRIBE vicidial_campaigns | grep carrier;

-- If present, assign campaign to carrier
UPDATE vicidial_campaigns 
SET carrier_id=1
WHERE campaign_id=5;

Note: Not all ViciDial versions have carrier_id in the campaign table. Check your schema first.

SIP Trunk Configuration for CID

The actual SIP trunk configuration in Asterisk determines whether CID is allowed, blocked, or modified by carriers.

Example SIP Trunk Configuration

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

[carrier_outbound_trunk](!)
type=peer
context=from-carriers
disallow=all
allow=alaw,ulaw,gsm
nat=yes
host=carrier.example.com
port=5060
insecure=port,invite

[carrier_outbound_trunk](carrier_outbound_trunk)
accountcode=OUTBOUND_CARRIER_1
fromuser=customer_acct
fromdomain=carrier.example.com
defaultuser=customer_acct
secret=your_sip_password_here

Controlling CID Presentation in SIP INVITE

Add per-trunk CID settings:

[carrier_outbound_trunk](!)
; ... existing config ...
setvar=OUTBOUND_CID=15551234567
setvar=OUTBOUND_CID_NAME=Acme Sales
; Allow or restrict CID override
directmedia=no

Pass CID to carrier via dialplan:

exten => _91XXXXXXXXX,1,Set(CALLERID(num)=15551234567)
exten => _91XXXXXXXXX,2,Set(CALLERID(name)=Acme Sales)
exten => _91XXXXXXXXX,3,Dial(SIP/${EXTEN}@carrier_outbound_trunk)

Compliance and Call Recording CID Logging

ViciDial logs all calls with their CID in vicidial_log and vicidial_closer_log.

Verifying Logged CID

Check the call log for a specific campaign:

SELECT 
    call_id,
    campaign_id,
    callerid_number,
    callerid_name,
    call_date,
    status
FROM vicidial_log
WHERE campaign_id=1 AND call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
ORDER BY call_date DESC
LIMIT 10;

Example output:

call_id: 1700156234.142
campaign_id: 1
callerid_number: 15551234567
callerid_name: Acme Sales
call_date: 2024-01-15 14:30:12
status: SALE

Auditing CID Changes Over Time

Create an audit log of CID configuration changes:

SELECT 
    campaign_id,
    campaign_name,
    outbound_cid,
    cid_name,
    modification_date
FROM vicidial_campaigns_archive
WHERE campaign_id=1
ORDER BY modification_date DESC;

If vicidial_campaigns_archive doesn't exist, manually log critical changes:

sudo asterisk -rx "database put CAMPAIGN_CID_AUDIT campaign_1_change_$(date +%s) '15551234567|$(date)'"

Troubleshooting CID Issues

Issue 1: CID Not Displaying Correctly to Called Party

Symptom: Outbound calls show wrong Caller ID or generic number.

Diagnosis:

Check campaign CID setting:

SELECT outbound_cid, cid_name FROM vicidial_campaigns WHERE campaign_id=1\G

Verify agent CID doesn't override:

SELECT outbound_cid, cid_name FROM vicidial_users WHERE user='agent_name'\G

Check Asterisk dialplan generated:

grep -i "callerid" /etc/asterisk/extensions-vicidial.conf | head -20

Monitor live call in Asterisk:

sudo asterisk -rx "core show channels verbose" | grep OUTGOING

Check Asterisk logs:

sudo tail -100 /var/log/asterisk/messages | grep -i callerid

Solution:

Regenerate dialplan:

sudo systemctl restart viciserver

Or manually reload:

sudo asterisk -rx "dialplan reload"

Issue 2: CID Rejected by Carrier

Symptom: Calls connect but caller ID shows as "Anonymous" or default carrier number.

Diagnosis:

Verify carrier accepts the CID:

sudo asterisk -rx "sip show peer carrier_outbound_trunk"

Check SIP debug logs:

sudo asterisk -rx "sip set debug on"
# Make a test call
sudo asterisk -rx "sip set debug off"
sudo tail -200 /var/log/asterisk/messages | grep -i "callerid\|from:"

Contact carrier to verify:
- CID number is whitelisted
- CID format is correct (E.164: +1NXXXXXXXXX)
- Account permissions allow CID override

Solution:

Reformat CID to carrier's requirement
Request CID whitelist approval from carrier
Use carrier-assigned DID if available

Issue 3: Incorrect CID on Agent Transfers

Symptom: When an agent transfers a call, different CID presents.

Diagnosis:

Check if attended transfer preserves CID:

sudo asterisk -rx "core show function REDIRECTING"

Verify in call logs:

SELECT call_id, callerid_number, transfer_to, transfer_from 
FROM vicidial_log 
WHERE campaign_id=1 AND call_date >= NOW() - INTERVAL 1 HOUR;

Solution:

Configure transfer preservation in /etc/asterisk/extensions-custom.conf:

exten => _91XXXXXXXXX,1,Set(REDIRECTING(num)=${CALLERID(num)})
exten => _91XXXXXXXXX,2,Set(REDIRECTING(name)=${CALLERID(name)})
exten => _91XXXXXXXXX,3,Dial(SIP/extension@asterisk)

Issue 4: Database Changes Not Reflecting in Calls

Symptom: Updated campaign CID in database, but old number still showing.

Cause: Asterisk dialplan is cached in memory.

Solution:

Fully restart ViciDial services:

sudo systemctl stop viciserver
sudo systemctl stop vicidial-Apache
sleep 5
sudo systemctl start viciserver
sudo systemctl start vicidial-Apache

Verify reload completed:

sudo asterisk -rx "dialplan show from-internal" | grep -i callerid | head -5

Issue 5: CID Shows Campaign Name Instead of Number

Symptom: Caller ID displays campaign name (e.g., "Sales_Outbound") instead of phone number.

Diagnosis:

Check for misconfiguration in campaign CID field:

SELECT campaign_id, campaign_name, outbound_cid, cid_name 
FROM vicidial_campaigns WHERE campaign_name='Sales_Outbound'\G

If outbound_cid contains non-numeric characters, it's misconfigured.

Solution:

Fix the field to contain only digits:

UPDATE vicidial_campaigns 
SET outbound_cid='15551234567'
WHERE campaign_name='Sales_Outbound';

Verify the format matches E.164:

# Should match pattern: 1-15 digits, starting with 1 for US numbers
echo "15551234567" | grep -E '^1[0-9]{10,14}$' && echo "Valid" || echo "Invalid"

Debug CID in Real-Time

Enable verbose logging and run a test call:

# Terminal 1: Enable debug
sudo asterisk -rx "core set verbose 5"
sudo asterisk -rx "sip set debug on"

# Terminal 2: Monitor logs
sudo tail -f /var/log/asterisk/messages | grep -i callerid

# Terminal 3: Run test call from agent screen (/agc/vicidial.php)
# Monitor both logs

Check both agent screen and logs for confirmation:

sudo grep "campaign_id=1" /var/log/asterisk/messages | tail -20

Production Best Practices

1. Document CID Assignments

Maintain a spreadsheet or wiki of all campaign CID assignments:

Campaign ID	Campaign Name	Assigned CID	CID Name	Carrier	Status
1	Sales_US	15551234567	Acme Sales	Carrier A	Active
2	Support_CA	14165559999	Acme Support	Carrier B	Active
3	Collections_Test	15559876543	Test CID	Carrier A	Testing

2. Use Staging Environment

Test CID changes in a staging ViciDial before production:

# Backup production campaign settings
mysqldump -u asterisk -p asterisk vicidial_campaigns > campaigns_backup_$(date +%Y%m%d).sql

# Test in staging first
mysql -u asterisk -p asterisk_stage < test_campaign_cid.sql

3. Implement Change Control

Log all manual CID changes:

# Create audit log
echo "[$(date)] Changed campaign 1 CID from 15551111111 to 15551234567 - Admin: $(whoami)" >> /var/log/vicidial_cid_changes.log

4. Validate CID Format

Before updating, validate CID numbers:

# Simple validation script
validate_cid() {
    if [[ $1 =~ ^1[0-9]{10,14}$ ]] || [[ $1 =~ ^\+1[0-9]{10,14}$ ]]; then
        echo "Valid CID: $1"
        return 0
    else
        echo "Invalid CID format: $1"
        return 1
    fi
}

validate_cid "15551234567" && echo "OK" || echo "FAIL"

5. Monitor CID Effectiveness

Regularly audit that CID is logging correctly:

-- Daily CID verification report
SELECT 
    DATE(call_date) as call_date,
    campaign_id,
    COUNT(*) as call_count,
    COUNT(DISTINCT callerid_number) as unique_cids
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY DATE(call_date), campaign_id
ORDER BY call_date DESC;

Summary

Configuring Caller ID per ViciDial campaign requires understanding the CID assignment hierarchy, database configuration, and Asterisk dialplan integration. Key takeaways:

Use the web admin (/vicidial/admin.php) for simple, one-off campaign CID changes
Access the database directly for bulk updates or complex scenarios
Understand the hierarchy: Campaign CID overrides agent CID, which overrides carrier default
Verify in Asterisk: Monitor dialplan generation and reload to ensure changes take effect
Test before production: Use staging environments and maintain change logs
Audit regularly: Check vicidial_log to confirm CID is presenting correctly to called parties
Handle carrier restrictions: Some carriers whitelist or restrict CID numbers; coordinate with your carrier
Troubleshoot methodically: Check database → dialplan → Asterisk logs → carrier support

For dynamic CID assignment beyond static campaign settings, use AstDB lookups or custom dialplan logic tied to area codes, lead data, or other routing variables. Always maintain backups before bulk changes and test in a staging environment whenever possible.

The configuration is now complete and ready for production use. Monitor call logs regularly to ensure CID compliance and effectiveness.

How to Set Up ViciDial Scheduled Callbacks — Agent & Campaign Level

Moisi Trungu — Tue, 06 Oct 2026 03:30:04 +0000

How to Set Up ViciDial Scheduled Callbacks — Agent & Campaign Level

Master both agent-initiated and campaign-level scheduled callbacks in ViciDial, including database configuration, Asterisk dialplan setup, and production troubleshooting.

Prerequisites

Before implementing scheduled callbacks, ensure you have:

ViciDial v2.14 or later installed and running
Asterisk 13+ with proper SIP configuration
MySQL/MariaDB access with direct database privileges
Administrator access to /vicidial/admin.php web interface
SSH access to the ViciDial server for file editing
Basic understanding of ViciDial call flow and campaign structure
At least one active campaign and inbound group configured
Asterisk CLI access via asterisk -rx commands
Daily cron jobs already configured for callback processing (/usr/share/astguiclient/)

Understanding ViciDial Callback Types

ViciDial supports two primary callback mechanisms:

Agent-Level Scheduled Callbacks

Callbacks initiated by agents during live calls via the agent screen (/agc/vicidial.php). The agent sets a callback time, and the system attempts to reach the lead at the scheduled time.

Campaign-Level Scheduled Callbacks

Callbacks triggered automatically by campaign rules, IVR results, or system events. These run on a larger scale and respect campaign-wide settings.

Both types store data in the vicidial_log and vicidial_closer_log tables but follow different processing workflows.

Section 1: Database Configuration for Callbacks

Step 1.1: Verify Core Tables Exist

Log into your ViciDial MySQL database and confirm callback-related tables:

mysql -u root -p asterisk -e "SHOW TABLES LIKE '%vicidial%';" | grep -E "(log|callback)"

You should see tables including:

vicidial_log (main call log)
vicidial_closer_log (agent notes and callbacks)
vicidial_list (lead records)
vicidial_callbacks (scheduled callback queue)

Step 1.2: Create or Verify Vicidial_Callbacks Table

If the vicidial_callbacks table doesn't exist, create it:

CREATE TABLE `vicidial_callbacks` (
  `callback_id` int(11) NOT NULL AUTO_INCREMENT,
  `lead_id` int(11) NOT NULL,
  `campaign_id` varchar(8) NOT NULL,
  `callback_time` datetime NOT NULL,
  `callback_type` varchar(10) DEFAULT 'AGENT',
  `user_id` varchar(20) DEFAULT NULL,
  `phone_number` varchar(20) NOT NULL,
  `notes` text,
  `status` varchar(20) DEFAULT 'PENDING',
  `created_date` datetime DEFAULT CURRENT_TIMESTAMP,
  `processed_date` datetime DEFAULT NULL,
  `attempt_count` int(11) DEFAULT 0,
  `max_attempts` int(11) DEFAULT 3,
  PRIMARY KEY (`callback_id`),
  KEY `idx_campaign_time` (`campaign_id`, `callback_time`),
  KEY `idx_lead_campaign` (`lead_id`, `campaign_id`),
  KEY `idx_status` (`status`),
  KEY `idx_callback_time` (`callback_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Step 1.3: Add Callback Fields to Vicidial_List

Ensure the vicidial_list table has callback-related columns:

ALTER TABLE `vicidial_list` ADD COLUMN IF NOT EXISTS `callback_date` datetime DEFAULT NULL;
ALTER TABLE `vicidial_list` ADD COLUMN IF NOT EXISTS `callback_type` varchar(10) DEFAULT 'AGENT';
ALTER TABLE `vicidial_list` ADD COLUMN IF NOT EXISTS `last_callback_attempt` datetime DEFAULT NULL;

CREATE INDEX idx_callback_date ON vicidial_list(callback_date);

Step 1.4: Extend Vicidial_Closer_Log for Callback Tracking

Add callback metadata to agent notes table:

ALTER TABLE `vicidial_closer_log` ADD COLUMN IF NOT EXISTS `scheduled_callback` datetime DEFAULT NULL;
ALTER TABLE `vicidial_closer_log` ADD COLUMN IF NOT EXISTS `callback_phone` varchar(20) DEFAULT NULL;
ALTER TABLE `vicidial_closer_log` ADD COLUMN IF NOT EXISTS `callback_notes` text;

CREATE INDEX idx_scheduled_callback ON vicidial_closer_log(scheduled_callback);

Section 2: Campaign-Level Callback Configuration

Step 2.1: Access Campaign Settings

Log into the ViciDial admin panel:

https://YOUR_VICIDIAL_IP/vicidial/admin.php

Navigate to: Admin → Manage Campaigns

Select your target campaign and scroll to the "Callback Settings" section.

Step 2.2: Configure Campaign Callback Parameters

Set the following fields:

Parameter	Value	Description
Callback Enabled	YES	Activates callback feature for the campaign
Callback Attempt Limit	3	Maximum retry attempts
Callback Time Window	09:00-17:00	Hours when callbacks should be attempted
Callback Interval	300	Seconds between retry attempts (300 = 5 min)
Callback Lead Status	CBHOLD	Lead status after callback is scheduled
Callback Dial Timeout	45	Seconds to wait for answer before hanging up

Step 2.3: Update Campaign in Database

Alternatively, update directly via SQL:

UPDATE vicidial_campaigns 
SET 
  use_callbacks = 'Y',
  callback_attempts = 3,
  callback_interval = 300,
  callback_leadstatus = 'CBHOLD'
WHERE campaign_id = 'YOUR_CAMPAIGN_ID';

Verify the update:

SELECT campaign_id, use_callbacks, callback_attempts, callback_interval, callback_leadstatus 
FROM vicidial_campaigns 
WHERE campaign_id = 'YOUR_CAMPAIGN_ID';

Section 3: Agent-Level Callback Setup via Agent Screen

Step 3.1: Understanding the Agent Screen Callback Button

When an agent is on a live call in /agc/vicidial.php, they can click the "Schedule Callback" button. This triggers a JavaScript modal for entering callback details.

Step 3.2: Modify Agent Screen for Callback Display

Edit the agent application configuration file:

sudo nano /var/www/html/agc/vicidial.php

Locate the callback button section (typically around line 800-1200) and ensure this code block exists:

function schedule_callback_form() {
  var callback_time = prompt("Enter callback time (YYYY-MM-DD HH:MM:SS):", new Date().toISOString().slice(0, 19));

  if (callback_time) {
    var callback_phone = prompt("Callback phone number:", document.getElementById('phone_number').value);
    var callback_notes = prompt("Callback notes:", "");

    var xhr = new XMLHttpRequest();
    xhr.open("POST", "/agc/schedule_callback.php", true);
    xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
    xhr.onload = function() {
      if (xhr.status === 200) {
        alert("Callback scheduled successfully!");
        log_callback_in_notes(callback_time, callback_notes);
      }
    };
    xhr.send("lead_id=" + encodeURIComponent(lead_id) + 
             "&callback_time=" + encodeURIComponent(callback_time) + 
             "&callback_phone=" + encodeURIComponent(callback_phone) + 
             "&callback_notes=" + encodeURIComponent(callback_notes) +
             "&campaign_id=" + encodeURIComponent(campaign_id) +
             "&user_id=" + encodeURIComponent(user_id));
  }
}

Step 3.3: Create Callback Processing PHP Script

Create a new file for handling agent callback submissions:

sudo nano /var/www/html/agc/schedule_callback.php

Add the following code:

<?php
// ViciDial Agent Callback Submission Handler
error_reporting(E_ALL);
ini_set('display_errors', 0);

// Security: Verify session
session_start();
if (!isset($_SESSION['user_id'])) {
    http_response_code(401);
    echo json_encode(['error' => 'Unauthorized']);
    exit;
}

// Database connection
$DB_host = 'localhost';
$DB_user = 'vicidial';
$DB_pass = 'VICIDIAL_DB_PASSWORD'; // Change this
$DB_name = 'asterisk';

$mysqli = new mysqli($DB_host, $DB_user, $DB_pass, $DB_name);
if ($mysqli->connect_error) {
    http_response_code(500);
    echo json_encode(['error' => 'Database connection failed']);
    exit;
}

// Input validation
$lead_id = intval($_POST['lead_id']);
$campaign_id = $mysqli->real_escape_string($_POST['campaign_id']);
$callback_time = $mysqli->real_escape_string($_POST['callback_time']);
$callback_phone = preg_replace('/[^0-9]/', '', $_POST['callback_phone']);
$callback_notes = $mysqli->real_escape_string($_POST['callback_notes']);
$user_id = $mysqli->real_escape_string($_SESSION['user_id']);

// Validate callback time is in the future
$callback_timestamp = strtotime($callback_time);
if ($callback_timestamp <= time()) {
    http_response_code(400);
    echo json_encode(['error' => 'Callback time must be in the future']);
    exit;
}

// Insert into vicidial_callbacks table
$query = "INSERT INTO vicidial_callbacks 
          (lead_id, campaign_id, callback_time, callback_type, user_id, phone_number, notes, status) 
          VALUES 
          ($lead_id, '$campaign_id', '$callback_time', 'AGENT', '$user_id', '$callback_phone', '$callback_notes', 'PENDING')";

if ($mysqli->query($query)) {
    // Update vicidial_list to mark callback pending
    $update_query = "UPDATE vicidial_list 
                    SET callback_date = '$callback_time', 
                        callback_type = 'AGENT',
                        last_callback_attempt = NOW()
                    WHERE lead_id = $lead_id";

    $mysqli->query($update_query);

    // Log to closer log for agent reference
    $closer_query = "INSERT INTO vicidial_closer_log 
                    (lead_id, campaign_id, call_date, user_id, scheduled_callback, callback_phone, callback_notes) 
                    VALUES 
                    ($lead_id, '$campaign_id', NOW(), '$user_id', '$callback_time', '$callback_phone', '$callback_notes')";

    $mysqli->query($closer_query);

    http_response_code(200);
    echo json_encode(['success' => true, 'callback_id' => $mysqli->insert_id]);
} else {
    http_response_code(500);
    echo json_encode(['error' => $mysqli->error]);
}

$mysqli->close();
?>

Section 4: Asterisk Dialplan Configuration

Step 4.1: Create Callback Processing Extension

Edit your Asterisk extensions configuration:

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

Add a dedicated context for callback processing:

[callback-outbound]
exten => _.,1,NoOp(ViciDial Callback Processing - Leg: ${CALLLEG})
 same => n,Set(TIMEOUT(absolute)=3600)
 same => n,Log(NOTICE, Processing callback for lead: ${lead_id})
 same => n,Dial(SIP/${callback_phone}@callback-carrier,45,tTkKwW)
 same => n,GoTo(callback-result-${DIALSTATUS},1)

exten => callback-result-ANSWER,1,NoOp(Callback answered successfully)
 same => n,Set(DB(vicidial/callback/${lead_id})=ANSWERED)
 same => n,Set(callback_status=ANSWERED)
 same => n,Hangup()

exten => callback-result-BUSY,1,NoOp(Callback line busy - will retry)
 same => n,Set(DB(vicidial/callback/${lead_id})=BUSY)
 same => n,Hangup()

exten => callback-result-NOANSWER,1,NoOp(No answer on callback)
 same => n,Set(DB(vicidial/callback/${lead_id})=NOANSWER)
 same => n,Hangup()

exten => callback-result-CHANUNAVAIL,1,NoOp(Channel unavailable for callback)
 same => n,Set(DB(vicidial/callback/${lead_id})=FAILED)
 same => n,Hangup()

exten => h,1,NoOp(Hangup handler for callback)
 same => n,Log(NOTICE, Callback hangup - Status: ${callback_status})

Step 4.2: Update SIP Configuration for Callback Carrier

Edit the SIP configuration to allow callback outbound routing:

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

Add or modify the callback carrier section:

[callback-carrier]
type=peer
host=YOUR_CARRIER_IP_OR_HOSTNAME
port=5060
secret=YOUR_SIP_SECRET
username=YOUR_SIP_USERNAME
fromuser=YOUR_SIP_USERNAME
fromdomain=YOUR_SIP_DOMAIN
dtmfmode=rfc2833
context=from-internal
disallow=all
allow=ulaw
allow=gsm
canreinvite=no
nat=force_rport,comedia
qualify=yes
qualifyfreq=60

Step 4.3: Reload Asterisk Configuration

After editing configuration files, reload Asterisk:

sudo asterisk -rx "sip reload"
sudo asterisk -rx "dialplan reload"
sudo asterisk -rx "core reload"

Verify the changes:

sudo asterisk -rx "sip show peers" | grep callback
sudo asterisk -rx "dialplan show callback-outbound"

Section 5: Cron Jobs and Scheduled Processing

Step 5.1: Create Callback Processing Script

Create the main callback processor script:

sudo nano /usr/share/astguiclient/vicidial_callbacks_processor.pl

Add the following Perl script:

#!/usr/bin/perl
# ViciDial Scheduled Callbacks Processor
# Runs every 60 seconds via cron
# Usage: /usr/share/astguiclient/vicidial_callbacks_processor.pl

use strict;
use warnings;
use DBI;
use DateTime;
use DateTime::Format::MySQL;

my $DB_host = 'localhost';
my $DB_user = 'vicidial';
my $DB_pass = 'VICIDIAL_DB_PASSWORD'; # Change this
my $DB_name = 'asterisk';

my $dbh = DBI->connect("DBI:mysql:$DB_name:$DB_host", $DB_user, $DB_pass)
    or die "Cannot connect to database: $DBI::errstr";

my $now = DateTime->now();
my $now_mysql = DateTime::Format::MySQL->format_datetime($now);

# Query pending callbacks due within the next 60 seconds
my $query = "SELECT cb.callback_id, cb.lead_id, cb.campaign_id, cb.phone_number, 
                    cb.callback_time, cb.attempt_count, cb.max_attempts, vl.phone_number as lead_phone
             FROM vicidial_callbacks cb
             JOIN vicidial_list vl ON cb.lead_id = vl.lead_id
             WHERE cb.status = 'PENDING'
             AND cb.callback_time <= DATE_ADD(NOW(), INTERVAL 60 SECOND)
             AND cb.callback_time > NOW()
             AND cb.attempt_count < cb.max_attempts
             ORDER BY cb.callback_time ASC
             LIMIT 50";

my $sth = $dbh->prepare($query);
$sth->execute() or die "Query failed: $DBI::errstr";

my $callback_count = 0;

while (my $row = $sth->fetchrow_hashref()) {
    my $callback_id = $row->{callback_id};
    my $lead_id = $row->{lead_id};
    my $campaign_id = $row->{campaign_id};
    my $phone_number = $row->{phone_number};
    my $attempt_count = $row->{attempt_count};
    my $max_attempts = $row->{max_attempts};

    # Execute Asterisk originate command
    my $asterisk_cmd = qq{
        Originate(SIP/$phone_number\@callback-carrier,exten,callback-outbound,$phone_number,1,,)
    };

    system("/usr/sbin/asterisk -rx \"$asterisk_cmd\"");

    # Update attempt count
    my $update_query = "UPDATE vicidial_callbacks 
                       SET attempt_count = attempt_count + 1,
                           processed_date = NOW()
                       WHERE callback_id = $callback_id";

    $dbh->do($update_query) or warn "Failed to update callback: $DBI::errstr";

    # Log the callback attempt
    system("logger -t vicidial_callbacks 'Callback initiated: lead_id=$lead_id, phone=$phone_number, attempt=" . ($attempt_count + 1) . "/$max_attempts'");

    $callback_count++;
}

# Mark expired callbacks as EXPIRED
my $expire_query = "UPDATE vicidial_callbacks 
                   SET status = 'EXPIRED'
                   WHERE status = 'PENDING'
                   AND callback_time < DATE_SUB(NOW(), INTERVAL 24 HOUR)";

$dbh->do($expire_query);

# Mark max-attempt callbacks as FAILED
my $fail_query = "UPDATE vicidial_callbacks 
                 SET status = 'FAILED'
                 WHERE status = 'PENDING'
                 AND attempt_count >= max_attempts";

$dbh->do($fail_query);

$dbh->disconnect();

exit(0);

Make the script executable:

sudo chmod 755 /usr/share/astguiclient/vicidial_callbacks_processor.pl

Step 5.2: Add Cron Job for Callback Processing

Edit the crontab:

sudo crontab -e

Add the following line to run callback processor every minute:

* * * * * /usr/share/astguiclient/vicidial_callbacks_processor.pl >> /var/log/asterisk/vicidial_callbacks.log 2>&1

Step 5.3: Monitor Callback Processing Logs

Create a log file and monitor it:

sudo touch /var/log/asterisk/vicidial_callbacks.log
sudo chown asterisk:asterisk /var/log/asterisk/vicidial_callbacks.log
sudo chmod 644 /var/log/asterisk/vicidial_callbacks.log

Monitor in real-time:

tail -f /var/log/asterisk/vicidial_callbacks.log

Section 6: Testing and Verification

Step 6.1: Manual Callback Test via SQL

Insert a test callback 5 minutes in the future:

INSERT INTO vicidial_callbacks 
(lead_id, campaign_id, callback_time, callback_type, user_id, phone_number, notes, status, max_attempts) 
VALUES 
(12345, 'TESTCAMP', DATE_ADD(NOW(), INTERVAL 5 MINUTE), 'AGENT', 'testuser', '15551234567', 'Test callback', 'PENDING', 3);

Verify the insert:

SELECT callback_id, lead_id, callback_time, status, attempt_count 
FROM vicidial_callbacks 
WHERE lead_id = 12345;

Step 6.2: Monitor Asterisk During Callback

In one terminal, watch Asterisk logs:

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

In another terminal, trigger the callback processor manually:

/usr/share/astguiclient/vicidial_callbacks_processor.pl

Step 6.3: Verify Callback Status in Database

Check the status after callback attempt:

SELECT callback_id, lead_id, status, attempt_count, processed_date 
FROM vicidial_callbacks 
WHERE lead_id = 12345
ORDER BY processed_date DESC;

Step 6.4: Check Agent Screen Integration

Log into the agent screen at /agc/vicidial.php with a test agent account. During a test call, click "Schedule Callback" and verify:

Modal appears with time and phone fields
Callback is inserted into database
Entry appears in agent's call notes
Callback time displays correctly in lead history

Section 7: Production Optimization

Step 7.1: Database Indexing for Performance

Add strategic indexes to improve callback query performance:

CREATE INDEX idx_callbacks_status_time ON vicidial_callbacks(status, callback_time);
CREATE INDEX idx_callbacks_campaign_time ON vicidial_callbacks(campaign_id, callback_time);
CREATE INDEX idx_callbacks_lead ON vicidial_callbacks(lead_id);
CREATE INDEX idx_list_callback ON vicidial_list(callback_date, callback_type);

Step 7.2: Rate Limiting for Callback Dialout

Modify the callback processor to respect concurrent call limits:

# Add to vicidial_callbacks_processor.pl
my $max_concurrent_callbacks = 10;
my $concurrent_query = "SELECT COUNT(*) as active_callbacks 
                       FROM asterisk.vicidial_callbacks 
                       WHERE status = 'PROCESSING'";
my $concurrent_sth = $dbh->prepare($concurrent_query);
$concurrent_sth->execute();
my $concurrent = $concurrent_sth->fetchrow_hashref()->{active_callbacks};

if ($concurrent >= $max_concurrent_callbacks) {
    exit(0); # Skip this run if limit reached
}

Step 7.3: Callback Time Zone Handling

Ensure callbacks respect agent/lead time zones:

ALTER TABLE vicidial_callbacks ADD COLUMN timezone_offset varchar(10) DEFAULT '+00:00';

UPDATE vicidial_callbacks cb
JOIN vicidial_list vl ON cb.lead_id = vl.lead_id
SET cb.timezone_offset = vl.state -- Assumes state field maps to timezone
WHERE cb.timezone_offset = '+00:00';

Update callback processor to account for timezone:

my $callback_time_utc = $row->{callback_time};
my $tz_offset = $row->{timezone_offset};
my $callback_time_local = DateTime->from_epoch(epoch => time(), time_zone => $tz_offset);

Section 8: Troubleshooting

Issue 1: Callbacks Not Triggering

Symptom: Callbacks scheduled but never attempt to dial.

Diagnosis:

# Check if cron job is running
sudo ps aux | grep vicidial_callbacks_processor
# Check cron logs
sudo grep CRON /var/log/syslog | tail -20

Solution:

Ensure the cron job is active and check file permissions:

sudo crontab -l | grep vicidial_callbacks_processor
sudo ls -la /usr/share/astguiclient/vicidial_callbacks_processor.pl

If missing, re-add to crontab as shown in Section 5.2.

Issue 2: Database Connection Errors

Symptom: Cannot connect to database errors in callback logs.

Diagnosis:

Verify database credentials in the Perl script match your installation:

sudo grep -i "DB_pass\|DB_user" /usr/share/astguiclient/*.pl | head -5

Solution:

Update credentials in /usr/share/astguiclient/vicidial_callbacks_processor.pl:

sudo nano /usr/share/astguiclient/vicidial_callbacks_processor.pl
# Edit the DB connection variables at the top

Test connection manually:

mysql -h localhost -u vicidial -p asterisk -e "SELECT COUNT(*) FROM vicidial_callbacks;"

Issue 3: Asterisk Originate Command Fails

Symptom: Callbacks attempted but SIP channels fail to originate.

Diagnosis:

Check Asterisk SIP peer status:

sudo asterisk -rx "sip show peers" | grep callback-carrier
sudo asterisk -rx "core show channels"

Check for SIP authentication errors:

sudo asterisk -rx "sip set debug on"
# Wait for callback to attempt
tail -f /var/log/asterisk/messages | grep -i "401\|403\|authentication"

Solution:

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

sudo asterisk -rx "sip show peer callback-carrier"

Test SIP connectivity:

sudo sipsak -U -s sip:YOUR_CARRIER_IP

Issue 4: Callback Phone Numbers Formatted Incorrectly

Symptom: Callbacks dial incomplete or malformed numbers.

Diagnosis:

Check stored phone numbers in database:

SELECT callback_id, phone_number, LENGTH(phone_number) as len 
FROM vicidial_callbacks 
WHERE status IN ('PENDING', 'PROCESSING') 
LIMIT 5;

Solution:

Standardize phone number formatting in the schedule_callback.php script:

function format_phone($phone) {
    $digits = preg_replace('/[^0-9]/', '', $phone);
    if (strlen($digits) == 10) {
        return '1' . $digits; // Add country code if missing
    }
    return $digits;
}

$callback_phone = format_phone($_POST['callback_phone']);

Issue 5: High Database Query Load from Callback Processing

Symptom: Database CPU spikes every minute during callback processor runs.

Diagnosis:

Check query execution time:

sudo mysql -u vicidial -p -e "SET GLOBAL log_queries_not_using_indexes=ON; SET GLOBAL long_query_time=1;"
tail -f /var/log/mysql/slow.log | grep callback

Solution:

Add batch processing and limit queries in the Perl script:

# Modify the query in vicidial_callbacks_processor.pl to add LIMIT
LIMIT 50  # Process max 50 callbacks per run

Increase cron interval from 1 minute to 5 minutes if needed:

*/5 * * * * /usr/share/astguiclient/vicidial_callbacks_processor.pl

Issue 6: Agents Report Callback Button Not Working

Symptom: Agent screen loads but callback scheduling fails silently.

Diagnosis:

Check browser console for JavaScript errors:

Open agent screen in browser
Press F12 (Developer Tools)
Go to Console tab
Attempt to schedule callback
Look for POST request failures

Check PHP error logs:

tail -f /var/log/apache2/error.log | grep schedule_callback
sudo grep -i "php error\|warning" /var/log/apache2/error.log | tail -20

Solution:

Verify schedule_callback.php exists and has correct permissions:

sudo ls -la /var/www/html/agc/schedule_callback.php
sudo chown www-data:www-data /var/www/html/agc/schedule_callback.php

Check if session is properly initialized in agent screen code:

grep -n "session_start" /var/www/html/agc/vicidial.php | head -3

Section 9: Monitoring and Reporting

Step 9.1: Callback Success Rate Report

Generate a callback success report:

SELECT 
    DATE(callback_time) as callback_date,
    campaign_id,
    COUNT(*) as total_callbacks,
    SUM(CASE WHEN status = 'ANSWERED' THEN 1 ELSE 0 END) as answered,
    SUM(CASE WHEN status = 'FAILED' THEN 1 ELSE 0 END) as failed,
    SUM(CASE WHEN status = 'PENDING' THEN 1 ELSE 0 END) as pending,
    ROUND(SUM(CASE WHEN status = 'ANSWERED' THEN 1 ELSE 0 END) / COUNT(*) * 100, 2) as success_rate_pct
FROM vicidial_callbacks
WHERE callback_time >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY DATE(callback_time), campaign_id
ORDER BY callback_date DESC, campaign_id;

Step 9.2: Agent Callback Activity

Track agent callback scheduling activity:

SELECT 
    user_id,
    campaign_id,
    COUNT(*) as callbacks_scheduled,
    AVG(TIMESTAMPDIFF(MINUTE, callback_time, NOW())) as avg_lead_time_minutes
FROM vicidial_callbacks
WHERE callback_type = 'AGENT'
AND created_date >= DATE_SUB(NOW(), INTERVAL 1 DAY)
GROUP BY user_id, campaign_id
ORDER BY callbacks_scheduled DESC;

Summary

You now have a complete, production-ready ViciDial scheduled callback system spanning both agent-initiated and campaign-level callbacks. Here's what you've implemented:

Key Components:

Database schema with callback tracking tables and indexes
Campaign configuration for automatic callback rules and retry logic
Agent screen integration with PHP form handler for manual callback scheduling
Asterisk dialplan with callback-specific contexts and SIP routing
Automated processing via Perl script and cron job for periodic callback attempts
Monitoring and logging for tracking callback performance and troubleshooting

Best Practices Applied:

Database indexing on frequently queried fields
Rate limiting to prevent overwhelming carriers
Time zone awareness for accurate callback scheduling
Comprehensive error handling and retry logic
Separation of agent and campaign callback workflows
Detailed logging for audit trails and debugging

Next Steps:

Deploy in a test environment first
Validate all database queries execute without errors
Monitor callback success rate for 1-2 weeks
Adjust retry intervals and time windows based on results
Train agents on callback scheduling via /agc/vicidial.php
Set up monitoring alerts for callback processor failures

Use the troubleshooting section to resolve environment-specific issues. Monitor /var/log/asterisk/vicidial_callbacks.log and Asterisk CLI output regularly to ensure callbacks are processing as expected.