Kuldron WebSocket API

1.0.0

Kuldron streams all real-time data over a single WebSocket at /ws: live chat, viewer counts, listen-along playback sync, moderation signals, direct messages, friend activity, and your channel's event feed. Open one connection and subscribe to the topics you need. A connection receives no data until it subscribes to at least one topic.

Authenticating

Authenticate in one of two ways:

  1. Send an Authorization: Bearer <token> header on the upgrade request. If the header is present but the credential is invalid, the upgrade is rejected with HTTP 401.
  2. If you cannot set request headers, such as from a browser WebSocket, send {"op":"auth","token":"..."} as the first frame within 10 seconds of connecting. On success the server replies with {"op":"authed"}. Any other first frame, an invalid credential, or no frame within the window closes the connection.

Three credential types are accepted, and each grants access to a different set of topics:

  • A session token authenticates a signed-in user and may subscribe to chat, user, and events.
  • A guest token authenticates an anonymous viewer. It may subscribe to chat in receive-only mode and cannot send messages. It cannot subscribe to user or events.
  • An API key may subscribe to events only, and only when it carries the events:read scope. It cannot subscribe to chat or user.

Session tokens come from POST /sessions, guest tokens from the guest-watch and guest/chat-token endpoints, and API keys (with their grantable scopes) from POST /users/me/api-keys.

Topics

  • chat requires a channel id. It carries one channel's live chat and the related signals (viewer count, listen-along, moderation). Subscribing adds you to that channel's audience and counts toward its viewer total; unsubscribing removes you.
  • user carries your own direct messages and friend activity. Available to signed-in users only.
  • events carries the event feed for your own channel. Available to the channel owner with a session token, or to an API key with the events:read scope.

Delivery and recovery

Pushes on the user and events topics are best effort and may be missed during a disconnect. Every such event carries a stable id. To recover anything missed while disconnected, reconcile against the REST endpoints GET /users/me/dms and GET /users/me/events, deduplicating on id.

Keeping the connection alive

The server sends a ping every 30 seconds; reply with a pong (browsers do this automatically). Each account may hold a limited number of concurrent connections. Opening more closes the new connection with an error frame whose code is connection_limit.