# Enhancer API

Remove background noise from the caller's voice before it reaches your voice bot.

The Enhancer API removes background noise from the caller's voice in real time. You send the call audio to one Vonyx WebSocket; the clean voice arrives at a WebSocket your bot runs, called the **redirect URL**.

There are two ways to connect:

- **[Telephony mode](/docs/enhancer-api/telephony)** (two-way). Point your carrier's media stream (Exotel, Twilio or Plivo) at the Enhancer. The caller's voice reaches your bot clean; your bot's replies go back to the caller unchanged.
- **[Native mode](/docs/enhancer-api/native)** (one-way). Your own server streams raw audio frames, and the clean frames arrive at your redirect URL.

Only the caller's audio is cleaned. Your bot's voice is never processed.

## Before you start

| You need | Notes |
| --- | --- |
| **API key** | Create it in the console under **Enhancer API**. It is shown once; we keep only a fingerprint of it. Keep it on your server. Every connection is checked against it and billed to your wallet. |
| **Wallet credit** | A call is refused when your wallet is empty. A call already running is never cut. |
| **Redirect URL** | A `wss://` WebSocket server your bot runs. It must be reachable from the internet and accept the connection within 10 seconds. |

If your key leaks, choose **Replace key** in the console. The old key stops working straight away.

The endpoint is `wss://fery.vonyx.si/denoise`, one WebSocket per call.

## Connection URL

Every connection carries your API key and your redirect URL. The console's **Connection URL** box builds it for you.

**Query form** (default):

```text
wss://fery.vonyx.si/denoise?api_key=<API_KEY>&redirect=<URL-encoded redirect>
```

URL-encode the redirect: `wss://bot.example.com/ws?lang=hi` becomes `wss%3A%2F%2Fbot.example.com%2Fws%3Flang%3Dhi`.

**Path form**, for carriers that drop the query string (Exotel and Twilio):

```text
wss://fery.vonyx.si/denoise/<API_KEY>/<base64url redirect>
```

Encode the redirect as base64url without padding:

```python
import base64
redirect = "wss://bot.example.com/ws?lang=hi"
encoded = base64.urlsafe_b64encode(redirect.encode()).decode().rstrip("=")
url = f"wss://fery.vonyx.si/denoise/{API_KEY}/{encoded}"
```

## Audio options

Audio is mono, 16-bit signed PCM. The defaults fit phone calls, so most integrations change nothing. You can set these as URL query parameters:

| Setting | URL parameter | Default | Values |
| --- | --- | --- | --- |
| Sample rate | `sample_rate` | 8000 | 8000, 16000 and 24000 Hz are tested |
| Frame length | `chunk` or `frame_duration` | 20 ms | Use 20. Other values are untested. |
| Suppression | `denoise` or `suppression_level` | 100 | 0 to 100. Lower keeps more background sound. |

Samples per frame = sample rate × frame length ÷ 1000: 160 at 8 kHz, 320 at 16 kHz, 480 at 24 kHz.

## Go-live checklist

- API key created and stored on your server only
- Wallet topped up
- Redirect URL is public, uses `wss://`, and accepts a connection within 10 seconds
- Path form for Exotel and Twilio
- Bot handles `start`, `media`, `dtmf` and `playedStream`
- Bot sends audio at the call's sample rate, in messages under 32 KB
- Test call made, and the caller's voice reaches the bot clean
- Your peak concurrent calls shared with us
- A fallback that connects your carrier straight to your bot if a call is refused
