VonyxDocs

Telephony mode

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

View this page as Markdown

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.

CarrierWhere to put the URLURL form
ExotelVoicebot applet URLPath form (Exotel drops query strings)
Twilio<Connect><Stream url="...">Path form (Twilio stream URLs take no query string)
Plivo<Stream> URL, bidirectionalQuery 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.
{"event":"start","start":{"streamId":"...","callId":"...","accountId":"...","from":"...","to":"...","customParameters":{},"carrier":"exotel","mediaFormat":{"encoding":"audio/x-l16","sampleRate":8000}}}
  1. 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.
{"event":"media","media":{"chunk":1,"contentType":"audio/x-l16","payload":"<base64>"}}
  1. dtmf when the caller presses a key: {"event":"dtmf","dtmf":{"digit":"5","streamId":"..."}}
  2. 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 ownWhat happens
{"event":"playAudio","media":{"contentType":"audio/x-l16","sampleRate":8000,"payload":"<base64>"}}mediaPlays audio to the caller. audio/x-mulaw is also accepted.
{"event":"clearAudio"}clearDrops audio that hasn't played yet (barge-in).
{"event":"checkpoint","name":"turn-3"}markComes back as playedStream once the audio before it has played.
{"event":"hangup"}close your socketEnds 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.

On this page