TÀI LIỆU SỰ KIỆN · FIREHOSE TRỰC TIẾP · ĐANG PHÁT
Toàn bộ bộ sự kiện của TikTok LIVE
Chat. Quà tặng. Like. Vào phòng. Follow. PK. Đăng ký. Mọi sự kiện trên TikTok LIVE truyền qua một WebSocket với metadata đầy đủ. Feed bên dưới là firehose công khai thật ngay lúc này - không phải bản mô phỏng.
Feed sự kiện trực tiếp
Đang chờ sự kiện live tiếp theo...
Firehose công khai đã được che, nhưng mỗi sự kiện đều là một lần đẩy thật từ một phòng TikTok LIVE thật. Kết nối bằng key của riêng bạn để nhận payload đầy đủ không che (username thật, avatar thật, số kim cương thật) - thứ duy nhất khác nhau giữa các gói là giới hạn kết nối đồng thời.
Đăng ký firehose trong stack của bạn
Chọn ngôn ngữ. Sao chép. Chạy. Key Sandbox lấy tại /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()Mọi sự kiện, khi nào kích hoạt, payload có gì
Mọi sự kiện dùng chung cấu trúc { event: string, data: object }. Bên dưới: từng loại sự kiện và dữ liệu đi kèm.
chatRất thường xuyên
Kích hoạt khi người xem gửi tin nhắn chat. Sự kiện phổ biến nhất.
userObjectuniqueId, nickname, profilePictureUrl, badgescommentStringNội dung tin nhắnuserIdStringID người dùng TikTok dạng số{
"event": "chat",
"data": {
"user": {
"uniqueId": "viewer42",
"nickname": "Viewer 42"
},
"comment": "Hello!",
"userId": "7123456789"
}
}giftVừa phải
Kích hoạt khi người xem tặng quà ảo. Gồm tên quà, giá trị kim cương, dữ liệu combo.
userObjectNgười tặnggiftNameStringvd. "Rose", "Galaxy"giftIdNumberID quà dạng sốdiamondCountNumberGiá trị kim cươngrepeatCountNumberSố comborepeatEndBooleanTrue khi combo kết thúc{
"event": "gift",
"data": {
"user": {
"uniqueId": "big_fan"
},
"giftName": "Rose",
"giftId": 5655,
"diamondCount": 1,
"repeatCount": 5,
"repeatEnd": true
}
}likeRất thường xuyên
Kích hoạt khi người xem bấm thả tim. Gồm tổng số lượt thích tích lũy.
userObjectNgười thả timlikeCountNumberSố trong sự kiện nàytotalLikeCountNumberTổng của phiên live{
"event": "like",
"data": {
"user": {
"uniqueId": "liker1"
},
"likeCount": 15,
"totalLikeCount": 12500
}
}memberVừa phải
Kích hoạt khi người xem vào phòng live.
userObjectNgười vào phòng{
"event": "member",
"data": {
"user": {
"uniqueId": "new_viewer",
"nickname": "New Viewer"
}
}
}followThấp
Kích hoạt khi người xem follow idol trong lúc live.
userObjectNgười follow{
"event": "follow",
"data": {
"user": {
"uniqueId": "new_follower"
}
}
}shareThấp
Kích hoạt khi người xem chia sẻ phiên live.
userObjectNgười chia sẻ{
"event": "share",
"data": {
"user": {
"uniqueId": "sharer"
}
}
}roomUserSeqĐịnh kỳ
Cập nhật số người xem định kỳ. Cách chính để theo dõi số người xem theo thời gian thực. SDK cũng phát nó dưới tên viewer_count (bí danh, cùng payload).
viewerCountNumberSố người đang xemtopViewersArrayXếp theo mức tương tác{
"event": "roomUserSeq",
"data": {
"viewerCount": 1234,
"topViewers": [
{
"user": {
"uniqueId": "top_fan"
},
"coinCount": 5000
}
]
}
}subscribeHiếm
Kích hoạt khi người xem đăng ký idol.
userObjectNgười đăng ký{
"event": "subscribe",
"data": {
"user": {
"uniqueId": "subscriber1"
}
}
}linkMicBattleTrong lúc PK
Kích hoạt khi một trận PK TikTok LIVE bắt đầu, cập nhật hoặc kết thúc. Gồm điểm số + người tham gia.
battleUsersArrayNgười tham gia kèm điểmtypeNumber1=bắt đầu, 2=cập nhật, 3=kết thúc{
"event": "linkMicBattle",
"data": {
"type": 1,
"battleUsers": [
{
"uniqueId": "streamer1"
},
{
"uniqueId": "streamer2"
}
]
}
}roomPinHiếm
Kích hoạt khi idol ghim một tin nhắn chat.
pinnedMessageObjectNội dung tin nhắn + người gửi{
"event": "roomPin",
"data": {
"pinnedMessage": {
"text": "Welcome!",
"user": {
"uniqueId": "streamer"
}
}
}
}Câu hỏi thường gặp
Có cần gói trả phí mới nhận được sự kiện không?
Không, nếu chỉ để đánh giá. Key Sandbox dùng được 7 ngày và trả về payload sự kiện thật đầy đủ (username thật, kim cương thật, v.v.) - client của bạn tự ký WebSocket upstream bằng cookie TikTok của chính nó. Trong thời gian đánh giá, giới hạn là 3 kết nối WebSocket đồng thời và 5.000 request REST/ngày. Sau 7 ngày cần chọn gói trả phí; Basic giá $7/tuần cho 20 WS đồng thời + 10.000 request/ngày.
Trên phiên live đông người, sự kiện nào xuất hiện nhiều nhất?
`like` và `chat` chiếm đa số về tần suất. `gift` là tín hiệu có giá trị cao nhất trên mỗi sự kiện.
Có thể đăng ký nhiều nhà sáng tạo TikTok cùng lúc không?
Có. Mở một WebSocket cho mỗi uniqueId. Gói Pro cho 50 WS đồng thời, Ultra 250.
Làm sao biết combo quà đã kết thúc?
Chỉ quà có combo (`giftType` 1) mới chạy combo: theo dõi `repeatEnd === true`, hoặc tự đóng combo khi không có frame mới trong vài giây, rồi lấy `repeatCount` cao nhất. Các quà khác không bao giờ gửi frame kết thúc: tặng theo số lượng như 8x là một frame với `repeatCount` 8, nên hãy cộng ngay khi nhận. Dù cách nào thì tổng kim cương = `diamondCount * repeatCount`.
Độ trễ so với livestream thật là bao nhiêu?
Sự kiện tới khoảng ~150-400ms sau khi xảy ra trên TikTok. Nhanh hơn cả luồng video trên hầu hết CDN.
Sự kiện PK có kích hoạt cho cả hai nhà sáng tạo không?
Có. Kết nối tới bất kỳ nhà sáng tạo nào trong trận PK - cả hai đều nhận cùng sự kiện `linkMicBattle` với `battleUsers` của cả hai bên.