Skip to main content

​
Overview

The TikTokLiveClient is the core class for connecting to and interacting with TikTok LIVE streams. It handles WebSocket connections, HTTP requests, event management, and provides a simple interface for reading live stream data.

​
Creating a Client

​
Basic Initialization

from TikTokLive import TikTokLiveClient

# Create a client for a specific user
client = TikTokLiveClient(unique_id="@username")

​
Constructor Parameters

​
unique_id
str | int
required
The username or user ID of the creator to connect to. Can include @ prefix and /live suffix - these will be automatically stripped.
​
platform
WebcastPlatform
default:"WebcastPlatform.WEB"
The platform to connect from (WEB or APP).
​
web_proxy
httpx.Proxy
default:"None"
Optional proxy for HTTP requests.
​
ws_proxy
WebcastProxy
default:"None"
Optional proxy for WebSocket connections.
​
web_kwargs
dict
default:"None"
Additional arguments for the HTTP client.
​
ws_kwargs
dict
default:"None"
Additional arguments for the WebSocket client.
​
is_user_id
bool
default:"False"
Whether to resolve a user ID to a unique_id (username).

​
Example with Options

import httpx
from TikTokLive import TikTokLiveClient
from TikTokLive.client.web.routes.fetch_signed_websocket import WebcastPlatform

client = TikTokLiveClient(
    unique_id="username",
    platform=WebcastPlatform.WEB,
    web_proxy=httpx.Proxy("http://proxy.example.com:8080")
)

​
Client Properties

​
Connection State

​
connected
bool
Whether the WebSocket client is currently connected to TikTok.
if client.connected:
    print("Client is connected")

​
User Information

​
unique_id
str
The cleaned unique ID (username) of the connected user.
print(f"Connected to: {client.unique_id}")
​
room_id
Optional[int]
The room ID of the current livestream. None if not connected.
print(f"Room ID: {client.room_id}")

​
Stream Data

​
room_info
Optional[dict]
Room information if fetch_room_info=True was passed to start(), connect(), or run().
if client.room_info:
    print(client.room_info)
​
gift_info
Optional[dict]
Gift information if fetch_gift_info=True was passed to start(), connect(), or run().
if client.gift_info:
    print(client.gift_info)

​
Internal Components

​
web
TikTokWebClient
The HTTP client used for requests.
# Access the web client
web_client = client.web
​
logger
logging.Logger
The internal logger used by TikTokLive.
from TikTokLive.client.logger import LogLevel

# Access and configure the logger
client.logger.setLevel(LogLevel.INFO)

​
Client Configuration

​
Error Handling

# Ignore broken payload errors (not recommended for production)
client.ignore_broken_payload = True
Setting ignore_broken_payload = True will suppress payload parsing errors. This is useful for debugging but should be avoided in production as it may hide important issues.

​
Utility Methods

​
Check Live Status

# Check if a user is currently live
is_live = await client.is_live()
print(f"User is live: {is_live}")

# Check if a different user is live
is_other_live = await client.is_live("other_username")

​
Send Chat Message

# Send a chat message to the room
await client.send_room_chat("Hello from TikTokLive!")
The send_room_chat() method requires appropriate authentication and permissions. It may not work for all users or streams.

​
Event Listener Methods

​
Check for Listeners

from TikTokLive.events import CommentEvent

# Check if the client is listening to a specific event
if client.has_listener(CommentEvent):
    print("Listening to comments")

​
Best Practices

Use Context Managers

Always close the client properly using await client.close() or use async context managers when available.

Handle Exceptions

Catch AlreadyConnectedError, UserOfflineError, and UserNotFoundError when connecting.

Configure Logging

Set appropriate log levels for development vs production environments.

Reuse Clients

Disconnect and reconnect the same client instance instead of creating new instances.

Connection Lifecycle

Learn about starting, connecting, and disconnecting

Event Handling

Understand how to register and handle events

Events Overview

Explore all available events

Build docs developers (and LLMs) love

Get started for freeTalk to us