Skip to main content
How to stream speech for a voice agent: send text in pieces, run up to 8 replies on one socket, flush to speak now, and cancel when the caller interrupts.

Contexts: one reply each

A context is one spoken reply, named by your context_id.
  • The first text message with a new context_id opens the reply. It sets the voice and options for that reply.
  • Later text messages with the same context_id add more text. Send "finish": true on the last one.
  • One socket can hold up to 8 open contexts. Reuse the socket across turns instead of reconnecting.
  • Each context ends with one done event that reports the billed characters.
  • Use a new context_id for every reply. Reusing one on the same socket returns an error event (invalid_request, param: context_id).

Sending text as your LLM writes it

Send text in pieces as it arrives. Plivo speaks each sentence as soon as it ends, and holds a sentence that hasn’t ended yet. Plivo speaks the held text when the sentence ends, or when you send flush or "finish": true. For example, "Your order ships" on its own produces no audio. "Your order ships tomorrow. It will" produces audio for the first sentence right away.

Flush: speak what you have now

Generates audio for all text sent so far in c1, including an unfinished sentence, without closing it. Add a flush_id to get a flush_done event when it’s done.

Cancel: handle barge-in

Stops generating c1 at once. Use it when the caller interrupts. A cancel with no context_id cancels every reply on the socket. Each canceled reply still ends with a done event, with reason: "cancelled". characters counts all the text the reply received, and spoken_chars counts the part spoken before the cancel.

Audio frames

Audio comes as binary frames tagged with their context:
Strip the header and route the audio to the right reply.