TikTokLive Python API (Unofficial)

TikTokLive is an unofficial Python API wrapper for TikTok LIVE written in Python. With this library you can connect to any TikTok livestream and fetch all data available to users in a stream using just a creator's @unique_id.

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

<!-- <a href="https://www.eulerstream.com/websockets" target="_blank"> <img src="https://www.eulerstream.com/api/advert?l2=WebSocket+API&r=15&b=1.5&bc=404854&o=0.95"/> </a> -->

TikTok LIVE API

<table> <tr> <td><br/><img width="180px" style="border-radius: 10px" src="https://raw.githubusercontent.com/isaackogan/TikTokLive/master/.github/SquareLogo.png"><br/><br/></td> <td> <a href="https://www.eulerstream.com/"> <strong>Euler Stream</strong> offers a comprehensive TikTok LIVE API, WebSocket Server, CAPTCHA Solutions and much more! </a> </td> </tr> </table> <!-- Temporarily Removed May 3rd 2025 ## Author's Choice The following are my two favourite enterprise use-cases for the TikTokLive family of libraries. This is <strong>not</strong> paid promotion, and I receive nothing for these recommendations: <table> <tr> <td><br/><img width="180px" style="border-radius: 10px" src="https://tiktory.com/images/meta/favicon.svg"><br/><br/></td> <td> <a href="https://www.tiktory.com"> <strong>Tiktory</strong> provides highly advanced custom overlays, follower alerts, and real-time goal tracking. Seamlessly integrate with OBS and stand out from the crowd! </a> </td> </tr> </table> <table> <tr> <td><br/><img width="180px" style="border-radius: 10px" src="https://cdn.casterlabs.co/branding/casterlabs/icon.svg"><br/><br/></td> <td> <a href="https://casterlabs.co/"> <strong>Casterlabs</strong> is a powerful tool that unifies chats from various streaming platforms, providing a combined chat view, customizable alerts, and handy on-screen widgets for streamers! </a> </td> </tr> </table> -->

Table of Contents

• Getting Started
  • Parameters
  • Methods
  • Properties
  • WebDefaults
• Documentation
• Other Languages
• Community
• Examples
• Licensing
• Star History
• Contributors

Community

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

Getting Started

1. Install the module via pip from the PyPi repository

pip install TikTokLive

2. Create your first 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, see the examples folder provided in the source tree.

Other Languages

TikTokLive is available in several alternate programming languages:

• Node.JS: https://github.com/zerodytrash/TikTok-Live-Connector
• Java: https://github.com/jwdeveloper/TikTok-Live-Java
• C#/Unity: https://github.com/frankvHoof93/TikTokLiveSharp
• Go: https://github.com/steampoweredtaco/gotiktoklive
• Rust: https://github.com/jwdeveloper/TikTokLiveRust

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. |

Web