# Telephony mode

Put the Enhancer between your carrier (Exotel, Twilio, Plivo) and your bot.

Put the Enhancer URL where your carrier asks for the stream or voicebot URL. It works out which carrier is calling from the first message, and your bot always gets the same Plivo-style protocol, whatever the carrier.

| Carrier | Where to put the URL | URL form |
| --- | --- | --- |
| Exotel | Voicebot applet URL | Path form (Exotel drops query strings) |
| Twilio | `<Connect><Stream url="...">` | Path form (Twilio stream URLs take no query string) |
| Plivo | `<Stream>` URL, bidirectional | Query or path form |

Make a test call before you go live.

## What your bot receives

1. One `start` event with the call's details. For Exotel and Twilio it is built from the carrier's own start event; Plivo's is passed through unchanged.

```json
{"event":"start","start":{"streamId":"...","callId":"...","accountId":"...","from":"...","to":"...","customParameters":{},"carrier":"exotel","mediaFormat":{"encoding":"audio/x-l16","sampleRate":8000}}}
```

2. A `media` event every 20 ms with the caller's clean voice: base64 PCM16 little-endian, 320 bytes at 8 kHz. Twilio's μ-law is decoded for you, so you always get PCM16.

```json
{"event":"media","media":{"chunk":1,"contentType":"audio/x-l16","payload":"<base64>"}}
```

3. `dtmf` when the caller presses a key: `{"event":"dtmf","dtmf":{"digit":"5","streamId":"..."}}`
4. `playedStream` when the carrier has played your audio up to a checkpoint: `{"event":"playedStream","streamId":"...","name":"..."}`

When the caller hangs up, your redirect socket is closed.

## What your bot sends back

Reply on the same redirect socket, in either protocol.

| Plivo-style (recommended) | Carrier's own | What happens |
| --- | --- | --- |
| `{"event":"playAudio","media":{"contentType":"audio/x-l16","sampleRate":8000,"payload":"<base64>"}}` | `media` | Plays audio to the caller. `audio/x-mulaw` is also accepted. |
| `{"event":"clearAudio"}` | `clear` | Drops audio that hasn't played yet (barge-in). |
| `{"event":"checkpoint","name":"turn-3"}` | `mark` | Comes back as `playedStream` once the audio before it has played. |
| `{"event":"hangup"}` | close your socket | Ends the call after queued audio has played (up to 10 s). |

If you use the carrier's own protocol, send audio in that carrier's encoding: μ-law for Twilio, PCM16 for Exotel.

Send audio at the call's sample rate; audio at a different rate plays at the wrong speed. For Exotel, your audio is re-chunked to Exotel's rules, so any chunk size works.
