Integrate AMDY AMD with FreeSWITCH

What does this integration do?

The integration attaches an audio fork to every answered call, streams mono 8 kHz 16-bit PCM to the AMDY detection service, and waits for a classification. The result is exposed as channel variables that your dialplan branches on. Only HUMAN results reach an agent; everything else is dispositioned automatically.

mod_audio_fork cannot send custom HTTP headers on the WebSocket upgrade, so fork connections carry no X-API-Key. AMDY authorizes fork connections by IP allowlist instead. The installer registers this host's public IP against your account using your API key.

What do you need before you start?

• FreeSWITCH 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 verified prebuilt download URL for mod_audio_fork. The upstream drachtio repository was deleted. The installer accepts a prebuilt .so via --module (recommended), or builds from source when a configured FreeSWITCH source tree is available via --fs-src. If neither path works, the installer fails with instructions rather than downloading from an unverified source.

How do you install the AMDY FreeSWITCH integration?

Run the installer as root with your API key:

bash installamd-freeswitch.sh <API_KEY> [options]

Or pass a prebuilt module and a key together:

bash installamd-freeswitch.sh --api-key <KEY> --module /path/to/mod_audio_fork.so

Key installer options:

The installer:

1. Installs and loads mod_audio_fork in modules.conf.xml
2. Drops the amdy-fork.xml dialplan snippet and the amdy_fork.lua driver script
3. Stores the API key in /etc/amdy/api-key (mode 600)
4. Registers this server's public IP with your AMDY account via POST /api/v1/ips/register

How do you verify the install?

The health check script confirms six conditions in one run: FreeSWITCH is running, the event socket responds, mod_audio_fork is loaded, the amdy dialplan context is parsed, api.amdy.io:2700 is reachable, and the API key file exists.

bash check-amdy-freeswitch.sh

Or confirm the module manually. You should see true:

fs_cli -x "module_exists mod_audio_fork"

The check script exits 0 when all checks pass and 1 otherwise. It is safe to run repeatedly; it only reads state and never modifies the dialplan or module files.

What does the dialplan do on answer?

1. Answers the call. Media must be flowing before the fork attaches.
2. Runs amdy_fork.lua, which starts the audio fork:

uuid_audio_fork <uuid> start ws://api.amdy.io:2700 mono 8k {"config":{"sample_rate":8000,"VID":"<caller_id_name or Unknown>"}}

3. The config frame carries the call identity. VID maps to caller_id_name in FreeSWITCH (equivalent to agi_calleridname in Asterisk). If empty, AMDY records it as Unknown.
4. The Lua driver waits up to amdy_max_wait_ms (default 10000, clamped 1000–30000) for a classification from the server. It listens for mod_audio_fork::transcription and mod_audio_fork::json events filtered by the channel UUID.
5. When the deadline passes or a result arrives, the driver stops the fork by sending {"eof":1} as the final text frame, then sets channel variables for the dialplan to branch on.
6. The dialplan transfers to amdy_dispatch_${amdy_result}, which routes each result to its own extension.

What result values does AMDY return and how are they routed?

Before routing, set amdy_bridge_target, amdy_voicemail_extension, and amdy_voicemail_context on the channel. If HUMAN fires with no bridge target set, the call hangs up with INCOMPATIBLE_DESTINATION.

What channel variables does the Lua driver set?

What are the common problems and their fixes?

Frequently asked questions

Support

Need help? Email [email protected] with your FreeSWITCH version (fs_cli -x "version") and the output of the check script.

Not an AMDY customer yet? Sign up at app.amdy.io to get your API key and start detecting.