Migration guide

Switch from TikTok-Live-Connector in a few lines

Already using tiktok-live-connector? Switch to the managed TikTool API by changing the import and the constructor. Your event handlers stay as they are.

1

Install the SDK

npm install @tiktool/live
2

Change the import

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

Pass your TikTools API key to the constructor

-new TikTokLiveConnection('username')
+new TikTokLive({ uniqueId: 'username', apiKey: 'YOUR_API_KEY' })

Get a 7-day evaluation key at tik.tools - no credit card required.

That's it. Handlers for these events work as before: chat, gift, member, like, social, envelope, liveIntro, streamEnd, connect(), disconnect(). The table below lists the events that have a different name.

Full Working Example

The same handlers as a tiktok-live-connector script. Only the import and the constructor change for @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));

Event name map

TikTok-Live-Connector event names and the matching names in the TikTools Node SDK, checked against the source of both packages.

TTLC eventTikTools eventNotes
chatchatSame name
membermemberSame name
giftgiftSame name
likelikeSame name
socialsocialSame name
followsocialArrives as social with action follow
sharesocialArrives as social with action share
roomUserroomUserSeqListen for roomUserSeq instead
questionNewquestionListen for question instead
linkMicBattlebattleListen for battle instead
linkMicArmiesbattleArmiesListen for battleArmies instead
linkMicFanTicketMethodfanTicketListen for fanTicket instead
linkMicMethodlinkMicListen for linkMic instead
emoteemoteChatListen for emoteChat instead
subNotifysubscribeListen for subscribe instead
controlMessagecontrolListen for control instead
envelopeenvelopeSame name
liveIntroliveIntroSame name
streamEndstreamEndSame name
connectedconnectedSame name
disconnecteddisconnectedSame name
errorerrorSame name

Why Switch to the Managed API?

Protocol changes handled for you

When TikTok changes its protocol, TikTools ships the fix on the service side or in an SDK update. The live status page shows any incident.

Events as JSON

Events arrive decoded, with no protobuf work on your end.

One small dependency

The Node SDK depends only on the ws package. No protobuf library and no request signing in your code.

Automatic reconnect

Built-in reconnection with exponential backoff when the connection drops.

Usage Dashboard

Monitor your API usage, WebSocket connections, and event volume in real-time at tik.tools/dashboard.

Developer Support

Get help by email or in the support chat on the site and in the dashboard.

Common Questions

Will my TypeScript types still work?

Yes. @tiktool/live ships TypeScript definitions for every event payload, including chat, gift and roomUserSeq.

What about TTLC options like sessionId, processInitialData and requestPollingIntervalMs?

The constructor takes one options object with uniqueId and apiKey, plus optional settings such as autoReconnect and debug. TTLC options such as processInitialData and requestPollingIntervalMs have no equivalent and can be removed.

TTLC sometimes works without an API key. Do I need one for TikTool?

Yes - a apiKey is required. A Sandbox key for a 7-day evaluation takes 30 seconds to get at tik.tools/login with no credit card. Sandbox includes 5,000 API calls/day and 3 concurrent WebSocket connections, which is enough for development and testing; after 7 days a paid plan is required.

What actually happens when TikTok updates their protocol?

TikTok changes its signature scheme and message formats from time to time. With an open-source connector you wait for a library release and then upgrade. With TikTools the change is handled on the service side or in an SDK release, and the live status page shows any incident.

Also included with TikTools

Live Feed Discovery

See which creators are live on TikTok right now.

Python SDK

Python SDK: pip install tiktok-live-api. The same event names, in Python.

Ready to Migrate?

Get a 7-day evaluation key - no credit card needed. The Sandbox tier includes 5,000 requests/day and 3 concurrent WebSocket connections for 7 days, development and evaluation only.