Realtime

The model

You open one socket and subscribe to one or more creators over it. Because any creator can be requested, a subscription is not instant: we must admit the room and have a worker own it before events flow. You are told exactly where each subscription stands through status frames — queued then active, or offline when the creator is not live. Drive your UI off those statuses, not off event volume.

Metering is truthful: only an active subscription owns a room and bills room-minute credits. queued, unavailable and offline are free — you never pay to wait.

Handshake

Mint a short-lived token over REST, then open the socket carrying that token in the Authorization header or the Sec-WebSocket-Protocol subprotocol — never in the URL (query strings leak into logs). The token expires quickly; the SDKs mint and refresh it for you across reconnects.

{ "token": "<jwt>", "tokenType": "Bearer", "expiresIn": 60, "wsUrl": "wss://…/v1/live/stream" }

Then send commands as JSON frames:

Subscription lifecycle

Every status frame carries one of these. Only active is billed:

When the workspace runs out of credits a subscription cannot stay active — you get a 402-class close/status and the room is released. Top up and re-subscribe.

Server frames

Four frame types arrive on the socket. Branch on type first:

A rejected command comes back as an error frame with a stable code:

The event frame

Every LIVE event shares one envelope: type: "event", the event name, an eventId, creatorId, roomId, a monotonic sequence, roomState, a provenance block, and the decoded body under data.decoded. Sequence increases per room but is not a gap-free guarantee — treat events as a stream, not a ledger, and make client handling idempotent.

{
  "type": "event",
  "event": "gift",
  "eventId": "01JQ8Z6M9C7K2R…",
  "creatorId": "@creator_handle",
  "roomId": "7451234567890123456",
  "sequence": 128,
  "roomState": "active",
  "data": {
    "messageType": "WebcastGiftMessage",
    "decoded": {
      "gift": { "giftName": "Rose", "diamondCount": 1 },
      "repeatCount": 5,
      "repeatEnd": true,
      "user": { "uniqueId": "whale_01", "nickname": "Top Fan" }
    }
  },
  "provenance": {
    "observedAt": "2026-07-24T04:12:33.481Z",
    "freshness": "near_realtime",
    "source": "platform_observed_live_stream",
    "coverageStatus": "observed",
    "methodologyVersion": "realtime-v1"
  }
}

Event-type reference

These are every event the gateway emits — 10 types, no more. We do not advertise events we do not actually produce. Fields below are on data.decoded.

{
  "comment": "let's go 🔥",
  "user": { "uniqueId": "guest_842", "nickname": "Guest", "verified": false }
}

{
  "gift": { "giftName": "Rose", "diamondCount": 1, "giftType": 1 },
  "repeatCount": 5,
  "repeatEnd": true,
  "user": { "uniqueId": "whale_01", "nickname": "Top Fan" }
}

{
  "action": 1,
  "memberCount": 3120,
  "user": { "uniqueId": "new_viewer" }
}

{
  "likeCount": 15,
  "totalLikeCount": 998240,
  "user": { "uniqueId": "fan_77" }
}

{
  "socialType": "follow",
  "followCount": 412,
  "user": { "uniqueId": "loyal_viewer" }
}

{
  "viewerCount": 2841,
  "totalUser": 51230,
  "topViewers": [
    { "rank": 1, "coinCount": 12040, "user": { "uniqueId": "whale_01" } }
  ]
}

{
  "action": "STREAM_ENDED",
  "isStreamEnd": true,
  "tips": ""
}

{
  "display": 1,
  "envelopeInfo": { "diamondCount": 999, "peopleCount": 200, "unpackAt": 1769200000, "sendUserName": "host" }
}

{
  "goodyBagId": "gb_88",
  "diamondCount": 500,
  "countDownMinutes": 5,
  "joinedHeadcount": 140
}

// no data.decoded — inspect the raw fields:
// data.messageType, data.msgId, data.decodeError

Backpressure & reconnect

Each socket has a bounded send queue. If your client falls behind, high-volume lossy frames — like, member, roomUser, unknown — may be dropped to keep up; critical overflow closes only that socket with code 1013. Never assume you saw every like. Reconnect with exponential backoff and re-subscribe (the SDKs replay your subscriptions automatically); treat gaps as normal and keep your handlers idempotent.

Connect

The SDKs own the token lifetime, reconnection and resume. Raw is there if you drive the socket yourself:

import { TokTikClient } from "@toktik/sdk-js";

const client = new TokTikClient({ apiKey: process.env.TOKTIK_API_KEY! });

const stream = await client.live.stream(["@creator_handle"], {
  onStatus: (s) => console.log("status", s.creatorId, s.status),   // queued → active
  onEvent: (frame) => {
    if (frame.event === "gift") {
      const g = frame.data.decoded;
      if (g.repeatEnd) console.log(g.gift?.giftName, (g.gift?.diamondCount ?? 0) * g.repeatCount);
    }
  },
  onError: (e) => console.error(e),
  onReconnect: (attempt) => console.warn("reconnected", attempt)
});

// later: await stream.close();