PricingDocs
Get API keyRANKS

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. The feed below is the real public firehose right now - not a mockup.

Get a free sandbox keyRead the docs

Live event feed

0 events buffered · real public stream

Waiting for the next live event...

The public firehose is masked, but every event is a real push from a real TikTok LIVE room. Connect with your own key to receive the full unmasked payload (real usernames, real avatars, real diamond counts) - the only thing that changes between tiers is the concurrent-connection cap.

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.

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

giftModerate

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

likeVery 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
  }
}

memberModerate

Fired when a viewer joins the live stream room.

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

followLow

Fired when a viewer follows the streamer during the live.

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

shareLow

Fired when a viewer shares the live stream.

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

roomUserSeqPeriodic

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
      }
    ]
  }
}

subscribeRare

Fired when a viewer subscribes to the streamer.

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

linkMicBattleDuring 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"
      }
    ]
  }
}

roomPinRare

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.