# Events reference

Messages flow both ways over the connection as JSON on the text channel. Audio is
base64 inside those messages. This is the OpenAI Realtime event subset.

## You send

| Event | What it's for |
|---|---|
| `session.update` | Set instructions, voice, and tools (at the start). |
| `input_audio_buffer.append` | Send a piece of the user's voice (base64 PCM16). |
| `input_audio_buffer.commit` | Optional — mark the end of the user's turn (Simple mode). |
| `input_audio_buffer.clear` | Optional — discard buffered audio (Simple mode). |
| `response.create` | Optional — ask for a reply now (Simple mode). |
| `response.cancel` | Stop the current reply (interrupt). |
| `conversation.item.create` | Send back the result of a tool it called. |

> Turn-taking is **automatic in both modes** — you just stream audio. The three
> "optional" events above are best-effort nudges; Premium uses automatic turn
> detection and ignores them.

## You receive

| Event | What it means |
|---|---|
| `session.created` | The session is ready (sent on connect). |
| `session.updated` | Your settings were applied. |
| `input_audio_buffer.speech_started` | The user started speaking. |
| `input_audio_buffer.speech_stopped` | The user stopped speaking. |
| `conversation.item.input_audio_transcription.completed` | The transcript of what the **user** said — see [Transcripts](transcripts.html). |
| `conversation.item.created` | A turn item was added (the user's turn, or a tool result). |
| `response.created` | A reply started. |
| `response.output_audio.delta` | A piece of Malayalam audio to play — the main payload. |
| `response.output_audio_transcript.delta` | The text of what **swaram** is saying — see [Transcripts](transcripts.html). |
| `response.function_call_arguments.done` | It wants to call one of your [tools](tools.html). |
| `response.done` | The reply finished. |
| `error` | Something went wrong — see [Errors](errors.html). |

## Close codes

When the server closes the connection, the WebSocket close code tells you why:

| Code | Meaning |
|---|---|
| `4001` | Invalid or missing API key. |
| `4003` | Out of credits — add credits to continue. |
| `4008` | Too many concurrent connections for your plan. |
| `1013` | Server busy — reconnect shortly. |

See [Errors](errors.html) for how to handle these gracefully.