Skip to main content

​
Introduction

The TikTokLive Python SDK provides a robust event system for handling real-time events from TikTok LIVE streams. Events are triggered when various actions occur during a livestream, such as comments, gifts, likes, and user interactions.

​
Event Types

There are two main categories of events in TikTokLive:

​
Custom Events

Custom events are manually triggered by the SDK for connection lifecycle management:
  • ConnectEvent - Fired when successfully connected to a stream
  • DisconnectEvent - Fired when disconnecting from a stream
  • LiveEndEvent - Fired when the livestream ends
  • LivePauseEvent - Fired when the stream is paused
  • LiveUnpauseEvent - Fired when a paused stream resumes
  • FollowEvent - Fired when a user follows the streamer
  • ShareEvent - Fired when a user shares the stream
  • SuperFanEvent - Fired for super fan interactions
  • UnknownEvent - Fired for untracked message types
  • WebsocketResponseEvent - Fired for any WebSocket event

​
Proto Events

Proto events are generated from TikTok’s protocol buffers and represent real-time stream interactions. These include:
  • Chat & Comments - CommentEvent, EmoteChatEvent, ScreenChatEvent
  • Gifts - GiftEvent, GiftUpdateEvent, GiftBroadcastEvent
  • Engagement - LikeEvent, DiggEvent, JoinEvent
  • Social - FollowEvent, ShareEvent, SocialEvent
  • Room Updates - RoomEvent, RoomPinEvent, RoomNotifyEvent
  • Battles & Games - LinkMicBattleEvent, GameMomentEvent
  • And 200+ more event types…

​
Listening to Events

To handle events, use the @client.on() decorator: 
from TikTokLive import TikTokLiveClient
from TikTokLive.events import ConnectEvent, CommentEvent, GiftEvent

client = TikTokLiveClient(unique_id="@username")

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

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

@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
    print(f"{event.user.nickname} sent {event.gift.name}!")

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

​
Event Base Class

All events inherit from BaseEvent, which provides common functionality and properties. Each event may have specific properties based on the event type.

​
Accessing Event Data

Most events provide structured data through properties: 
@client.on(CommentEvent)
async def on_comment(event: CommentEvent):
    # User information
    user = event.user_info
    print(f"User ID: {user.id}")
    print(f"Nickname: {user.nickname}")
    print(f"Profile Picture: {user.avatar_thumb.url_list[0]}")
    
    # Comment data
    print(f"Comment: {event.comment}")
    print(f"Is Super Fan: {event.user_is_super_fan}")

​
Error Handling

It’s recommended to wrap event handlers with try-except blocks: 
@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
    try:
        # Your event handling logic
        process_gift(event)
    except Exception as e:
        print(f"Error handling gift: {e}")

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us