TikTok-Live-Connector

TikTok LIVE API for Node.JS (Unofficial)

TikTok LIVE API Client for Node.JS (Unofficial, Unaffiliated with ByteDance Ltd.)

Connect to any TikTok LIVE stream and receive real-time chat messages, gifts, likes, follows, shares, viewer counts and battles using just a creator's username (@uniqueId). No login, credentials or app registration are required.

TikTokLiveConnector reads TikTok's internal Webcast push service directly, which makes it the foundation for TikTok chat bots, gift trackers, OBS overlays, donation alerts, moderation tools and livestream analytics. It works for your own live chat and for any other creator's.

Full guides, event reference and API documentation: https://ttlc.docs.isaackogan.com/

Tracked events include Chat Comments, Members Joining, Gifts, Viewers, Follows, Shares, Questions, Likes, Super Fans and Battles.

[!NOTE] This is not a production-ready API. It is a reverse engineering project. Use the WebSocket API for production.

[!TIP] An example project is available at https://tiktok-chat-reader.zerody.one/ - View Source

Do you prefer other programming languages?

• Python rewrite: TikTokLive by @isaackogan and @eulerstream
• Java rewrite: TikTokLiveJava by @jwdeveloper and @kohlerpop1
• Go rewrite: GoTikTokLive by @steampoweredtaco and @davincible
• C# rewrite: TikTokLiveSharp by @frankvHoof93

Table of Contents

• Getting Started
• Params and Options
• Methods
• Properties
• Events
• Examples

Getting Started

1. Install the package via NPM

npm i tiktok-live-connector

2. Create your first TikTok LIVE chat connection

// Username of someone who is currently live
import { TikTokLiveConnection, WebcastEvent } from 'tiktok-live-connector';

const tiktokUsername = 'officialgeilegisela';

// Create a new wrapper object and pass the username
const connection = new TikTokLiveConnection(tiktokUsername);

// Connect to the chat (await can be used as well)
connection.connect().then(state => {
    console.info(`Connected to roomId ${state.roomId}`);
}).catch(err => {
    console.error('Failed to connect', err);
});

// Define the events that you want to handle
// In this case we listen to chat messages (comments)
connection.on(WebcastEvent.CHAT, data => {
    console.log(`${data.user.uniqueId} (userId:${data.user.uniqueId}) writes: ${data.comment}`);
});

// And here we receive gifts sent to the streamer
connection.on(WebcastEvent.GIFT, data => {
    console.log(`${data.user.uniqueId} (userId:${data.user.userId}) sends ${data.giftId}`);
});

// ...and more events described in the documentation below

Params and Options

To create a new TikTokLiveConnection object the following parameters can be specified.

TikTokLiveConnection(uniqueId, [options])

Param Name	Required	Description
uniqueId	Yes	The unique username of the broadcaster. You can find this name in the URL.Example: https://www.tiktok.com/@officialgeilegisela/live becomes officialgeilegisela. The leading @ and the full URL form are also accepted.
options	No	Optional connection properties. Defaults are applied when a value is not specified.signApiKey (default: undefined)Euler Stream API key. When provided, it is written to the global SignConfig.apiKey before the underlying Euler client is created. Ignored when eulerApiInstance is passed.eulerApiInstance (default: undefined)Pre-built EulerStreamApiClient to use for all sign-server traffic. Takes precedence over signApiKey.session (default: undefined)Authenticated session bundle. Pass session.cookie to seed the cookie jar with sessionid and tt-target-idc, and/or session.oAuthToken to send an OAuth token to the sign server. Required when authenticateWs or useMobile is true. See Authenticated Connection.authenticateWs (default: false)Forward the session cookies or OAuth token to the sign server so the WebSocket is authenticated. Disabled by default since signing is done by a third-party service; enabling it sends your session credentials to that service.useMobile (default: false)Use the mobile WebSocket flow. Requires authenticateWs: true and session.cookie; connecting with useMobile but without authenticateWs throws a TypeError.processInitialData (default: true)Decode and emit the message batch returned in the initial sign response (recent chat history etc.).fetchRoomInfoOnConnect (default: true)Fetch room info during connect. If the streamer is not currently live the connect rejects with UserOfflineError. The fetched info is stored on connection.roomInfo and is also accessible via fetchRoomInfo().enableExtendedGiftInfo (default: false)Fetch the room gift list during connect so WebcastGiftMessage events carry an extendedGiftInfo field with name, cost, and image data.clientPresets (default: randomized)Pre-built { device, screen, location } presets. Defaults to a freshly randomized set from getRandomPresets().webClientOptions (default: {})Extra options forwarded to the underlying got HTTP client (proxy agent, timeout, etc.). Headers and search params from this object are merged with the defaults; transport-only fields are passed through. See Proxied Connection.wsClientOptions (default: {})Extra options forwarded to the underlying ws WebSocket client. See Proxied Connection.webConfigOverrides (default: {})Partial overrides for the resolved WebcastWebConfigDefaults used by the HTTP client. Use this to customize DEFAULT_HTTP_CLIENT_PARAMS, DEFAULT_HTTP_CLIENT_HEADERS, etc.wsConfigOverrides (default: {})Partial overrides for the resolved WebcastWebSocketConfigDefaults used by the WebSocket client. Use this to customize DEFAULT_WS_CLIENT_PARAMS or DEFAULT_WS_CLIENT_HEADERS.

Example Options

const tikTokLiveConnection = new TikTokLiveConnection(tiktokUsername, {
    signApiKey: 'your-api-key',
    processInitialData: false,
    enableExtendedGiftInfo: true,
    webConfigOverrides: {
        DEFAULT_HTTP_CLIENT_PARAMS: {
            app_language: 'en-US',
            device_platform: 'web_pc'
        },
        DEFAULT_HTTP_CLIENT_HEADERS: {
            'X-Custom-Header': 'value'
        }
    },
    wsConfigOverrides: {
        DEFAULT_WS_CLIENT_PARAMS: {
            app_language: 'en-US'
        },
        DEFAULT_WS_CLIENT_HEADERS: {
            'X-Custom-Header': 'value'
        }
    },
    webClientOptions: {
        timeout: { request: 10000 }
    },
    wsClientOptions: {
        handshakeTimeout: 10000
    }
});

Methods

Method Name	Description
connect([roomId])	Connects to the live stream chat. Returns a Promise<TikTokLiveConnectionState> that resolves when the WebSocket is open and the room has been entered. Pass an explicit roomId to skip room-id resolution.
disconnect()	Closes the WebSocket and waits for the close event before resolving. Safe to call even when not connected.
sendMessage(content, [roomId])	Sends a chat message to the connected room (or to roomId if provided). Requires signApiKey and an authenticated session. See Send Messages.
fetchRoomId([uniqueId])	Resolves the room id for the configured username (or for uniqueId if provided). Tries HTML scrape, then the TikTok API, then Euler Stream as a fallback.
fetchIsLive([uniqueId])	Resolves whether the user is currently live. Same fallback chain as fetchRoomId.
waitUntilLive([seconds], [abortSignal])	Polls fetchIsLive every seconds seconds (minimum 30) until the streamer goes live. Reject via abortSignal to cancel.
fetchRoomInfo([roomId])	Fetches room info from TikTok's webcast API. Caches the result on connection.roomInfo. Callable without an active connection. See Retrieve Room Info.
fetchAvailableGifts()	Fetches the room gift list. Caches on connection.availableGifts. Callable without an active connection. See Retrieve Available Gifts.

Properties

Property Name	Description
webClient: WebcastHttpClient	The HTTP client used to talk to TikTok's web and webcast APIs. Holds the cookie jar, the merged client params, and the merged client headers.
apiClient: EulerStreamApiClient	The Euler Stream API client used for sign-server traffic and other premium endpoints. Equivalent to webClient.apiClient.
wsClient: WebcastWebSocketClient | null	The active WebSocket client. null until the connection is established and after disconnect.
options: TikTokLiveConnectionMutableOptions	The subset of options retained on the instance (processInitialData, fetchRoomInfoOnConnect, enableExtendedGiftInfo, authenticateWs, useMobile).
roomInfo: RoomInfo | null	The room info object cached from the most recent fetchRoomInfo() call (or from connect, when fetchRoomInfoOnConnect is true).
availableGifts: RoomGiftInfo | null	The cached gift list. Populated when enableExtendedGiftInfo is true or after manually calling fetchAvailableGifts().
isConnecting: boolean	True while connect() is in flight.
isConnected: boolean	True after a successful connect, until the WebSocket closes.
clientParams: Record<string, string>	Live URI parameters sent with every webClient request. Mutating this changes outgoing query strings.
roomId: string	The currently bound room id. Empty string until connect resolves or fetchRoomId() is called.
state: TikTokLiveConnectionState	Snapshot containing isConnected, isConnecting, roomId, roomInfo, and availableGifts.

Signing Configuration

WebSocket URL signing is delegated to the Euler Stream sign server via the @eulerstream/euler-api-sdk package. Configuration is held on the mutable SignConfig singleton.

For most users, passing signApiKey to the TikTokLiveConnection constructor is enough. It writes the key to SignConfig.apiKey before the underlying Euler client is built.

For advanced cases (custom sign-server URL, extra headers, JWT auth), mutate SignConfig directly before constructing your first connection:

import { SignConfig } from 'tiktok-live-connector';

SignConfig.apiKey = 'your api key'; // An API key created at https://www.eulerstream.com
SignConfig.basePath = 'https://your-custom-sign-server.com';
SignConfig.baseOptions = SignConfig.baseOptions || {};
SignConfig.baseOptions.headers = {
    ...(SignConfig.baseOptions.headers || {}),
    'X-Custom-Header': 'Custom-Header-Value'
};

[!IMPORTANT] SignConfig is read once when the underlying Euler client is first instantiated and the result is cached. Mutate it before constructing the first TikTokLiveConnection, or pass an explicit eulerApiInstance to bypass the cache.

Accessing TikTok LIVE Routes

All HTTP route handlers live in the global RouteConfig registry and are also exported individually. Each route is a function that accepts a single options object and returns a Promise resolving to the route's response. The currently registered routes are:

• fetchRoomInfo (TikTok webcast API)
• fetchRoomGifts (TikTok webcast API)
• fetchRoomInfoFromApiLive (TikTok web API)
• fetchRoomInfoFromHtml (HTML scrape with SIGI_STATE extraction)
• fetchRoomGiftsFromProvider (Euler Stream)
• fetchRoomGiftGalleryFromProvider (Euler Stream)
• fetchRoomIdFromProvider (Euler Stream)
• fetchRoomInfoFromProvider (Euler Stream)
• fetchSignedWebSocketFromProvider (Euler Stream)
• fetchWebcastSignatureFromProvider (Euler Stream)
• sendRoomChatFromProvider (Euler Stream)
• fetchRoomIdComposite (HTML, then API, then Euler fallback)
• fetchIsLiveComposite (HTML, then API, then Euler fallback)

Example Usage

Routes need a webClient (and an apiClient for Euler routes), both of which are exposed on a TikTokLiveConnection instance:

import { TikTokLiveConnection, RouteConfig } from 'tiktok-live-connector';

const connection = new TikTokLiveConnection('officialgeilegisela');

const sigiState = await RouteConfig.fetchRoomInfoFromHtml({
    webClient: connection.webClient,
    uniqueId: 'officialgeilegisela'
});

console.log('SIGI_STATE liveRoom:', sigiState.liveRoom);

Swapping a Route Implementation

You can replace any handler in RouteConfig to inject custom behavior (caching, alternate sign provider, proxying through your own backend, etc.):

import { RouteConfig } from 'tiktok-live-connector';

const original = RouteConfig.fetchSignedWebSocketFromProvider;
RouteConfig.fetchSignedWebSocketFromProvider = async (args) => {
    console.log('signing for room', args.roomId);
    return original(args);
};

Accessing 3rd-Party (Euler Stream) Routes

The Euler Stream API client is exposed as connection.apiClient. It wraps every endpoint published by the @eulerstream/euler-api-sdk package, including premium and analytics endpoints not bundled into RouteConfig.

Example 1: Fetching Rate Limits

import { TikTokLiveConnection } from 'tiktok-live-connector';

const connection = new TikTokLiveConnection('officialgeilegisela', {
    signApiKey: 'your-api-key'
});

const response = await connection.apiClient.webcast.getRateLimits();
console.log('Rate Limits:', response.data);

Example 2: Using JWT Authentication

When running the connector in a client-facing environment (bundled desktop app, browser worker, etc.) you should not ship your raw API key. Mint a short-lived JWT on your server and hand that to the client instead.

Server-Side

import { SignConfig, createEulerClient } from 'tiktok-live-connector';

SignConfig.apiKey = 'your_server_side_api_key';
const apiClient = createEulerClient();

const res = await apiClient.authentication.createJWT(
    122, // Your account ID
    {
        limits: { minute: 5, hour: 5, day: 5 },
        expireAfter: 60 * 60 * 2 // 2 hours, the maximum accepted value
    }
);

console.log('Generated JWT:', res.data.token);

Client-Side

import { SignConfig, TikTokLiveConnection } from 'tiktok-live-connector';

SignConfig.baseOptions = SignConfig.baseOptions || {};
SignConfig.baseOptions.headers = {
    ...(SignConfig.baseOptions.headers || {}),
    'x-jwt-key': 'generated-jwt-key'
};

const connection = new TikTokLiveConnection('tv_asahi_news');

Events

A TikTokLiveConnection object has the following events which can be handled with an event listener.

The simplest event handler is a connect event:

const connection = new TikTokLiveConnection('officialgeilegisela');
connection.on(ControlEvent.CONNECTED, () => console.log("Connected!"));

Control Events:

See the control event reference for arguments and examples.

• ControlEvent.CONNECTED or "connected"
• ControlEvent.DISCONNECTED or "disconnected"
• ControlEvent.RAW_DATA or "rawData"
• ControlEvent.DECODED_DATA or "decodedData"
• ControlEvent.WEBSOCKET_CONNECTED or "websocketConnected"
• ControlEvent.ERROR or "error"
• ControlEvent.WEBSOCKET_DATA or "websocketData"

Message Events:

See the message event reference for payloads and examples.

• WebcastEvent.CHAT or "chat"
• WebcastEvent.GIFT or "gift"
• WebcastEvent.MEMBER or "member"
• WebcastEvent.LIKE or "like"
• WebcastEvent.SOCIAL or "social"
• WebcastEvent.ENVELOPE or "envelope"
• WebcastEvent.QUESTION_NEW or "questionNew"
• WebcastEvent.LINK_MIC_BATTLE or "linkMicBattle"
• WebcastEvent.LINK_MIC_ARMIES or "linkMicArmies"
• WebcastEvent.LIVE_INTRO or "liveIntro"
• WebcastEvent.SUPER_FAN or "superFan"
• WebcastEvent.SUPER_FAN_JOIN or "superFanJoin"
• WebcastEvent.FOLLOW or "follow"
• WebcastEvent.SHARE or "share"
• WebcastEvent.STREAM_END or "streamEnd"
• WebcastEvent.ROOM_USER or "roomUser"
• WebcastEvent.EMOTE or "emote"
• WebcastEvent.GOAL_UPDATE or "goalUpdate"
• WebcastEvent.ROOM_MESSAGE or "roomMessage"
• WebcastEvent.CAPTION_MESSAGE or "captionMessage"
• WebcastEvent.IM_DELETE or "imDelete"
• WebcastEvent.IN_ROOM_BANNER or "inRoomBanner"
• WebcastEvent.RANK_UPDATE or "rankUpdate"
• WebcastEvent.POLL_MESSAGE or "pollMessage"
• WebcastEvent.RANK_TEXT or "rankText"
• WebcastEvent.LINK_MIC_BATTLE_PUNISH_FINISH or "linkMicBattlePunishFinish"
• WebcastEvent.LINK_MIC_BATTLE_TASK or "linkMicBattleTask"
• WebcastEvent.LINK_MIC_FAN_TICKET_METHOD or "linkMicFanTicketMethod"
• WebcastEvent.LINK_MIC_METHOD or "linkMicMethod"
• WebcastEvent.UNAUTHORIZED_MEMBER or "unauthorizedMember"
• WebcastEvent.OEC_LIVE_SHOPPING or "oecLiveShopping"
• WebcastEvent.MSG_DETECT or "msgDetect"
• WebcastEvent.LINK_MESSAGE or "linkMessage"
• WebcastEvent.ROOM_VERIFY or "roomVerify"
• WebcastEvent.LINK_LAYER or "linkLayer"
• WebcastEvent.ROOM_PIN or "roomPin"
• WebcastEvent.SUPER_FAN_BOX or "superFanBox"
• WebcastEvent.ACCESS_CONTROL or "accessControl"
• WebcastEvent.ACCESS_RECALL or "accessRecall"
• WebcastEvent.BOOST_CARD or "boostCard"
• WebcastEvent.BOTTOM_MESSAGE or "bottomMessage"
• WebcastEvent.CAPSULE or "capsule"
• WebcastEvent.GAME_RANK_NOTIFY or "gameRankNotify"
• WebcastEvent.GIFT_BROADCAST or "giftBroadcast"
• WebcastEvent.GIFT_DYNAMIC_RESTRICTION or "giftDynamicRestriction"
• WebcastEvent.GIFT_PANEL_UPDATE or "giftPanelUpdate"
• WebcastEvent.GIFT_PROMPT or "giftPrompt"
• WebcastEvent.GUIDE or "guide"
• WebcastEvent.HOURLY_RANK or "hourlyRank"
• WebcastEvent.LINK_MIC_LAYOUT_STATE or "linkMicLayoutState"
• WebcastEvent.LINK_STATE or "linkState"
• WebcastEvent.LIVE_GAME_INTRO or "liveGameIntro"
• WebcastEvent.MARQUEE_ANNOUNCEMENT or "marqueeAnnouncement"
• WebcastEvent.NOTICE or "notice"
• WebcastEvent.PARTNERSHIP_DROPS_UPDATE or "partnershipDropsUpdate"
• WebcastEvent.PARTNERSHIP_GAME_OFFLINE or "partnershipGameOffline"
• WebcastEvent.PARTNERSHIP_PUNISH or "partnershipPunish"
• WebcastEvent.PERCEPTION or "perception"
• WebcastEvent.ROOM_NOTIFY or "roomNotify"
• WebcastEvent.SPEAKER or "speaker"
• WebcastEvent.SUB_NOTIFY or "subNotify"
• WebcastEvent.SUB_PIN_EVENT or "subPinEvent"
• WebcastEvent.TOAST or "toast"
• WebcastEvent.VIEWER_PICKS_UPDATE or "viewerPicksUpdate"

Examples

Retrieve Room Info

const connection = new TikTokLiveConnection('@username');

connection.fetchRoomInfo().then((roomInfo: RoomInfoResponse) => {
    console.log(roomInfo);
    console.log(`Stream started timestamp: ${roomInfo.create_time}, Streamer bio: ${roomInfo.owner.bio_description}`);
    console.log(`HLS URL: ${roomInfo.stream_url.hls_pull_url}`); // Can be played or recorded with e.g. VLC
}).catch(err => {
    console.error(err);
});

Retrieve Available Gifts

const connection = new TikTokLiveConnection('@username');

connection.fetchAvailableGifts().then((giftList: RoomGiftInfo) => {
    console.log(giftList);
    giftList.forEach(gift => {
        console.log(`id: ${gift.id}, name: ${gift.name}, cost: ${gift.diamond_count}`)
    });
}).catch(err => {
    console.error(err);
})

Proxied Connection

The HTTP layer uses got and the WebSocket layer uses ws. Both accept a Node http.Agent, which makes hpagent the recommended proxy integration. hpagent is already a direct dependency of this package, so no extra install is required.

HTTP Client (got) via webClientOptions

got accepts an agent map keyed by protocol (http, https, http2). Provide proxy agents for each protocol the connector talks to:

import { TikTokLiveConnection } from 'tiktok-live-connector';
import { HttpProxyAgent, HttpsProxyAgent } from 'hpagent';

const proxy = 'http://user:pwd@host:8080';

const connection = new TikTokLiveConnection('@username', {
    webClientOptions: {
        agent: {
            http: new HttpProxyAgent({ proxy, keepAlive: true }),
            https: new HttpsProxyAgent({ proxy, keepAlive: true })
        }
    }
});

This routes all TikTok web/webcast HTTP traffic (room id, room info, gift list, HTML scrape, sign requests) through the proxy.

WebSocket Client (ws) via wsClientOptions

ws accepts a single agent (a Node http.Agent). Since the WebSocket upgrade goes over wss://, use the HTTPS variant:

import { TikTokLiveConnection } from 'tiktok-live-connector';
import { HttpProxyAgent, HttpsProxyAgent } from 'hpagent';

const proxy = 'http://user:pwd@host:8080';

const connection = new TikTokLiveConnection('@username', {
    webClientOptions: {
        agent: {
            http: new HttpProxyAgent({ proxy, keepAlive: true }),
            https: new HttpsProxyAgent({ proxy, keepAlive: true })
        }
    },
    wsClientOptions: {
        agent: new HttpsProxyAgent({ proxy, keepAlive: true })
    }
});

// Connect as usual
await connection.connect();

Authenticated Connection

To connect as a specific TikTok account, log into TikTok in your browser and copy two cookies: sessionid and tt-target-idc. Both are required. sessionid is your account's session token (keep it secret), and tt-target-idc is the datacenter region your account belongs to (for example useast1a for North America).

Pass them via the session.cookie bundle. To force the WebSocket itself to authenticate (so the server treats you as that account in chat), also set authenticateWs: true.

import { TikTokLiveConnection } from 'tiktok-live-connector';

const connection = new TikTokLiveConnection(
    'tv_asahi_news',
    {
        signApiKey: 'your-api-key',
        authenticateWs: true,
        session: {
            cookie: {
                type: 'cookie',
                value: {
                    sessionId: '<account_session_id>',
                    ttTargetIdc: '<account_target_idc>'
                }
            }
        }
    }
);

await connection.connect();
console.log('Connected to TikTok LIVE chat!');

You can also set the session after construction by calling setSessionBundle on the cookie jar:

await connection.webClient.cookieJar.setSessionBundle({
    type: 'cookie',
    value: {
        sessionId: '<account_session_id>',
        ttTargetIdc: '<account_target_idc>'
    }
});

Send Messages

sendMessage posts a chat message into the currently connected room. It requires a valid Euler Stream API key (see Signing Configuration) and an authenticated session bundle (cookies or OAuth token).

import { TikTokLiveConnection } from 'tiktok-live-connector';

const connection = new TikTokLiveConnection(
    'tv_asahi_news',
    {
        signApiKey: 'your-api-key',
        authenticateWs: true,
        session: {
            cookie: {
                type: 'cookie',
                value: {
                    sessionId: '<account_session_id>',
                    ttTargetIdc: '<account_target_idc>'
                }
            }
        }
    }
);

await connection.connect();
await connection.sendMessage('Hello world!');
console.log('Message sent!');

Frequently Asked Questions

Is there an official TikTok LIVE API?

TikTok does not offer a public official API for reading livestream events. TikTokLiveConnector is an unofficial, open-source TikTok LIVE API client that reads the same Webcast data available to any viewer of a stream.

How do I read TikTok live chat messages in Node.js?

Install with npm i tiktok-live-connector, create a TikTokLiveConnection with the streamer's @uniqueId, and listen for WebcastEvent.CHAT. See Getting Started above — it takes about ten lines of code.

Can I track TikTok gifts, likes and viewer counts in real time?

Yes. GIFT (with streak handling), LIKE and ROOM_USER deliver gifts, likes and live viewer counts as they happen, alongside follows, shares, subscriptions, questions and battles.

Does it work without logging in?

Yes. No credentials, cookies or app registration are required to read a public livestream. Authentication is only needed to send chat messages, which additionally requires a sign API key — see Send Messages.

Is it free?

Yes, the library is free and open source. Connecting requires a signed WebSocket token, provided by Euler Stream with free community rate limits; an API key raises those limits.

Is it production-ready?

The library is a reverse-engineering project and TikTok can change the Webcast protocol without notice. For workloads that need an uptime guarantee, use the managed TikTok LIVE WebSocket API, which handles signing, scaling and protocol drift for you.

Is this available in other languages?

Yes — see Do you prefer other programming languages? for the Python, Java, Go and C# ports.

Contributors

• Zerody - Initial Reverse-Engineering and Protobuf-Decoding - Zerody
• Isaac Kogan - TypeScript Rewrite, Sign-Server Maintainer - isaackogan
• sleepylessons - Docs & QoL Updates - sleepylessons

License

This project is licensed under a modified AGPL License. See the LICENSE file for details.