Documentation
VICIdial Integration Guide
Real-time voicemail detection using WebSocket audio streaming with your VICIdial dialer.
How VM Hunter Works
VM Hunter uses WebSocket connections for real-time audio streaming and analysis.
Call Answered
When an outbound call is answered, Asterisk triggers the VM Hunter AGI script via the configured dialplan extension.
WebSocket Connection
The AGI script establishes a secure WebSocket connection to wss://vmhunter.com/ws and authenticates using your API key.
Real-time Audio Streaming
Raw audio from the call is streamed in real-time to VM Hunter's servers for immediate analysis by our SpeechLLM model.
Instant Classification
Within milliseconds, VM Hunter returns AMDSTATUS=HUMAN or AMDSTATUS=MACHINE, allowing your dialplan to route the call appropriately.
VICIdial Server
Asterisk + AGI
WebSocket
Real-time Audio
VM Hunter
SpeechLLM
HUMAN/MACHINE
Call Routing
AMDSTATUS
Prerequisites
Before you begin, ensure you have the following:
VICIdial Installation
Running VICIdial server with Asterisk
Python 3.x
With websockets library installed
VM Hunter API Key
Get from your dashboard
Root/Admin Access
To modify Asterisk configs
Installation
Follow these steps to install VM Hunter on your VICIdial server.
1Install Python and Dependencies
Install Python and the required websocket library for the AGI script:
# Install Python and pip
zypper in -y python3-pip
# Upgrade pip
pip install --upgrade pip
# Install websocket client library
pip install websocket-client2Download the AGI Script
Download vmhunter.agi.py and upload to your VICIdial AGI directory:
# Download vmhunter.tar.gz from VM Hunter Dashboard.
# Upload the AGI script to VICIdial
scp vmhunter.agi.py root@your-vicidial-server:/var/lib/asterisk/agi-bin/
# Or direct download vmhunter.tar.gz on vicidial server
wget -N -O vmhunter.tar.gz https://app.vmhunter.com/vmhunter.tar.gz
tar zxvf amdy.tar.gz --directory /var/lib/asterisk/agi-bin
# Set permissions
chmod +x /var/lib/asterisk/agi-bin/vmhunter.agi.py3Set Your API Key
Export your VM Hunter API key as an environment variable. Add this to your system startup script or /etc/environment:
export AMD_WS_API_KEY="{YOUR_API_KEY}"Replace {YOUR_API_KEY} with your actual API key from the VM Hunter Dashboard.
4Configure Asterisk Dialplan
Add the following dialplan to your Asterisk extensions configuration file:
exten => 8370,1,AGI(agi://127.0.0.1:4577/call_log)
exten => 8370,n,Playback(sip-silence)
exten => 8370,n,EAGI(/var/lib/asterisk/agi-bin/vmhunter.agi.py,${VID})
exten => 8370,n,NoOp(AMDSTATUS=${AMDSTATUS} AMDCAUSE=${AMDCAUSE})
exten => 8370,n,AGI(VD_amd.agi,${EXTEN})
exten => 8370,n,AGI(agi-VDAD_ALL_outbound.agi,NORMAL-----LB-----${CONNECTEDLINE(name)})
exten => 8370,n,Hangup()5Reload Asterisk
Apply the dialplan changes by reloading Asterisk:
asterisk -rx "dialplan reload"VICIdial Campaign Setup
Configure your VICIdial outbound campaign to use VM Hunter.
Campaign Settings
8370AMDEAGIPro Tip
Start your outbound campaign with the routing extension set to 8370. All answered calls will automatically be processed through VM Hunter for instant human/voicemail classification.
WebSocket API Reference
Technical details for the WebSocket connection and response formats.
Endpoint
ws://app.vmhunter.com:2701Authentication
Include your API key in the connection headers:
Authorization: Bearer {YOUR_API_KEY}Response Format
VM Hunter returns the following response codes:
| AMDSTATUS | Description |
|---|---|
HUMAN | Live person detected - route to agent |
MACHINE | Voicemail/Answering machine detected |
NOTSURE | Unable to determine (rare) |
AMDCAUSE Values
Additional context provided with the classification:
| AMDCAUSE | Meaning |
|---|---|
HUMAN | Natural human speech patterns detected |
MACHINE | Standard voicemail greeting detected |
INITIALSILENCE | Voicemail beep tone detected |
MAXWORD | Voicemail keywords detected |
Need Help?
Our support team is here to help you get VM Hunter up and running.