이벤트 레퍼런스 · 실시간 파이어호스 · 지금 스트리밍 중
TikTok LIVE의 모든 이벤트 한눈에
채팅. 선물. 좋아요. 입장. 팔로우. 배틀. 구독. TikTok LIVE의 모든 이벤트가 풍부한 메타데이터와 함께 WebSocket 하나로 들어와요. 아래 피드는 목업이 아니라 지금 이 순간의 실제 공개 파이어호스예요.
실시간 이벤트 피드
다음 라이브 이벤트를 기다리는 중...
공개 파이어호스는 마스킹돼 있지만, 모든 이벤트는 실제 TikTok LIVE 방에서 온 진짜 데이터예요. 내 키로 연결하면 마스킹 없는 전체 페이로드(실제 사용자 이름, 실제 프로필 사진, 실제 다이아몬드 수)를 받아요. 요금제마다 달라지는 건 동시 연결 한도뿐이에요.
내 스택에서 파이어호스 구독하기
언어를 고르고, 복사하고, 실행하세요. 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()모든 이벤트의 발생 조건과 페이로드 내용
모든 이벤트는 { 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(같은 페이로드의 별칭)로도 보내 줘요.
viewerCountNumber지금 시청 중인 인원topViewersArray참여도순 정렬{
"event": "roomUserSeq",
"data": {
"viewerCount": 1234,
"topViewers": [
{
"user": {
"uniqueId": "top_fan"
},
"coinCount": 5000
}
]
}
}subscribe드묾
시청자가 스트리머를 구독하면 발생해요.
userObject구독자{
"event": "subscribe",
"data": {
"user": {
"uniqueId": "subscriber1"
}
}
}linkMicBattle배틀 중
TikTok LIVE 배틀이 시작, 업데이트, 종료될 때 발생해요. 점수 + 참가자 포함.
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 요금제는 무료이며 실제 이벤트 페이로드 전체(실제 사용자 이름, 실제 다이아몬드 등)를 제공해요. 클라이언트가 자체 TikTok 쿠키로 업스트림 WebSocket에 서명해요. 고정 한도는 동시 WebSocket 연결 3개와 하루 REST 요청 5,000건뿐이에요. 주 $7의 Basic은 한도를 동시 WS 20개 + 하루 요청 10,000건으로 늘려 줘요.
붐비는 방송에서 가장 자주 발생하는 이벤트는 뭔가요?
빈도로는 `like`와 `chat`이 압도적이에요. 이벤트당 가치가 가장 높은 신호는 `gift`예요.
여러 TikTok 크리에이터를 한 번에 구독할 수 있나요?
네. uniqueId마다 WebSocket을 하나씩 여세요. Pro 요금제는 동시 WS 50개, Ultra는 250개까지 가능해요.
선물 연속 전송이 끝난 걸 어떻게 알 수 있나요?
연속 전송은 콤보 가능한 선물(`giftType` 1)에만 있어요. `repeatEnd === true`를 기다리거나, 몇 초 동안 새 프레임이 오지 않으면 직접 종료 처리하고 가장 큰 `repeatCount`를 쓰세요. 다른 선물은 종료 프레임을 보내지 않아요. 8개처럼 수량을 지정해 보내면 `repeatCount` 8인 프레임 하나로 오니, 도착할 때 바로 집계하세요. 어느 쪽이든 총 다이아몬드 = `diamondCount * repeatCount`예요.
실제 방송 대비 지연 시간은 얼마인가요?
이벤트는 TikTok에서 발생한 뒤 약 150-400ms 후에 도착해요. 대부분의 CDN에서 영상 스트림 자체보다 빨라요.
배틀 이벤트는 양쪽 크리에이터 모두에게 발생하나요?
네. 배틀 중인 크리에이터 중 아무나 연결하면 돼요. 양쪽 모두 `battleUsers`가 채워진 같은 `linkMicBattle` 이벤트를 받아요.