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.
Node: TikTok-Live-Connector to @tiktool/live
npm install @tiktool/liveBefore: 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:
TikTokLivefrom@tiktool/liveinstead ofTikTokLiveConnection. - The constructor takes one object:
{ uniqueId, apiKey }. TTLC options such asprocessInitialDataorfetchRoomInfoOnConnecthave no equivalent and can be removed. - Event names are plain strings.
WebcastEvent.CHATis'chat', so most handlers keep working; the renamed ones are in the table below. - The room id is on
connection.roomId; there is nostateobject passed toconnect(). - 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/live | Note |
|---|---|---|
chat, gift, member, like, social | same names | Handlers keep working. |
streamEnd, envelope, liveIntro | same names | Handlers keep working. |
roomUser | roomUserSeq | viewerCount and totalViewers on the payload. |
follow | social | Arrives with action follow. |
share | social | Arrives with action share. |
emote | emoteChat | |
questionNew | question | |
linkMicBattle | battle | |
linkMicArmies | battleArmies | |
linkMicFanTicketMethod | fanTicket | |
linkMicMethod | linkMic | |
subNotify | subscribe | |
controlMessage | control | |
connected / disconnected / error | connected / disconnected / error | disconnected receives (code, reason). |
goalUpdate, caption, imDelete, inRoomBanner, poll, rankText, roomPin, giftPanelUpdate | no equivalent | Remove these handlers. |
Payload fields
| TikTok-Live-Connector | @tiktool/live | Note |
|---|---|---|
user.userId | user.id | |
user.uniqueId | user.uniqueId | Same. |
giftDetails.giftType, giftDetails.giftName | giftType, giftName | Gift fields, diamondCount and repeatCount sit on the event itself. |
connection.state | connection.connected, connection.roomId | No getState(). |
Python: TikTokLive to tiktok-live-api
pip install tiktok-live-apiBefore: 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 asapi_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
| TikTokLive | tiktok-live-api | Note |
|---|---|---|
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
- Get a key: Sandbox is a 7-day evaluation, no credit card. Plans and limits are on the pricing page.
- Seeing an error in the library right now? See the troubleshooting guides.
- Event payloads in full: the docs. Short overview: migrate from TikTok-Live-Connector.