> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime

> Stream text in and audio out over a WebSocket with Plivo Text-to-Speech, with multiple replies per connection.

> [!NOTE]
>
> The realtime WebSocket: the messages you send (text, flush, cancel), the audio and events you receive, and close codes.

Realtime generates speech over a WebSocket. Send text as it's written, get audio frames back. One socket carries up to 8 replies. For a complete file in one request, use [Batch](https://plivo.com/docs/models/text-to-speech/api/batch.md).

***

## Open a Stream

Open a WebSocket. Send `Authorization: Basic base64(<auth_id>:<auth_token>)` on the upgrade request.

```text theme={null}
wss://api.plivo.com/v1/Account/{auth_id}/TTS/Realtime/
```

### Arguments

No query parameters: one returns `422 invalid_request` naming it, and the socket doesn't open. Options go in the first `text` message of each reply.

A plain `GET` on this URL, without a WebSocket upgrade, returns `426` with an `Upgrade: websocket` header.

```bash wscat theme={null}
wscat -c "wss://api.plivo.com/v1/Account/<auth_id>/TTS/Realtime/" \
  -H "Authorization: Basic $(printf '<auth_id>:<auth_token>' | base64)"
> {"type":"text","context_id":"c1","voice_id":"<voice_id>","text":"Hello from Plivo","finish":true}
```

***

## Messages you send

All client messages are JSON text frames, up to 64 KiB.

### text

```json theme={null}
{"type": "text", "context_id": "c1", "voice_id": "<voice_id>", "text": "Hello from Plivo", "finish": true}
```

**type** `string` *required*

`text`

**context\_id** `string` *required*

Your ID for this reply. A new ID opens a new reply (max 8 open per socket). Each ID can be used once per connection: opening a reply with an ID already used on the socket returns an `error` event with `invalid_request` and `param: context_id`. Frames sent for a reply that has ended are ignored.

**text** `string` *required*

Text to add to the reply. Up to 5,000 characters per message.

**finish** `boolean` (default: false)

`true` on the last text of the reply.

**voice\_id** `string`

Required on the first message of a context.

**timestamps** `boolean` (default: false)

Send `timestamps` events with character timings.

The first message of a context also accepts every [batch](https://plivo.com/docs/models/text-to-speech/api/batch.md) option: `language`, `output_format`, `pace`, `volume`, `pronunciations`, `lexicon_id`, `continuation`, `seed`.

Options are fixed when the reply opens. Later `text` messages for the same context take only `type`, `context_id`, `text` and `finish`. Any other field, such as `voice_id` or `pace`, returns an `error` event with `invalid_request` and `param` naming the field.

### flush

```json theme={null}
{"type": "flush", "context_id": "c1", "flush_id": "f1"}
```

Speak all text received so far for `c1`, including a sentence that hasn't ended yet. The reply stays open for more text.

**context\_id** `string` *required*

The reply to flush. A `context_id` that isn't open returns an `error` event with `invalid_request`.

**flush\_id** `string`

Your ID for this flush. When you send one, you get a `flush_done` event with the same `flush_id`. Without it, no `flush_done` is sent.

### cancel

```json theme={null}
{"type": "cancel", "context_id": "c1"}
```

Stop `c1` at once. Leave out `context_id` to cancel every open reply. Each canceled reply ends with a `done` event whose `reason` is `cancelled`. A `context_id` that isn't open is ignored.

***

## Messages you receive

### Audio (binary)

```text theme={null}
[2 bytes: context_id length, little-endian][context_id][audio bytes]
```

Audio is in the `output_format` of that context.

### timestamps

Sent when `timestamps` is on, once per sentence.

```json theme={null}
{
  "type": "timestamps",
  "context_id": "c1",
  "chars": ["H", "e", "l", "l", "o", " ", "f", "r", "o", "m", " ", "P", "l", "i", "v", "o", "."],
  "start_ms": [0, 0, 0, 0, 0, 79, 79, 79, 79, 79, 157, 157, 157, 236, 314, 314, 393],
  "duration_ms": [0, 0, 0, 0, 79, 0, 0, 0, 0, 78, 0, 0, 79, 78, 0, 79, 708]
}
```

**chars** `array`

The characters of the text, one per entry, including spaces and punctuation.

**start\_ms** `array`

When each character starts, in milliseconds from the start of the reply's audio. Times keep counting across events: the next sentence's first character starts where this one ends.

**duration\_ms** `array`

How long each character lasts, in milliseconds. Several characters can share one start time with a duration of `0`.

### flush\_done

Sent after a `flush` that carried a `flush_id`, once the text up to that flush has been generated.

```json theme={null}
{"type": "flush_done", "context_id": "c1", "flush_id": "f1"}
```

### done

Sent once per reply when it ends: after its last audio frame, or when you cancel it.

```json theme={null}
{
  "type": "done",
  "context_id": "c1",
  "reason": "complete",
  "continued": false,
  "normalized_text": "नमस्ते, Plivo में आपका स्वागत है।",
  "characters": 33,
  "spoken_chars": 33,
  "audio_seconds": 2.08,
  "ttfb_ms": 20,
  "connection_id": "148d6af0bee98c09"
}
```

**reason** `string`

`complete` when the reply was spoken in full, or `cancelled` after a `cancel`.

**normalized\_text** `string`

The text as spoken. For a canceled reply, only the part spoken before the cancel.

**characters** `integer`

Billed characters: all the text the reply received, including text not spoken because of a cancel.

**spoken\_chars** `integer`

Characters spoken before the reply ended. Lower than `characters` when you cancel.

**audio\_seconds** `number`

Seconds of audio sent for the reply.

### warning

A non-fatal problem.&#x20;

### error

```json theme={null}
{"type": "error", "code": "...", "message": "...", "param": "...", "context_id": "...", "connection_id": "..."}
```

An `error` event doesn't close the socket. It affects only the reply named in `context_id`, and other replies keep playing. `context_id` is left out when the error isn't about one reply, for example a frame that isn't a JSON object or an unknown `type`. See [Errors](https://plivo.com/docs/models/text-to-speech/troubleshooting/errors.md) for codes.

***

## Close codes

| Code | When |
| - | - |
| 1013 | Retryable error. Reconnect. |
| 1011 | Server (5xx) error |
| 1008 | Other errors |

A client that stops reading for 30 s is dropped.
