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
- One
startevent 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.
- A
mediaevent 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.
dtmfwhen the caller presses a key:{"event":"dtmf","dtmf":{"digit":"5","streamId":"..."}}playedStreamwhen 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.