Skip to main content

​
Overview

Custom events are manually triggered by the TikTokLive SDK to provide connection lifecycle management and special interaction handling. These events are defined in TikTokLive/events/custom_events.py.

​
Connection Events

​
ConnectEvent

Triggered when the client successfully connects to a TikTok LIVE stream and receives the first payload from the Sign Server. Properties:
  • unique_id (str) - The unique username of the streamer
  • room_id (int) - The room ID of the livestream
Example: 
from TikTokLive.events import ConnectEvent

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

​
DisconnectEvent

Triggered when the client disconnects from a TikTok LIVE stream. Example: 
from TikTokLive.events import DisconnectEvent

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

​
Stream Control Events

​
LiveEndEvent

Triggered when the livestream ends. Inherits from ControlEvent. Example: 
from TikTokLive.events import LiveEndEvent

@client.on(LiveEndEvent)
async def on_live_end(event: LiveEndEvent):
    print("Stream has ended")

​
LivePauseEvent

Triggered when the livestream is paused by the streamer. Inherits from ControlEvent. Example: 
from TikTokLive.events import LivePauseEvent

@client.on(LivePauseEvent)
async def on_pause(event: LivePauseEvent):
    print("Stream paused")

​
LiveUnpauseEvent

Triggered when a paused livestream resumes. Inherits from ControlEvent. Example: 
from TikTokLive.events import LiveUnpauseEvent

@client.on(LiveUnpauseEvent)
async def on_unpause(event: LiveUnpauseEvent):
    print("Stream resumed")

​
Social Interaction Events

​
FollowEvent

Triggered when a user follows the streamer during the livestream. Inherits from SocialEvent. Example: 
from TikTokLive.events import FollowEvent

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

​
ShareEvent

Triggered when a user shares the livestream. Inherits from SocialEvent. Properties:
  • users_joined (Optional[int]) - Number of people who joined the stream from the share
Example: 
from TikTokLive.events import ShareEvent

@client.on(ShareEvent)
async def on_share(event: ShareEvent):
    print(f"{event.user.nickname} shared the stream!")
    if event.users_joined:
        print(f"{event.users_joined} users joined from the share")

​
SuperFanEvent

Triggered for super fan interactions. This is a specialized BarrageEvent with its own class for clarity. Example: 
from TikTokLive.events import SuperFanEvent

@client.on(SuperFanEvent)
async def on_super_fan(event: SuperFanEvent):
    print("Super fan interaction detected!")

​
Special Events

​
WebsocketResponseEvent

Triggered for any event received from the WebSocket connection. This is the base event for all WebSocket messages. Example: 
from TikTokLive.events import WebsocketResponseEvent

@client.on(WebsocketResponseEvent)
async def on_websocket_event(event: WebsocketResponseEvent):
    # Handle any WebSocket event
    print(f"Received event: {type(event).__name__}")

​
UnknownEvent

Triggered when a Webcast message is received that is not yet tracked by TikTokLive. Inherits from WebsocketResponseEvent. Example: 
from TikTokLive.events import UnknownEvent

@client.on(UnknownEvent)
async def on_unknown(event: UnknownEvent):
    print("Received an unknown event type")
    # Log for debugging purposes

​
Event Hierarchy

Custom events inherit from base proto events: 
BaseEvent
├── WebsocketResponseEvent
│   └── UnknownEvent
├── ConnectEvent
├── DisconnectEvent
├── ControlEvent
│   ├── LiveEndEvent
│   ├── LivePauseEvent
│   └── LiveUnpauseEvent
├── SocialEvent
│   ├── FollowEvent
│   └── ShareEvent
└── BarrageEvent
    └── SuperFanEvent

​
Usage Tips

  • ConnectEvent is ideal for initialization logic when connecting to a stream
  • DisconnectEvent is useful for cleanup operations
  • LiveEndEvent helps detect when a stream has finished
  • UnknownEvent is helpful for debugging new TikTok features

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us