TikTok LIVE events, over one WebSocket

A read-only WebSocket tap on your own TikTok LIVE room. BetterTok already connects to TikTok, decodes the stream and cleans up the messy parts — inconsistent field names, partial gift combos, missing role flags. The Developer API hands you the result so you can build a bot, a game, an overlay or an analytics pipeline without touching TikTok's protocol yourself. One note on gifts: a combo arrives once, when it ends; a combo that stops without an end frame arrives after ~15 s idle, and if the end frame shows up later it adds only the remainder (nothing at all when the combo did not grow) — sum gift_count per viewer and gift.

• One socket, 15 event types. No polling, no webhooks to host.
• Stable JSON. Every event uses the same envelope and snake_case field names.
• Roles included. Follower, subscriber, moderator, fan club and gifter rank arrive on the event — no second lookup.
• Free locally. The desktop app serves the same events on ws://127.0.0.1:21213 with no key — see local mode.

1. 1

   Get a key

   Open the Developer API page in your dashboard and create one. Keys look like btk_live_… and are shown once — store it like a password. The hosted stream needs a Creator plan and a linked TikTok account.

2. 2

   Open the socket

   Connect to wss://api.bettertok.app/api/v1/developer/stream with your key in the Authorization header. You'll get a connected frame back.

3. 3

   Read events

   Go live on TikTok. Every event arrives as one JSON frame. Switch on type and read data.

Two forms. Both carry the same key.

# Servers, CLIs, anything that can set headers:
Authorization: Bearer btk_live_<your key>

# Browsers — the WebSocket API can't set headers:
wss://api.bettertok.app/api/v1/developer/stream?access_token=btk_live_<your key>

Keys can be rotated or revoked from the dashboard. A revoked key kills its live connections within about 30 seconds.

Every event frame has the same outer shape:

{ v, id, correlation_id, user_id, session_id, type, room_id, received_at, normalized_at, data }

A real gift event:

{
  "v": 1,
  "id": "evt_9f1c0f7a-6b1e-4c22-9f0e-2a5b1d3e4f60",
  "correlation_id": "7412998877665544332",
  "user_id": "usr_01HZX9Q2",
  "session_id": "7412998877665544000",
  "type": "gift",
  "room_id": "7412998877665544000",
  "received_at": "2026-07-28T18:04:11.220Z",
  "normalized_at": "2026-07-28T18:04:11.244Z",
  "data": {
    "username": "yourhandle",
    "viewer_id": "6829471055",
    "viewer_username": "someviewer",
    "display_name": "Some Viewer",
    "profile_picture": "https://p16-sign.tiktokcdn.com/...",
    "is_follower": true,
    "is_subscriber": false,
    "is_moderator": false,
    "is_fan_club_member": true,
    "is_gifter": true,
    "top_gifter_rank": 3,
    "gifter_level": 12,
    "fan_club_level": 4,
    "subscriber_level": 0,
    "follow_role": 1,
    "gift_id": 5655,
    "gift_name": "Rose",
    "gift_count": 10,
    "gift_value": 1,
    "gift_total_value": 10,
    "gift_image_url": "https://p19-webcast.tiktokcdn.com/..."
  }
}

These are all of them. Types are stable; new fields may be added inside data, so ignore keys you don't recognise. Fields marked ? are absent when TikTok didn't send a value.

Identity fields

Sent inside data on every event that has a viewer behind it. Listed once here rather than repeated below.

You → server

Optional. If you never send anything you receive every event type.

// Narrow to the types you want. Unknown types are ignored.
{ "type": "subscribe", "events": ["gift", "comment"] }

// No "events" key = all 15 types.
{ "type": "subscribe" }

// Round-trip check. Replies { "type": "pong" }.
{ "type": "ping" }

Server → you

// First frame after a successful auth.
{ "type": "connected", "username": "yourhandle", "events": [ ...all 15 types ] }

// Confirms a subscribe, echoing what you'll actually receive.
{ "type": "subscribed", "events": ["gift", "comment"] }

// Reply to your ping.
{ "type": "pong" }

// Something went wrong; the socket closes right after.
{ "type": "error", "code": "UNAUTHORIZED", "message": "Invalid or missing API key." }

// Anything else is an event envelope — see above.
{ "v": 1, "type": "gift", "data": { ... } }

Unknown control frames are ignored in both directions, so new frame types won't break an existing client.

Errors arrive in-band as { "type": "error", "code", "message" }, then the socket closes.

If you exceed the handshake rate the upgrade is refused with an HTTP 429 before any WebSocket exists — there is no error frame in that case.

Reconnect with backoff on close. Don't retry in a tight loop after UNAUTHORIZED or TIER_REQUIRED: those need a human to fix the key or the plan.

Events themselves are never rate limited — only the frames you send. A busy room streams as fast as TikTok delivers.

The BetterTok desktop app serves live events from your own machine at ws://127.0.0.1:21213. No API key, no plan, no internet round trip — build and test against it for free, then point at the cloud endpoint when you ship.

The frame shape is deliberately TikFinity-compatible, so tools written for TikFinity's local socket work unchanged. That also means it is not the normalized cloud format documented above:

{ "event": "gift", "data": { ...raw camelCase fields, TikFinity-shaped } }

• event uses TikFinity's names, not the cloud type names — chat (not comment), member (not join), subscribe (not superfan), roomUser (not viewer_count). There is no local equivalent of shop_purchase or stream_start.
• data is the raw internal payload in camelCase (nickname, giftName, uniqueId) — not the snake_case fields documented above, and with no outer envelope, so no v, id or timestamps.
• data.username is the sender's handle here — in the cloud envelope the same key means the creator's handle. This is the one difference that will not show up as undefined.
• Bound to loopback (127.0.0.1) — nothing on your network can reach it, and there is no firewall prompt. It is on by default and starts with the desktop app; turn it off in the desktop app's settings if you don't want it running.
• It is unauthenticated by design, for drop-in TikFinity compatibility. Any software running on the same machine — including a page open in your browser — can connect to it and read your live event feed. Turn Local Mode off if that is not what you want.
• Port 21213 is the default, but if it is already taken (TikFinity itself uses it) the app walks up to 21222 — check the desktop app for the live port before hardcoding it.
• Use the cloud endpoint instead when you need de-duplication ids, correlation ids or a server that isn't the streamer's PC.

// Desktop app running, no key needed.
// NOTE: local mode speaks TikFinity's wire format, NOT the cloud envelope —
// raw camelCase fields, and TikFinity's event names (chat/member/subscribe).
const ws = new WebSocket("ws://127.0.0.1:21213");

ws.onmessage = (e) => {
  const { event, data } = JSON.parse(e.data);
  if (event === "gift") {
    console.log(data.nickname, "sent", data.giftName);
  }
};

Node.js

// npm i ws
import WebSocket from "ws";

const ws = new WebSocket("wss://api.bettertok.app/api/v1/developer/stream", {
  headers: { Authorization: `Bearer ${process.env.BETTERTOK_API_KEY}` },
});

ws.on("open", () => {
  // Optional. Omit this entirely and you get all 15 types.
  ws.send(JSON.stringify({ type: "subscribe", events: ["gift", "comment"] }));
});

ws.on("message", (raw) => {
  const evt = JSON.parse(raw.toString());

  if (evt.type === "error") return console.error(evt.code, evt.message);
  if (evt.type === "connected") return console.log("streaming @" + evt.username);

  if (evt.type === "gift") {
    const d = evt.data;
    console.log(`${d.display_name} sent ${d.gift_count}x ${d.gift_name} — ${d.gift_total_value} diamonds`);
  }
  if (evt.type === "comment") {
    console.log(`${evt.data.display_name}: ${evt.data.comment}`);
  }
});

Python

# pip install websockets
import asyncio, json, os, websockets

URL = "wss://api.bettertok.app/api/v1/developer/stream"
HEADERS = {"Authorization": f"Bearer {os.environ['BETTERTOK_API_KEY']}"}

async def main():
    async with websockets.connect(URL, additional_headers=HEADERS) as ws:
        # Optional. Omit this entirely and you get all 15 types.
        await ws.send(json.dumps({"type": "subscribe", "events": ["gift", "comment"]}))

        async for raw in ws:
            evt = json.loads(raw)

            if evt["type"] == "error":
                print("error:", evt["code"], evt["message"])
                break
            if evt["type"] == "gift":
                d = evt["data"]
                print(d["display_name"], "sent", d["gift_count"], "x", d["gift_name"])
            elif evt["type"] == "comment":
                print(f"{evt['data']['display_name']}: {evt['data']['comment']}")

asyncio.run(main())

Browser

// A browser can't set headers on a WebSocket, so the key goes on the URL.
// Only do this in a page you control — anyone who opens devtools sees the key.
const ws = new WebSocket(
  "wss://api.bettertok.app/api/v1/developer/stream?access_token=" + encodeURIComponent(API_KEY)
);

ws.onmessage = (e) => {
  const evt = JSON.parse(e.data);
  console.log(evt.type, evt.data);
};