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

# WebSockets

> Define the authorization, event contract, reconnect behavior, and operational checks required for a future WebSocket integration.

A WebSocket integration needs a published endpoint and message protocol. The current public resource API does not establish a general Threetone WebSocket conversation endpoint, event stream, or supported client package.

<Note>
  Do not derive a socket URL by replacing `https` with `wss` on an API route. A signed-URL or token operation in the reference does not establish a WebSocket protocol, and conversation execution remains gated by [current availability](/agents-platform/overview#current-availability).
</Note>

## Specify the integration before connecting

| Contract | Questions the release must answer |
| - | - |
| Access | How is session access issued, scoped, refreshed, and revoked? |
| Handshake | Which endpoint, protocol version, and authentication mechanism are supported? |
| Messages | Which event types, schemas, ordering rules, and payload limits apply? |
| Delivery | Are acknowledgments, retries, duplicate detection, or resumable cursors supported? |
| Lifecycle | What do close codes, heartbeat failures, idle timeouts, and session expiry mean? |
| Audio | Which encoding, sample rate, frame size, and interruption behavior are accepted? |

Keep workspace credentials in your server's secret storage. Give the application only the access permitted by the released session contract. Avoid putting long-lived credentials in URLs, which can be retained in logs.

## Plan failure handling

<Steps>
  <Step title="Use an explicit connection state">
    Distinguish connecting, open, closing, and closed. Send only when the connection is ready, and stop accepting new work after the owning session ends.
  </Step>

  <Step title="Bound outgoing work">
    Set a queue limit and an application response to overload. The standard [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) has no automatic backpressure; a growing buffer needs deliberate handling.
  </Step>

  <Step title="Treat reconnect as a protocol decision">
    Retry transient failures with a bounded delay only when the released protocol permits it. Do not replay tool actions, user messages, or audio unless the protocol defines safe replay or deduplication.
  </Step>
</Steps>

Before release, test malformed messages, expired access, duplicate events, slow consumers, abrupt disconnects, and cleanup. Record identifiers and error codes without logging access tokens or full customer payloads.

Use [server deployment](/agents-platform/deploy/server/overview) for supported resource requests and [client events](/agents-platform/advanced/events/overview) for the separate event-contract boundaries.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can the live conversation count endpoint stream messages?" id="websockets-faq-count">No. It returns a workspace count. It is not a transcript subscription or socket endpoint.</Accordion>
  <Accordion title="Does an event name in agent configuration make it subscribable?" id="websockets-faq-events">No. Saved event preferences require a released producer, transport, and authorization contract before a client can subscribe.</Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.