Skip to content
Projects

zerodytrash/TikTok-Live-Connector

View on GitHub

zerodytrash/TikTok-Live-Connector has 2,302 GitHub stars and 497 forks. GitHot measured +34 in 7 days. Last checked 2026-11-11 10:58 UTC. Last push 2026-10-19.

How these counts are measured

TikTok LIVE API for Node.js: An unofficial library to receive live stream events (comments, gifts, etc.) in realtime from TikTok LIVE.

2,302 stars497 forks

Measured star growth

in 24h
Update delayed
in 7 days
+34
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

README.md

Original

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.

Discord Connections Downloads Stars Issues Forks

[!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?

Table of Contents

Getting Started

  1. Install the package via NPM
npm i tiktok-live-connector
  1. 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.

Message Events:

See the message event reference for payloads and examples.

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.

Explore related projects

codecrafters-io/build-your-own-x

Master programming by recreating your favorite technologies from scratch.

561,728 stars

public-apis/public-apis

A collective list of free APIs

498,148 stars

morluto/rea

Reverse engineer anything with agents, from app behavior down to native binaries.

451,531 stars

openclaw/openclaw

The AI that really does things. Any OS. Any Platform. The lobster way. 🦞

394,331 stars