TikTok LIVE API for Python: Real-Time Livestream Events (Unofficial)

TikTok LIVE API (TikTokLive) is the #1 TikTok LIVE client for Python. Connect to any TikTok LIVE stream and receive real-time chat messages, gifts, likes, follows, shares, viewer counts, battles, and more using just a creator's @unique_id. No login, no credentials or app are required.

TikTokLive is the definitive third-party Python library for reading the TikTok LIVE websocket, building TikTok chat bots, gift trackers, live stream overlays, alerts, and analytics tools.

Discord Live TikTok LIVE API connections TikTokLive PyPI downloads TikTokLive GitHub stars TikTokLive GitHub forks TikTokLive open issues

Note: This is not a production-ready API. It is a reverse engineering project. Use the WebSocket API for production by Euler Stream.

What Can You Build With the TikTok LIVE API?

TikTok LIVE API for Production


Euler Stream TikTok LIVE API logo

 Euler Stream offers a comprehensive TikTok LIVE API, WebSocket Server, CAPTCHA Solutions and much more!

Table of Contents

Community

Join the TikTokLive discord and visit the #py-support channel for questions, contributions and ideas.

Getting Started

Install the TikTok LIVE API client for Python via pip from the PyPi repository:

pip install TikTokLive

Then create your first real-time TikTok LIVE chat connection:

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

# Create the client
client: TikTokLiveClient = TikTokLiveClient(unique_id="@isaackogz")


# Listen to an event with a decorator!
@client.on(ConnectEvent)
async def on_connect(event: ConnectEvent):
    print(f"Connected to @{event.unique_id} (Room ID: {client.room_id}")


# Or, add it manually via "client.add_listener()"
async def on_comment(event: CommentEvent) -> None:
    print(f"{event.user.nickname} -> {event.comment}")


client.add_listener(CommentEvent, on_comment)

if __name__ == '__main__':
    # Run the client and block the main thread
    # await client.start() to run non-blocking
    client.run()

For more quickstart examples, including a TikTok live chat reader, gift tracker, and live status checker, see the examples folder provided in the source tree.

TikTok LIVE API in Other Languages: Node.js, Java, C#, Go, Rust

The TikTokLive TikTok LIVE API is available in several alternate programming languages:

Parameters

Param Name Required Default Description
unique_id Yes N/A The unique username of the broadcaster. You can find this name in the URL of the user. For example, the unique_id for https://www.tiktok.com/@isaackogz would be isaackogz.
web_proxy No None TikTokLive supports proxying HTTP requests. This parameter accepts an httpx.Proxy. Note that if you do use a proxy you may be subject to reduced connection limits at times of high load.
ws_proxy No None TikTokLive supports proxying the websocket connection. This parameter accepts an httpx.Proxy. Using this proxy will never be subject to reduced connection limits.
web_kwargs No {} Under the scenes, the TikTokLive HTTP client uses the httpx library. Arguments passed to web_kwargs will be forward the the underlying HTTP client.
ws_kwargs No {} Under the scenes, TikTokLive uses the websockets library to connect to TikTok. Arguments passed to ws_kwargs will be forwarded to the underlying WebSocket client.

Methods

A TikTokLiveClient object contains the following methods worth mentioning:

Method Name Notes Description
run N/A Connect to the livestream and block the main thread. This is best for small scripts.
add_listener N/A Adds an asynchronous listener function (or, you can decorate a function with @client.on(Type[Event])) and takes two parameters, an event name and the payload, an AbstractEvent
connect async Connects to the tiktok live chat while blocking the current future. When the connection ends (e.g. livestream is over), the future is released.
start async Connects to the live chat without blocking the main thread. This returns an asyncio.Task object with the client loop.
disconnect async Disconnects the client from the websocket gracefully, processing remaining events before ending the client loop.

Properties

A TikTokLiveClient object contains the following important properties:

Attribute Name Description
room_id The Room ID of the livestream room the client is currently connected to.
web The TikTok HTTP client. This client has a lot of useful routes you should explore!
connected Whether you are currently connected to the livestream.
logger The internal logger used by TikTokLive. You can use client.logger.setLevel(...) method to enable client debug.
room_info Room information that is retrieved from TikTok when you use a connection method (e.g. client.connect) with the keyword argument fetch_room_info=True .
gift_info Extra gift information that is retrieved from TikTok when you use a connection method (e.g. client.run) with the keyword argument fetch_gift_info=True.

WebDefaults

TikTokLive has a series of global defaults used to create the HTTP client which you can customize. For info on how to set these parameters, see the web_defaults.py example.

Parameter Type Description
tiktok_sign_api_key str A Euler Stream API key used to increase rate limits.
tiktok_app_url str The TikTok app URL (https://www.tiktok.com) used to scrape the room.
tiktok_sign_url str The signature server used to generate tokens to connect to TikTokLive. By default, this is Euler Stream, but you can swap your own with ease.
tiktok_webcast_url str The TikTok livestream URL (https://webcast.tiktok.com) where livestreams can be accessed from.
web_client_params dict The URL parameters added on to TikTok requests from the HTTP client.
web_client_headers dict The headers added on to TikTok requests from the HTTP client.
web_client_cookies dict Custom cookies to initialize the http client with.
ws_client_params dict The URL parameters added to the URI when connecting to TikTok's Webcast WebSocket server.
ws_client_params_append_str dict Extra string data to append to the TikTokLive WebSocket connection URI.
ws_client_headers dict Extra headers to append to the TikTokLive WebSocket client.

Events

The TikTok LIVE API emits real-time events for everything happening in a livestream: comments, gifts, likes, joins, follows, shares, battles (PK), polls, captions, subscriptions, and moderation actions. Events can be listened to using a decorator or non-decorator method call. The following examples illustrate how you can listen to an event:

@client.on(LikeEvent)
async def on_like(event: LikeEvent) -> None:
    ...


async def on_comment(event: CommentEvent) -> None:
    ...


client.add_listener(CommentEvent, on_comment)

There are two types of events, CustomEvent events and ProtoEvent events. Both belong to the TikTokLive Event type and can be listened to. The following events are available:

Custom Events

Proto Events

These events are auto-generated from the TikTokLiveProto v3 schema. Only events whose proto messages are present in v3 are emitted; if you don't see one you used to rely on, it's because TikTok removed it from the schema.

If you know what an event does that's missing a description below, make a pull request and add it.

New in 7.X.X

GiftEvent

Fires every time a gift is sent. Extra static metadata for every gift type in the room can be fetched once on connect by passing fetch_gift_info=True to client.run() / client.start(); the result is cached on client.gift_info.

Streaks: streakable gifts trigger multiple GiftEvents as the viewer ramps up the streak, with event.repeat_count incrementing each time. The final gift in a streak carries event.repeat_end == 1. Use the event.streaking helper to filter intermediate events out and only act on the final one.

@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
    gift = event.gift
    if gift is None:
        return

    # Streakable gift & streak is over
    if not event.streaking and gift.type == 1:  # ``type == 1`` is streakable
        print(f"{event.user.unique_id} sent {event.repeat_count}x \"{gift.name}\"")

    # Non-streakable gift
    elif gift.type != 1:
        print(f"{event.user.unique_id} sent \"{gift.name}\"")

In v3 the canonical Gift field names are name, type, and image. The v2-era prefixed names (gift_name, gift_type, gift_image) remain available as read-only aliases on ExtendedGift for backwards compatibility. Wrap a Gift in ExtendedGift(...) if you want the .streakable helper.

Checking If A User Is Live

It is considered inefficient to use the connect method to check if a user is live. It is better to use the dedicated await client.is_live() method.

There is a complete example of how to do this in the examples folder.

Frequently Asked Questions

Is there an official TikTok LIVE API?

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

How do I get TikTok LIVE chat messages in Python?

Install with pip install TikTokLive, create a TikTokLiveClient with the streamer's @unique_id, and listen for CommentEvent. See the Getting Started example above; it takes about ten lines of code.

Is the TikTok LIVE API free?

Yes. TikTokLive is free and open source under a modified AGPL license. Signing is handled by a third-party signature server (Euler Stream) with free community rate limits; an API key raises those limits.

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

Yes. GiftEvent (with streak handling), LikeEvent, and RoomUserSeqEvent deliver gifts, likes, and live viewer counts as they happen, alongside 50+ other event types including battles, polls, captions, and subscriptions.

Does this work with Node.js, Java, C#, Go, or Rust?

Yes, sister libraries exist for each. See Other Languages.

Star History

TikTokLive GitHub star history chart: growth of the TikTok LIVE API for Python

License

This project is licensed under a modified AGPL license - see the LICENSE file for details.

Contributors

See also the full list of secondary contributors who have participated in this project.