事件參考 · 即時 FIREHOSE · 串流中
TikTok LIVE 的完整事件清單
聊天、禮物、按讚、進場、追蹤、PK、訂閱。TikTok LIVE 上的每個事件都透過同一條 WebSocket 串流，附完整中繼資料。下方的動態就是此刻真實的公開 firehose，不是示意圖。
即時事件動態
等待下一個直播事件...
公開 firehose 有遮蔽，但每個事件都是來自真實 TikTok LIVE 直播間的真實推送。用你自己的金鑰連線，就能收到完整顯示的 payload（真實使用者名稱、真實頭像、真實鑽石數）。各方案之間唯一的差別是同時連線數上限。
在你的技術堆疊裡訂閱 firehose
選語言、複製、執行。Sandbox 金鑰請到 /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訊息內容userIdString數字形式的 TikTok 使用者 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 金鑰可使用 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`，或幾秒內沒有新的 frame 就自行結束，取最大的 `repeatCount`。其他禮物不會送結束 frame：像 8 個一次送出這種數量送禮，就是一個 `repeatCount` 為 8 的 frame，收到時直接計算即可。不管哪種，總鑽石數都是 `diamondCount * repeatCount`。
跟實際直播相比延遲多少？
事件在 TikTok 上觸發後約 150-400 毫秒送達。在大多數 CDN 上比直播影像本身還快。
PK 事件兩位直播主都會觸發嗎？
會。連上 PK 中任一位直播主都可以，兩邊都會收到同樣的 `linkMicBattle` 事件，`battleUsers` 裡兩位都有資料。