FreeSWITCH

Prerequisites#

Install#

1. Download the client

   Two files: the Lua script and an XML dialplan include.

   TerminalCopy

   wget -N -O vmhunter-freeswitch.tar.gz https://app.vmhunter.com/vmhunter-freeswitch.tar.gz
   tar zxvf vmhunter-freeswitch.tar.gz
   cp vmhunter_amd.lua /usr/share/freeswitch/scripts/
   cp vmhunter_amd.xml /etc/freeswitch/dialplan/default/

   Paths vary by packaging: on source builds use /usr/local/freeswitch/scripts and /usr/local/freeswitch/conf/dialplan/default. The XML goes in whichever context your dialer originates into.

2. Set your API key

   The script reads channel variables first and global variables second, so you can set the key once in vars.xml or pass it per call in the originate string.

   conf/vars.xmlCopy

   <X-PRE-PROCESS cmd="set" data="vmhunter_api_key={YOUR_API_KEY}"/>
   <!-- optional -->
   <X-PRE-PROCESS cmd="set" data="vmhunter_ws_url=ws://app.vmhunter.com:2701"/>

3. Reload

   TerminalCopy

   fs_cli -x "reloadxml"

4. Originate calls into the AMD extension

   Send the customer leg to vmhunter_amd so detection starts the moment the callee answers. vid is the lead or call id that VM Hunter bills and records under; it falls back to the channel UUID.

   fs_cliCopy

   originate {vid=12345,ignore_early_media=true,origination_caller_id_number=18005551212}sofia/gateway/carrier/15551234567 vmhunter_amd XML default

   Watch the result in the console:

   TerminalCopy

   fs_cli
   /log 6
   # [vmhunter] uuid=... vid=12345 module=audio_stream raw=MACHINE -> status=MACHINE cause=MACHINE_BEEP waited=2300ms

Routing the verdict#

The bundled dialplan runs the script, then transfers to vmhunter_route, which sends the call on to vmhunter_HUMAN or vmhunter_MACHINE. Edit those two extensions for your setup; everything above them can stay as it is.

<extension name="vmhunter_HUMAN">
  <condition field="destination_number" expression="^vmhunter_HUMAN$">
    <!-- hand the live person to your agents: a callcenter queue, a fifo, or a bridge -->
    <action application="callcenter" data="sales@default"/>
  </condition>
</extension>

<extension name="vmhunter_MACHINE">
  <condition field="destination_number" expression="^vmhunter_MACHINE$">
    <!-- disconnected numbers get their own disposition so the dialer does not recycle the lead -->
    <condition field="${AMDCAUSE}" expression="^DISCONNECT">
      <action application="set" data="dialer_disposition=DISCONNECT"/>
      <anti-action application="set" data="dialer_disposition=MACHINE"/>
    </condition>
    <action application="hangup" data="NORMAL_CLEARING"/>
  </condition>
</extension>

Call screening (CALLGUARD)#

Screened calls (iPhone “Ask reason for calling”, Google Call Screen) are labelled AMDCAUSE=CALLGUARD_PHRASE:<phrase>. The bundled vmhunter_route extension plays a short intro so the screener hears who is calling, marks the call HUMAN and connects an agent:

<extension name="vmhunter_route">
  <condition field="destination_number" expression="^vmhunter_route$"/>
  <condition field="${AMDCAUSE}" expression="^CALLGUARD">
    <action application="playback" data="$${sounds_dir}/vmhunter/callguard-intro.wav"/>
    <action application="set" data="AMDSTATUS=HUMAN"/>
    <action application="transfer" data="vmhunter_HUMAN XML default"/>
    <anti-action application="transfer" data="vmhunter_${AMDSTATUS} XML default"/>
  </condition>
</extension>

Record the intro as 8 kHz mono WAV at sounds/vmhunter/callguard-intro.wav. To keep dropping screened calls instead, delete the vmhunter_route extension and transfer straight to vmhunter_${AMDSTATUS}.

Configuration#

Variables the script reads (channel variable first, then global):

Two constants at the top of the script control the fail-safes:

Channel variables set on every call:

Troubleshooting#