VICIdial / Asterisk

Prerequisites#

Install#

1. Install Python and the WebSocket library

   VICIdial runs on openSUSE, so the example uses zypper. Use apt or yum on other systems.

   TerminalCopy

   zypper in -y python3-pip
   pip3 install --upgrade pip
   pip3 install websocket-client

2. Download the client

   Unpack vmhunter.agi.py into the Asterisk AGI directory. You can also download it from the dashboard.

   TerminalCopy

   wget -N -O vmhunter.tar.gz https://app.vmhunter.com/vmhunter.tar.gz
   tar zxvf vmhunter.tar.gz --directory /var/lib/asterisk/agi-bin
   chmod +x /var/lib/asterisk/agi-bin/vmhunter.agi.py

3. Set your API key

   The script reads its settings from environment variables. Asterisk must see them, so put them where its process picks them up: /etc/environment on most installs, or the unit's Environment= lines if Asterisk runs under systemd. Restart Asterisk after editing.

   /etc/environmentCopy

   AMD_WS_API_KEY="{YOUR_API_KEY}"
   AMD_LOG_FILE="/var/log/vmhunter.agi.log"

   To confirm Asterisk can see the variable: cat /proc/$(pidof asterisk)/environ | tr '\0' '\n' | grep AMD_

4. Add the routing extension

   Add this to the context your campaigns use (/etc/asterisk/extensions.conf on VICIdial). It runs VM Hunter, then hands the verdict to VICIdial's own VD_amd.agi, which drops the call when AMDSTATUS=MACHINE.

   /etc/asterisk/extensions.confCopy

   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(VMHUNTER AMDSTATUS=${AMDSTATUS} RAW=${AMDSTATUS_RAW} CAUSE=${AMDCAUSE})
    ; optional: give disconnected numbers their own disposition so the lead is not recycled
   exten => 8370,n,GotoIf($["${AMDCAUSE}"="DISCONNECT"]?disc)
   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()
   exten => 8370,n(disc),AGI(agi-VDAD_ALL_outbound.agi,DISCONNECT-----LB-----${CONNECTEDLINE(name)})
   exten => 8370,n,Hangup()

   Plain Asterisk without VICIdial: replace the two AGI(...) lines with your own branch on ${AMDSTATUS}, for example GotoIf($["${AMDSTATUS}"="HUMAN"]?agent:hangup).

5. Reload and test

   TerminalCopy

   asterisk -rx "dialplan reload"
   tail -f /var/log/vmhunter.agi.log

   Place a test call. Each call logs a line with the verdict, the cause and how long the round trip took. The same call appears in your call logs with the transcript and a recording of what the engine heard.

VICIdial campaign settings#

Point each outbound campaign at the new extension. Nothing else in the campaign changes.

Call screening (CALLGUARD)#

iPhone's “Ask reason for calling”, Google Call Screen and similar features answer the call with a prompt and let a real person listen. VM Hunter labels those calls AMDCAUSE=CALLGUARD_PHRASE:<phrase>. By default the client maps them to AMDSTATUS=HUMAN so they reach an agent.

A better experience is to play a short recorded introduction first, so the screener hears who is calling, then connect the agent. The 8371 extension below does that; use it for one test campaign.

exten => 8371,1,AGI(agi://127.0.0.1:4577/call_log)
exten => 8371,n,Playback(sip-silence)
exten => 8371,n,EAGI(/var/lib/asterisk/agi-bin/vmhunter.agi.py,${VID})
exten => 8371,n,NoOp(VMHUNTER AMDSTATUS=${AMDSTATUS} RAW=${AMDSTATUS_RAW} CAUSE=${AMDCAUSE})
exten => 8371,n,GotoIf($["${AMDCAUSE:0:9}" = "CALLGUARD"]?callguard)
exten => 8371,n,AGI(VD_amd.agi,${EXTEN})
exten => 8371,n,AGI(agi-VDAD_ALL_outbound.agi,NORMAL-----LB-----${CONNECTEDLINE(name)})
exten => 8371,n,Hangup()
exten => 8371,n(callguard),Playback(vmhunter-callguard-intro)
exten => 8371,n,Set(AMDSTATUS=HUMAN)
exten => 8371,n,AGI(VD_amd.agi,${EXTEN})
exten => 8371,n,AGI(agi-VDAD_ALL_outbound.agi,NORMAL-----LB-----${CONNECTEDLINE(name)})
exten => 8371,n,Hangup()

Record the intro as 8 kHz mono WAV at /var/lib/asterisk/sounds/vmhunter-callguard-intro.wav, three to five seconds, naming your company and the reason for the call:

sox intro.mp3 -r 8000 -c 1 -b 16 -e signed-integer /var/lib/asterisk/sounds/vmhunter-callguard-intro.wav

Configuration#

All settings are environment variables. Only the API key is required.

Channel variables set on every call:

Troubleshooting#