Migration

Switch from TikTok-Live-Connector or TikTokLive in a few lines, keep your code

Change the import and the constructor, keep your event handlers. Below is the same script in TikTok-Live-Connector (Node) and TikTokLive (Python) next to the TikTools SDK, plus a map of every event that has a different name.

The TikTools snippets on this page are the exact scripts run against a live stream on 2026-10-31, with the key replaced by YOUR_API_KEY.

Node: TikTok-Live-Connector to @tiktool/live

npm install @tiktool/live

Before: tiktok-live-connector (from its README)

const { TikTokLiveConnection, WebcastEvent } = require('tiktok-live-connector');

const connection = new TikTokLiveConnection('username');

connection.connect()
  .then(state => console.info(`Connected to roomId ${state.roomId}`))
  .catch(err => console.error('Failed to connect', err));

connection.on(WebcastEvent.CHAT, data => {
  console.log(`${data.user.uniqueId} writes: ${data.comment}`);
});

connection.on(WebcastEvent.GIFT, data => {
  console.log(`${data.user.uniqueId} sends ${data.giftId}`);
});

After: @tiktool/live

// Before: const { TikTokLiveConnection } = require('tiktok-live-connector');
const { TikTokLive } = require('@tiktool/live');

const connection = new TikTokLive({
  uniqueId: process.argv[2] || 'username',
  apiKey: process.env.TIKTOOL_API_KEY || 'YOUR_API_KEY',
});

connection.on('connected', () => console.log(`Connected to roomId ${connection.roomId}`));
connection.on('chat', data => console.log(`${data.user.uniqueId} (userId:${data.user.id}) writes: ${data.comment}`));
connection.on('gift', data => {
  if (data.giftType === 1 && !data.repeatEnd) return; // streak still running
  console.log(`${data.user.uniqueId} sent ${data.giftName} x${data.repeatCount} (${data.diamondCount * data.repeatCount} diamonds)`);
});
connection.on('like', data => console.log(`${data.user.uniqueId} liked x${data.likeCount} (total ${data.totalLikes})`));
connection.on('member', data => console.log(`${data.user.uniqueId} joined`));
connection.on('roomUserSeq', data => console.log(`Viewers: ${data.viewerCount}`));
connection.on('disconnected', (code, reason) => console.log(`Disconnected ${code} ${reason}`));

connection.connect().catch(err => console.error('Failed to connect', err));

What changes

  • The import: TikTokLive from @tiktool/live instead of TikTokLiveConnection.
  • The constructor takes one object: { uniqueId, apiKey }. TTLC options such as processInitialData or fetchRoomInfoOnConnect have no equivalent and can be removed.
  • Event names are plain strings. WebcastEvent.CHAT is 'chat', so most handlers keep working; the renamed ones are in the table below.
  • The room id is on connection.roomId; there is no state object passed to connect().
  • By default the SDK opens the WebSocket from your process. Set mode: 'relayed' to receive events from wss://api.tik.tools instead (see only works with VPN).

Event names

TikTok-Live-Connector@tiktool/liveNote
chat, gift, member, like, socialsame namesHandlers keep working.
streamEnd, envelope, liveIntrosame namesHandlers keep working.
roomUserroomUserSeqviewerCount and totalViewers on the payload.
followsocialArrives with action follow.
sharesocialArrives with action share.
emoteemoteChat
questionNewquestion
linkMicBattlebattle
linkMicArmiesbattleArmies
linkMicFanTicketMethodfanTicket
linkMicMethodlinkMic
subNotifysubscribe
controlMessagecontrol
connected / disconnected / errorconnected / disconnected / errordisconnected receives (code, reason).
goalUpdate, caption, imDelete, inRoomBanner, poll, rankText, roomPin, giftPanelUpdateno equivalentRemove these handlers.

Payload fields

TikTok-Live-Connector@tiktool/liveNote
user.userIduser.id
user.uniqueIduser.uniqueIdSame.
giftDetails.giftType, giftDetails.giftNamegiftType, giftNameGift fields, diamondCount and repeatCount sit on the event itself.
connection.stateconnection.connected, connection.roomIdNo getState().

Python: TikTokLive to tiktok-live-api

pip install tiktok-live-api

Before: TikTokLive (from its README)

from TikTokLive import TikTokLiveClient
from TikTokLive.events import ConnectEvent, CommentEvent

client: TikTokLiveClient = TikTokLiveClient(unique_id="@username")

@client.on(ConnectEvent)
async def on_connect(event: ConnectEvent):
    print(f"Connected to @{event.unique_id} (Room ID: {client.room_id}")

@client.on(CommentEvent)
async def on_comment(event: CommentEvent) -> None:
    print(f"{event.user.nickname} -> {event.comment}")

client.run()

After: tiktok-live-api

# Before: from TikTokLive import TikTokLiveClient
import os, sys
from tiktok_live_api import TikTokLive

client = TikTokLive(sys.argv[1] if len(sys.argv) > 1 else "username",
                    api_key=os.environ.get("TIKTOOL_API_KEY", "YOUR_API_KEY"))

@client.on("connected")
def on_connect(event):
    print(f"Connected to @{event['uniqueId']}")

@client.on("chat")
def on_comment(event):
    print(f"{event['user']['nickname']} -> {event['comment']}")

@client.on("gift")
def on_gift(event):
    if event.get("giftType") == 1 and not event.get("repeatEnd"):
        return  # streak still running
    print(f"{event['user']['uniqueId']} sent {event['giftName']} x{event['repeatCount']}")

@client.on("like")
def on_like(event):
    print(f"{event['user']['uniqueId']} liked x{event['likeCount']}")

client.run()

What changes

  • The import: from tiktok_live_api import TikTokLive, and the key goes in as api_key=.
  • Handlers are registered with a string, for example @client.on("chat"), and can be plain functions.
  • Each event is a dict with camelCase keys: event["user"]["uniqueId"], event["comment"], event["giftName"].
  • client.run() blocks, as before. The Python SDK receives events from wss://api.tik.tools.

Event names

TikTokLivetiktok-live-apiNote
ConnectEvent"connected"
CommentEvent"chat"Text in event["comment"].
GiftEvent"gift"giftName, giftType, repeatCount and repeatEnd sit on the event.
LikeEvent"like"
JoinEvent"member"
SocialEvent, FollowEvent, ShareEvent"social"Check event["action"].
RoomUserSeqEvent"roomUserSeq"
LiveEndEvent"streamEnd"
WebsocketResponseEvent"event"Catch-all for every event.

Next steps