事件参考 · 实时全量事件流 · 正在推送
TikTok LIVE 的完整事件词汇表
弹幕、礼物、点赞、进场、关注、PK、订阅。TikTok LIVE 上的每个事件都通过同一条 WebSocket 推送，并附带丰富的元数据。下方是此刻真实的公开全量事件流，不是演示效果图。
实时事件流
正在等待下一个直播事件...
公开全量事件流已脱敏，但每个事件都是来自真实 TikTok 直播间的真实推送。用你自己的 Key 连接即可接收完整的不脱敏 payload（真实用户名、真实头像、真实钻石数）。不同套餐之间唯一的区别是并发连接上限。
在你的技术栈中订阅全量事件流
选择语言，复制，运行。Sandbox Key 可在 /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()每个事件：触发条件和 payload 内容
所有事件共用 { event: string, data: object } 结构。下面列出每种事件类型及其携带的数据。
chat非常频繁
观众发送弹幕时触发，是最常见的事件。
userObjectuniqueId, nickname, profilePictureUrl, badgescommentString消息内容userIdStringTikTok 数字用户 ID{
"event": "chat",
"data": {
"user": {
"uniqueId": "viewer42",
"nickname": "Viewer 42"
},
"comment": "Hello!",
"userId": "7123456789"
}
}gift中等
观众赠送虚拟礼物时触发，包含礼物名称、钻石价值和连击数据。
userObject赠送者giftNameString例如 "Rose"、"Galaxy"giftIdNumber数字礼物 IDdiamondCountNumber钻石价值repeatCountNumber连击次数repeatEndBoolean连击结束时为 true{
"event": "gift",
"data": {
"user": {
"uniqueId": "big_fan"
},
"giftName": "Rose",
"giftId": 5655,
"diamondCount": 1,
"repeatCount": 5,
"repeatEnd": true
}
}like非常频繁
观众点击点赞按钮时触发，包含累计点赞总数。
userObject点赞者likeCountNumber本次事件点赞数totalLikeCountNumber本场直播总数{
"event": "like",
"data": {
"user": {
"uniqueId": "liker1"
},
"likeCount": 15,
"totalLikeCount": 12500
}
}member中等
观众进入直播间时触发。
userObject进场用户{
"event": "member",
"data": {
"user": {
"uniqueId": "new_viewer",
"nickname": "New Viewer"
}
}
}follow较少
观众在直播期间关注主播时触发。
userObject关注者{
"event": "follow",
"data": {
"user": {
"uniqueId": "new_follower"
}
}
}share较少
观众分享直播间时触发。
userObject分享者{
"event": "share",
"data": {
"user": {
"uniqueId": "sharer"
}
}
}roomUserSeq定期
定期推送的观众数更新，是追踪实时观众数的主要方式。SDK 还会以 viewer_count 的名义发出同一事件（别名，payload 相同）。
viewerCountNumber当前在线观众数topViewersArray按互动度排序{
"event": "roomUserSeq",
"data": {
"viewerCount": 1234,
"topViewers": [
{
"user": {
"uniqueId": "top_fan"
},
"coinCount": 5000
}
]
}
}subscribe罕见
观众订阅主播时触发。
userObject订阅者{
"event": "subscribe",
"data": {
"user": {
"uniqueId": "subscriber1"
}
}
}linkMicBattlePK 期间
TikTok LIVE PK 开始、更新或结束时触发，包含比分和参与者。
battleUsersArray参与者及其比分typeNumber1=开始，2=更新，3=结束{
"event": "linkMicBattle",
"data": {
"type": 1,
"battleUsers": [
{
"uniqueId": "streamer1"
},
{
"uniqueId": "streamer2"
}
]
}
}roomPin罕见
主播置顶弹幕时触发。
pinnedMessageObject消息内容和发送者{
"event": "roomPin",
"data": {
"pinnedMessage": {
"text": "Welcome!",
"user": {
"uniqueId": "streamer"
}
}
}
}常见问题
接收事件需要付费套餐吗？
评估阶段不需要。Sandbox Key 可使用 7 天，并提供完整的真实事件 payload（真实用户名、真实钻石数等），你的客户端会用自己的 TikTok cookie 为上游 WebSocket 签名。评估期间的上限是 3 个并发 WebSocket 连接和每天 5,000 次 REST 请求。7 天后需要付费套餐；Basic 套餐 $7/周，提供 20 个并发 WS 和每天 10,000 次请求。
热门直播中哪个事件触发最频繁？
按频率算，`like` 和 `chat` 占绝大多数。按单个事件的价值算，`gift` 是最高价值的信号。
可以同时订阅多个 TikTok 主播吗？
可以。每个 uniqueId 开一条 WebSocket。Pro 套餐支持 50 个并发 WS，Ultra 支持 250 个。
如何判断礼物连击已结束？
只有可连击礼物（`giftType` 1）才会连击：监听 `repeatEnd === true`，或者在几秒内没有新帧时自行结束，并取最大的 `repeatCount`。其他礼物从不发送结束帧：像 8x 这样的批量赠送只有一帧，`repeatCount` 为 8，收到时直接计数即可。无论哪种情况，总钻石数 = `diamondCount * repeatCount`。
相比实际直播画面，延迟是多少？
事件在 TikTok 上触发后约 150-400ms 送达，在大多数 CDN 上比视频流本身还快。
PK 事件会为双方主播都触发吗？
会。连接 PK 中任意一位主播即可，双方都会收到同一个 `linkMicBattle` 事件，且 `battleUsers` 中包含双方数据。