Quickstart

Build your first TikTok livestream client and start receiving events in minutes

This guide walks you through creating a basic TikTok livestream client that connects to a live broadcast and handles real-time events like comments, gifts, and likes.

Prerequisites

Before starting, make sure you have:

• Python 3.10 or higher installed
• TikTokLive installed (pip install TikTokLive)
• A TikTok username to connect to (use @tv_asahi_news for testing)

Create Your First Client

1. Import the library

   Create a new Python file and import the necessary components:

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

   The TikTokLiveClient is the main class for connecting to livestreams. Events like ConnectEvent and CommentEvent represent different actions that occur during a broadcast.

2. Initialize the client

   Create a client instance with the unique ID of the TikTok user whose livestream you want to monitor:

   client = TikTokLiveClient(unique_id="@isaackogz")
   

   The unique_id is the username visible in the TikTok URL. For example, @isaackogz from https://www.tiktok.com/@isaackogz.

3. Add event listeners

   Define async functions to handle events. You can use decorators or add listeners manually:

   Decorator Method

   @client.on(ConnectEvent)
   async def on_connect(event: ConnectEvent):
       print(f"Connected to @{event.unique_id} (Room ID: {client.room_id})")
   
   @client.on(CommentEvent)
   async def on_comment(event: CommentEvent):
       print(f"{event.user.nickname} -> {event.comment}")
   

   All event handlers must be async functions since TikTokLive uses asyncio for non-blocking operations.

4. Run the client

   Start the client and connect to the livestream:

   if __name__ == '__main__':
       # Run the client and block the main thread
       client.run()
   

   The run() method connects to the livestream and blocks the main thread until the stream ends or you manually disconnect.

Complete Example

Here’s the full working code:

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

# Create the client
client = 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})")


@client.on(CommentEvent)
async def on_comment(event: CommentEvent):
    print(f"{event.user.nickname} -> {event.comment}")


if __name__ == '__main__':
    # Run the client and block the main thread
    client.run()

Make sure the user is currently live before running your client. If they’re offline, the connection will fail. See Checking Live Status to learn how to check if a user is live.

Handling More Events

TikTokLive supports 100+ event types. Here are some commonly used ones:

from TikTokLive.events import (
    ConnectEvent,
    DisconnectEvent,
    CommentEvent,
    GiftEvent,
    LikeEvent,
    FollowEvent,
    ShareEvent,
    JoinEvent
)

@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
    # Check if gift streak is over
    if event.gift.streakable and not event.streaking:
        print(f"{event.user.nickname} sent {event.repeat_count}x {event.gift.name}")
    elif not event.gift.streakable:
        print(f"{event.user.nickname} sent {event.gift.name}")

@client.on(LikeEvent)
async def on_like(event: LikeEvent):
    print(f"{event.user.nickname} liked the stream")

@client.on(FollowEvent)
async def on_follow(event: FollowEvent):
    print(f"{event.user.nickname} followed the host")

@client.on(ShareEvent)
async def on_share(event: ShareEvent):
    print(f"{event.user.nickname} shared the stream")

@client.on(DisconnectEvent)
async def on_disconnect(event: DisconnectEvent):
    print("Disconnected from the livestream")

Non-Blocking Connection

If you want to run the client without blocking your main thread, use start() instead of run():

import asyncio
from TikTokLive import TikTokLiveClient
from TikTokLive.events import ConnectEvent

client = TikTokLiveClient(unique_id="@isaackogz")

@client.on(ConnectEvent)
async def on_connect(event: ConnectEvent):
    print(f"Connected to @{event.unique_id}")

async def main():
    # Start client without blocking
    task = await client.start()
    
    # Do other async work here
    await asyncio.sleep(60)
    
    # Disconnect when done
    await client.disconnect()

if __name__ == '__main__':
    asyncio.run(main())

Enabling Debug Logging

To see detailed connection logs and debug information:

from TikTokLive import TikTokLiveClient
from TikTokLive.client.logger import LogLevel

client = TikTokLiveClient(unique_id="@isaackogz")

# Set log level to INFO or DEBUG
client.logger.setLevel(LogLevel.INFO.value)

if __name__ == '__main__':
    client.run()

Next Steps

Core Concepts

Learn about the TikTokLiveClient and its properties

Event Handling

Master event listeners and handlers

Handling Gifts

Learn about gift streaks and metadata

Error Handling

Handle connection errors and exceptions