Docs / FreeSWITCH install
Install AMDY on FreeSWITCH
AI answering machine detection for FreeSWITCH. This guide uses mod_audio_fork to stream answered-call audio to the AMDY backend over WebSocket and route each call on the result. It uses the same backend as the ViciDial install, so results, timing, and your dashboard work the same way.
Prerequisites
- FreeSWITCH 1.8+ with mod_audio_fork available (see note below)
- Root access on the FreeSWITCH server
- Your AMDY.IO API key, from Settings
- Outbound TCP to api.amdy.io:2700
There is no prebuilt download for mod_audio_fork. You supply it to the installer either as a prebuilt .so (--module) or as a configured FreeSWITCH source tree (--fs-src) so it can build the module. If the module is already loaded, the installer keeps it.
1. Run the installer
On the FreeSWITCH server, as root, with your API key:
curl -fsSL https://download.amdy.io/installamd-freeswitch.sh | bash -s <API_KEY>
The installer:
- Installs and loads mod_audio_fork in modules.conf.xml
- Drops the AMDY dialplan snippet and the amdy_fork.lua driver script
- Registers this server's public IP with your AMDY account
AMDY authorizes fork connections by IP allowlist, because mod_audio_fork cannot send custom HTTP headers on the WebSocket upgrade. Your API key authorizes the one-time registration call and is stored in /etc/amdy/api-key.
2. Verify the install
One command checks the module, the dialplan snippet, and AMDY reachability:
curl -fsSL https://download.amdy.io/check-amdy-freeswitch.sh | bash
Or confirm the module is loaded manually. You should see true:
fs_cli -x "module_exists mod_audio_fork"
3. What the dialplan does on answer
- Answers the call.
- Starts an audio fork to ws://api.amdy.io:2700 at 8000 Hz mono.
- Sends one JSON config frame as call identity: {"config":{"sample_rate":8000,"VID":"<caller ID name>"}}. Set the caller ID name to your call identifier before the fork starts; if empty, AMDY records it as Unknown.
- Waits for the result and routes on it. Only results containing HUMAN reach an agent.
There is no dialplan application named fork; mod_audio_fork registers only the uuid_audio_fork API command. The installed snippet answers the call and runs the Lua driver, which calls:
uuid_audio_fork <uuid> start ws://api.amdy.io:2700 mono 8k {"config":{"sample_rate":8000,"VID":"<caller ID name>"}}4. Result values and routing
| amdy_result | Action |
|---|---|
| HUMAN | Bridge to agent |
| MACHINE | Transfer to voicemail extension |
| FAS | Hangup (CALL_REJECTED) |
| TIMEOUT | Hangup (RECOVERY_ON_TIMER_EXPIRE) |
| ERROR | Hangup (NETWORK_OUT_OF_ORDER) |
Keep the rule identical in spirit to the ViciDial HUMAN,HUMAN container setting: only HUMAN reaches an agent. Every other result is dispositioned automatically. Full status definitions: API reference.
5. Common problems
| Symptom | Likely cause |
|---|---|
| No result, call ends after ~10s | Outbound TCP to api.amdy.io:2700 blocked. Check firewall rules. |
| Connection rejected right after opening | This host's IP is not allowlisted. Re-run the installer registration. |
| NO AUDIO on every call | Fork not running, or no read-direction audio at 8 kHz. |
| Machines reaching agents | Routing matches too broadly. Bridge only on HUMAN. |
| Every call logs VID as Unknown | Caller ID name not set before the fork starts. |
| module_exists returns false | Module not loaded. Re-run the installer, check modules.conf.xml. |
Support
Need help? Email [email protected] with your FreeSWITCH version (fs_cli -x "version") and the output of the check script.