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.

Realtime is sold by LIVE rooms held at once: your plan sets how many the workspace can hold at once (1 on Free, up to 3,000 on Agency), and streaming spends no credits. A creator you stay subscribed to can keep one of those rooms while you wait for them to go live, so unsubscribe from the ones you no longer need.

Plans, the price per room and the full event list: TikTok LIVE WebSocket API.

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. None of them spends credits:

When the workspace already holds as many rooms as its plan allows, a new subscription gets unavailable with the reason plan_cap_reached. Unsubscribe from a creator you no longer need, or move to a larger plan, then subscribe again. The reason creator_resolve_failed means the creator's live room could not be looked up on TikTok for 10 minutes: unsubscribe and subscribe again to retry.

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, 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" }
    }
  }
}

Event-type reference

These are every event the gateway emits — 15 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,
  "isCompleted": true,
  "fanTicketCount": 0,
  "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
}

{
  "subMonth": 3,
  "subscribeType": 1,
  "user": { "uniqueId": "loyal_fan", "nickname": "Loyal Fan" }
}

{
  "battleType": 1,
  "participants": [
    { "user": { "uniqueId": "hostA", "nickname": "Host A" } },
    { "user": { "uniqueId": "hostB", "nickname": "Host B" } }
  ]
}

{
  "battleId": "7700872369384409908",
  "battleStatus": 1,
  "battleType": 2,
  "teams": [],
  "teamArmies": [
    { "teamId": "1", "points": 2200, "hosts": [ { "userId": "111", "points": 1200 }, { "userId": "333", "points": 1000 } ] },
    { "teamId": "2", "points": 980, "hosts": [ { "userId": "222", "points": 980 }, { "userId": "444", "points": 0 } ] }
  ]
}

{
  "type": "hourly",
  "label": "No. 3",
  "rankId": "3",
  "colour": "#FFB300"
}

{
  "startedAt": "2026-08-05T10:00:00.000Z"
}

// 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 "@toktikhq/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.isCompleted) 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();