Node.js SDK

Official TikTool Node.js SDK - connect to any TikTok Live stream with a simple, event-driven API.

Installation

npm install @tiktool/live

Quick Start

import { TikTokLive } from '@tiktool/live';

const client = new TikTokLive({
  apiKey: process.env.TIKTOOL_API_KEY,
  uniqueId: 'streamer_username',
});

client.on('connected', () => console.log('Connected!'));
client.on('chat', (event) => console.log(`${event.user.uniqueId}: ${event.comment}`));
client.on('gift', (event) => console.log(`${event.user.uniqueId} sent ${event.giftName}`));
client.on('like', (event) => console.log(`${event.user.uniqueId} liked × ${event.likeCount}`));

await client.connect();

Configuration

Option	Type	Default	Description
apiKey	string	-	Your TikTool API key
uniqueId	string	-	TikTok username to connect to
enableExtendedGiftInfo	boolean	false	Fetch full gift details (image, diamond values)
requestPollingIntervalMs	number	1000	Polling interval for HTTP mode

Events

All events from the WebSocket Events reference are available:

client.on('chat', (event) => { /* chat message */ });
client.on('gift', (event) => { /* virtual gift */ });
client.on('like', (event) => { /* likes */ });
client.on('member', (event) => { /* viewer joined */ });
client.on('follow', (event) => { /* new follower */ });
client.on('share', (event) => { /* stream shared */ });
client.on('roomUserSeq', (event) => { /* viewer count update */ });
client.on('subscribe', (event) => { /* new subscriber */ });
client.on('battle', (event) => { /* PK on/off */ });
client.on('battleArmies', (event) => { /* PK score + MVP breakdown */ });
client.on('battleItemCard', (event) => { /* x2/x3 boosters, gloves, mist, ... */ });
client.on('emote', (event) => { /* animated emote */ });
client.on('envelope', (event) => { /* treasure box */ });
client.on('questionNew', (event) => { /* Q&A question */ });
client.on('roomPin', (event) => { /* starred / pinned message */ });

PK Battles - MVP + Boosters

client.on('battleArmies', (e) => {
  console.log(`⏱ ${e.secsRemaining}s left`);
  for (const host of e.hosts ?? []) {
    const mvp = host.contributors[0]; // sorted MVP first
    console.log(`${host.hostUserId}: ${host.teamTotalScore} (MVP: ${mvp?.nickname} ${mvp?.score})`);
  }
});

client.on('battleItemCard', (e) => {
  const tag = e.multiplier > 0 ? `x${e.multiplier} BOOSTER` : e.effect.toUpperCase();
  console.log(`💥 ${e.senderNickname} → ${tag}`);
  // e.iconUrl / e.accentColor → drop-in OBS overlay
});

Source Code

GitHub Repository

MIT-licensed. Full source code available.