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

# Voice

> Open a real-time voice conversation over WebSocket.

Real-time voice provides a low-latency spoken interface to the grounded AutoSage runtime. Unlike the versioned REST API, voice is served directly at the API root under `/voice`.

## Endpoints

| Protocol  | Path              | Description                     | Auth      |
| --------- | ----------------- | ------------------------------- | --------- |
| WebSocket | `/voice/realtime` | Start a real-time voice session | \[User]   |
| `GET`     | `/voice/health`   | Check voice service readiness   | \[Public] |

## Open a real-time session

Connect to:

```text theme={null}
wss://api.autosage.ai/voice/realtime?kbId=KB_ID
```

<ParamField query="kbId" type="string" required>
  Knowledge base used for grounded voice responses.
</ParamField>

<ParamField query="token" type="string">
  Signed-in user session token when a session cookie cannot be sent during the WebSocket handshake.
</ParamField>

The handshake must authenticate a signed-in user, either through the normal session headers/cookie or the `token` query parameter. AutoSage verifies that the user can access the knowledge base and that the tenant has credits before starting the session.

<Warning>
  `token` is a user session token, not an `sk_...` API key. Do not place long-lived credentials in browser-visible URLs or logs.
</Warning>

Once connected, the socket carries bidirectional audio and transcript events. The runtime can ground responses in the selected knowledge base and its configured data connections. When the socket closes, AutoSage saves the user and assistant transcript as a chat and records session usage.

Common server message types include `connected`, `speech_started`, `speech_stopped`, `audio`, `audio_done`, `assistant_transcript`, `user_transcript`, `response_done`, and `error`. The detailed audio payload and client-message protocol can evolve independently of the REST schemas.

<Info>
  For production protocol details, contact the AutoSage team and consult the API explorer at `/swagger`. Build clients to ignore unknown message types so additive protocol updates remain compatible.
</Info>

## Check readiness

`GET /voice/health`

```bash theme={null}
curl "https://api.autosage.ai/voice/health"
```

Returns `ready` when the voice service is configured or `not_configured` otherwise.

## Next steps

<CardGroup cols={2}>
  <Card title="Chat lifecycle" icon="comments" href="/developers/lifecycles/chat-lifecycle">
    Understand how grounded conversation state is persisted.
  </Card>

  <Card title="Knowledge bases" icon="database" href="/knowledge-bases/overview">
    Prepare the content that grounds voice sessions.
  </Card>
</CardGroup>