Ranks Captions
Login
EVENTS REFERENCE · LIVE FIREHOSE · STREAMING NOW

The full event vocabulary of TikTok LIVE

Chat. Gifts. Likes. Joins. Follows. Battles. Subscriptions. Every event on TikTok LIVE streams through one WebSocket with rich metadata. Numbers below are the LIVE firehose right now (free public sample, refreshes every second).

Top gift right now
-
most frequent in sample window
Events per minute
0
sampled across 0 live events
Peak diamonds (single gift)
0
from region -
LIVE GIFT FIREHOSE - SAMPLED FROM THE PUBLIC ENDPOINT
Connecting to live firehose...
Waiting for first event...

Your client signs the upstream TikTok WebSocket with its own cookie so every tier receives the full real payload (real usernames, real avatars, real diamond counts). The only thing that changes between tiers is the concurrent-connection cap.

Build with TikTok LIVE data

DEVELOPER API
Real-time gifts + chat firehose
WebSocket + REST. Sandbox tier. Paid plans from $7/wk.
LEADERBOARDS
28 regions, real-time ranks
Country + league rankings. Unmasked at PRO+ / ULTRA+.
GLOBAL AGENCY
Scout creators in every region
CRM + watchlist + Telegram alerts. $119/wk.

Subscribe to the firehose in your stack

Pick your language. Copy. Run. Sandbox key from /pricing.

import { TiktokLiveClient } from '@tiktool/live'

const client = new TiktokLiveClient({
  apiKey: process.env.TIKTOOL_API_KEY,
  uniqueId: 'tiktok_handle_here',
})

client.on('gift', (e) => {
  console.log(`${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount} diamonds)`)
})

client.on('chat', (e) => console.log(`${e.user.uniqueId}: ${e.comment}`))
client.on('member', (e) => console.log(`+ join ${e.user.uniqueId}`))
client.on('like', (e) => console.log(`+ ${e.likeCount} likes`))
client.on('linkMicBattle', (e) => console.log('battle update', e.battleUsers))

await client.connect()

Every event, what fires it, what's in the payload

All events share the envelope { event: string, data: object }. Below: every event type and the data it carries.

chat Very frequent

Fired when a viewer sends a chat message. Most common event.

userObjectuniqueId, nickname, profilePictureUrl, badges
commentStringThe message text
userIdStringNumeric TikTok user ID
{
  "event": "chat",
  "data": {
    "user": {
      "uniqueId": "viewer42",
      "nickname": "Viewer 42"
    },
    "comment": "Hello!",
    "userId": "7123456789"
  }
}

gift Moderate

Fired when a viewer sends a virtual gift. Includes gift name, diamond value, streak data.

userObjectSender
giftNameStringe.g. "Rose", "Galaxy"
giftIdNumberNumeric gift ID
diamondCountNumberDiamond value
repeatCountNumberStreak count
repeatEndBooleanTrue when streak ends
{
  "event": "gift",
  "data": {
    "user": {
      "uniqueId": "big_fan"
    },
    "giftName": "Rose",
    "giftId": 5655,
    "diamondCount": 1,
    "repeatCount": 5,
    "repeatEnd": true
  }
}

like Very frequent

Fired when a viewer taps the like button. Includes total accumulated likes.

userObjectLiker
likeCountNumberThis event count
totalLikeCountNumberStream total
{
  "event": "like",
  "data": {
    "user": {
      "uniqueId": "liker1"
    },
    "likeCount": 15,
    "totalLikeCount": 12500
  }
}

member Moderate

Fired when a viewer joins the live stream room.

userObjectJoining user
{
  "event": "member",
  "data": {
    "user": {
      "uniqueId": "new_viewer",
      "nickname": "New Viewer"
    }
  }
}

follow Low

Fired when a viewer follows the streamer during the live.

userObjectFollowing user
{
  "event": "follow",
  "data": {
    "user": {
      "uniqueId": "new_follower"
    }
  }
}

share Low

Fired when a viewer shares the live stream.

userObjectSharing user
{
  "event": "share",
  "data": {
    "user": {
      "uniqueId": "sharer"
    }
  }
}

roomUserSeq Periodic

Periodic viewer count update. Primary way to track real-time viewer numbers. The SDK also emits it as viewer_count (alias, same payload).

viewerCountNumberLive viewers right now
topViewersArrayRanked by engagement
{
  "event": "roomUserSeq",
  "data": {
    "viewerCount": 1234,
    "topViewers": [
      {
        "user": {
          "uniqueId": "top_fan"
        },
        "coinCount": 5000
      }
    ]
  }
}

subscribe Rare

Fired when a viewer subscribes to the streamer.

userObjectSubscriber
{
  "event": "subscribe",
  "data": {
    "user": {
      "uniqueId": "subscriber1"
    }
  }
}

linkMicBattle During battles

Fired when a TikTok LIVE battle starts, updates, or ends. Includes scores + participants.

battleUsersArrayParticipants with scores
typeNumber1=start, 2=update, 3=end
{
  "event": "linkMicBattle",
  "data": {
    "type": 1,
    "battleUsers": [
      {
        "uniqueId": "streamer1"
      },
      {
        "uniqueId": "streamer2"
      }
    ]
  }
}

roomPin Rare

Fired when the streamer pins a chat message.

pinnedMessageObjectMessage content + sender
{
  "event": "roomPin",
  "data": {
    "pinnedMessage": {
      "text": "Welcome!",
      "user": {
        "uniqueId": "streamer"
      }
    }
  }
}

Frequently asked

Do I need a paid plan to receive events?

No. The Sandbox tier is free and ships the full real event payload (real usernames, real diamonds, etc) - your client signs the upstream WebSocket with its own TikTok cookie. The only hard caps are 1 concurrent WebSocket connection and 2,500 REST requests/day. Basic at $7/wk lifts the cap to 20 concurrent WS + 10,000 req/day.

Which event fires most often on a busy stream?

`like` and `chat` dominate by frequency. `gift` is the highest-value signal per event.

Can I subscribe to multiple TikTok creators at once?

Yes. Open one WebSocket per uniqueId. Pro tier allows 50 concurrent WS, Ultra 250.

How do I detect when a gift streak ends?

Watch `repeatEnd === true` on the `gift` event. The streak count is in `repeatCount` and the final total diamonds = `diamondCount * repeatCount`.

What is the latency vs the actual stream?

Events arrive ~150-400ms after they fire on TikTok. Faster than the video stream itself on most CDNs.

Do battles fire for both creators?

Yes. Connect to either creator in the battle - both receive the same `linkMicBattle` event with both `battleUsers` populated.