Docs / API quickstart
AMDY AMD API Quickstart & Authentication
The AMDY answering machine detection API streams live call audio over WebSocket and returns aHUMAN / MACHINE classification in real time. This quickstart covers how to get an API key, how authentication works on the detection WebSocket and on the portal REST endpoints, and how to send your first detection call.
What is the AMDY AMD detection API?
AMDY is a hosted answering machine detection service. Your PBX or dialer opens a WebSocket to the AMDY backend, streams raw 8 kHz PCM audio from the answered call, and receives a classification for each chunk. The final response is a short string in the form CLASSIFICATION-DURATION-CONFIDENCE (for example HUMAN-4.50-0.9950).
The same backend serves every integration platform. Results feed your AMDY dashboard, CDRs, and any downstream routing you wire up on your side.
How do I get an API key?
Sign in at app.amdy.io and open Settings. Create a new key with a name and environment. The key is shown once; store it on each detection server at /etc/amdy/api-key (mode 600).
Key format:
- Every key starts with the prefix amd_live_.
- The prefix is followed by 24 hex characters for signup-minted keys or 32 hex characters for manually created keys.
- Keys are stored hashed in the api_keys table; the user_id column scopes every request to the owning client.
How does API key authentication work?
There are two auth surfaces. The detection WebSocket takes the key as a header; the portal REST API takes the key as a bearer token or header.
| Surface | How to send the key | Notes |
|---|---|---|
| Detection WebSocket | X-API-Key header on connect | FreeSWITCH mod_audio_fork cannot send custom headers; those connections are gated by IP allowlist instead |
| Portal REST API (/api/v1/*) | Authorization: Bearer amd_live_... or X-API-Key header | Unknown key returns 401; key with status != 'active' returns 401 or 403 |
The management endpoints for creating and revoking keys (/api/api-keys) use NextAuth session auth in the portal UI. There is no public key-management REST endpoint; rotate keys from the portal.
What audio format does the detection API expect?
The WebSocket accepts raw PCM with these parameters:
| Parameter | Value |
|---|---|
| Sample rate | 8000 Hz |
| Bit depth | 16-bit signed, little-endian |
| Channels | 1 (mono) |
| Container | none (raw) |
| Recommended chunk | ~1s (8000 samples, 16000 bytes) |
How do I make my first detection call?
- Open a WebSocket to ws://api.amdy.io:2700 with header X-API-Key: amd_live_....
- Send the config frame as a text message:
{"config": {"sample_rate": 8000, "VID": "<your call identifier>"}}VID is the caller ID name from your PBX. If empty, AMDY records it as Unknown. - Stream raw PCM as binary frames. Send at roughly 1-second intervals.
- After each binary frame, read the server reply. A non-empty reply containing HUMAN, AMD, or MACHINE is the final classification.
- To force a final result, send a text frame {"eof": 1} when audio ends.
The canonical result string is CLASSIFICATION-DURATION-CONFIDENCE, for example HUMAN-4.50-0.9950 or AMD-2.10-0.8700. Split on - to extract the three fields.
What portal REST endpoints are available?
In addition to the detection WebSocket, AMDY exposes REST endpoints under /api/v1/ for managing your account from your own automation. All four require API key auth.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/ips/register | Register this server's IP and activate the account |
| GET | /api/v1/config | Read detection sensitivity and max detection time |
| GET | /api/v1/client-settings | Read per-IP detection settings (rate-limited 20/min) |
| GET | /api/v1/ips | List IPs owned by this client, with their settings (rate-limited 20/min) |
The public, unauthenticated endpoint /api/health returns platform-wide stats (7-day detections, human percentage, p95 latency) and is used by the landing page. It does not return per-client data.
What happens if detection fails mid-call?
The installed detection script (amd.py) maps errors to channel variables so your dialplan can decide. On any error the script defaults to treating the call as HUMAN for safety:
| AMDSTATUS | AMDCAUSE | Meaning |
|---|---|---|
| HUMAN | HUMAN | Live person detected |
| MACHINE | MACHINE | Answering machine / voicemail |
| HANGUP | NO_AUDIO / AUDIO_TIMEOUT / NO_AUDIO_TIMEOUT | No audio received within the timeout window |
| NOTSURE | CONNECTION_ERROR / PROCESSING_ERROR / FATAL_ERROR | Backend error; script defaults to HUMAN for call safety |
Frequently asked questions
Is there a TLS (wss://) endpoint for the detection WebSocket?
The current documented endpoint is ws://api.amdy.io:2700 (plain WebSocket, port 2700). Contact [email protected] if your environment requires a TLS-wrapped endpoint for integration.
Can I use my own PBX without the install scripts?
Yes. Any client that can open a WebSocket to ws://api.amdy.io:2700, send the header and config frame, and stream 8 kHz 16-bit mono raw PCM will work. The install scripts handle IP registration and key storage; you can perform those steps manually.
Does FreeSWITCH use the same API key header?
No. mod_audio_fork cannot set custom headers on the WebSocket upgrade. FreeSWITCH connections are authorized by IP allowlist instead. The API key is still used for the one-time registration call (POST /api/v1/ips/register) and is stored at /etc/amdy/api-key.
Issabel support?
Issabel is not documented in the AMDY install materials. Contact [email protected] for integration access; the generic Asterisk installer may apply.
Next steps
- Install on your platform: FreeSWITCH, Asterisk, ViciDial.
- Read the full endpoint reference at API reference.
- Manage keys and view results at app.amdy.io.
Support: [email protected]