Custom Events

Custom lifecycle and control events in TikTokLive

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

• Explore Proto Events for interaction events
• See the Client Reference for connection configuration
• Learn about Event System Overview