Skip to main content

​
Event Architecture

TikTokLive uses an event-driven architecture built on top of pyee.AsyncIOEventEmitter. When you connect to a live stream, the client receives WebSocket messages from TikTok and converts them into Python event objects that you can handle.

​
Event Types

There are two main categories of events:

​
Proto Events

Proto events are automatically generated from TikTok’s protobuf messages. These represent the raw data structures sent by TikTok’s servers. 
from TikTokLive.events import (
    CommentEvent,      # Chat messages
    GiftEvent,         # Virtual gifts
    JoinEvent,         # User joins
    LikeEvent,         # Likes
    ShareEvent,        # Shares
    FollowEvent,       # Follows
)

​
Custom Events

Custom events are specially processed events that provide additional context or represent important state changes. 
from TikTokLive.events import (
    ConnectEvent,         # When connection is established
    DisconnectEvent,      # When disconnected
    LiveEndEvent,         # Stream ends
    LivePauseEvent,       # Stream paused
    LiveUnpauseEvent,     # Stream unpaused
    UnknownEvent,         # Unknown message type
    WebsocketResponseEvent, # Raw WebSocket response
)

​
Common Events

Triggered when a user sends a chat message.
@client.on(CommentEvent)
async def on_comment(event: CommentEvent):
    print(f"{event.user_info.nickname}: {event.comment}")
    print(f"Is super fan: {event.user_is_super_fan}")
Key Properties:
  • comment / content: The message text
  • user_info: User who sent the comment
  • user_is_super_fan: Whether user is a subscriber
Triggered when a user sends a virtual gift.
@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
    # Only process when the gift streak ends
    if event.gift.streakable and not event.streaking:
        print(f"{event.from_user.nickname} sent {event.repeat_count}x {event.gift.name}")
        print(f"Total value: ${event.value:.2f}")
Key Properties:
  • gift / m_gift: The gift object
  • from_user: User who sent the gift
  • to_user: Gift recipient
  • repeat_count: Number in streak
  • streaking: Whether still in progress
  • value: USD value (only when streak ends)
Triggered when a user joins the livestream.
@client.on(JoinEvent)
async def on_join(event: JoinEvent):
    print(f"{event.user.nickname} joined!")
Key Properties:
  • user: User who joined
  • operator: User who performed the action
Triggered when a user likes the stream.
@client.on(LikeEvent)
async def on_like(event: LikeEvent):
    print(f"{event.user.nickname} liked the stream!")
Key Properties:
  • user: User who liked
  • count: Number of likes
Triggered when a user follows the streamer.
@client.on(FollowEvent)
async def on_follow(event: FollowEvent):
    print(f"{event.user.nickname} followed!")
Triggered when a user shares the stream.
@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 this share")

​
Lifecycle Events

ConnectEvent

Emitted when successfully connected to the stream.
@client.on(ConnectEvent)
async def on_connect(event: ConnectEvent):
    print(f"Connected to {event.unique_id}")
    print(f"Room ID: {event.room_id}")

DisconnectEvent

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

LiveEndEvent

Emitted when the livestream ends.
@client.on(LiveEndEvent)
async def on_live_end(event: LiveEndEvent):
    print("Stream has ended")

LivePauseEvent

Emitted when the stream is paused.
@client.on(LivePauseEvent)
async def on_pause(event: LivePauseEvent):
    print("Stream paused")

​
Base Event Properties

All events inherit from BaseEvent and share these properties:
​
type
str
The event class name (e.g., “CommentEvent”, “GiftEvent”).
​
bytes
Optional[bytes]
The raw protobuf payload bytes if available.
​
as_base64
str
Base64-encoded representation of the payload.
​
size
int
Size of the payload in bytes.

​
Example

@client.on(CommentEvent)
async def on_comment(event: CommentEvent):
    print(f"Event type: {event.type}")
    print(f"Payload size: {event.size} bytes")

​
Event Flow

1

WebSocket Message

TikTok server sends a protobuf message via WebSocket
2

Message Parsing

Client parses the protobuf message and identifies the type
3

Event Creation

An appropriate event object is instantiated from the parsed data
4

Custom Event Processing

If applicable, additional custom events are derived (e.g., FollowEvent from SocialEvent)
5

Event Emission

All relevant events are emitted to registered listeners
6

Handler Execution

Your event handler functions are called with the event object

​
Special Events

​
WebsocketResponseEvent

This event is emitted for every WebSocket message received, regardless of type. It’s useful for debugging or logging all activity. 
@client.on(WebsocketResponseEvent)
async def on_websocket_response(event: WebsocketResponseEvent):
    print(f"Received message: {event.method}")

​
UnknownEvent

Emitted when TikTok sends a message type that TikTokLive doesn’t recognize yet. 
@client.on(UnknownEvent)
async def on_unknown(event: UnknownEvent):
    print(f"Unknown event: {event.method}")
If you encounter UnknownEvent messages frequently, consider reporting them to the TikTokLive maintainers so they can add support for new event types.

​
Complete Event List

TikTokLive supports over 200 different event types. Here are some additional notable ones:
  • DiggEvent - When users “dig” (tap) the screen
  • GoalUpdateEvent - Stream goal progress updates
  • PollEvent - Poll-related events
  • RoomPinEvent - Pinned message events
  • SubNotifyEvent - Subscription notifications
  • EmoteChatEvent - Emote messages
  • LinkMicBattleEvent - Battle events during co-hosting
  • RankUpdateEvent - Ranking changes
For a complete list of all events, see the Events API Reference.

​
Next Steps

Event Handling

Learn how to register and handle events

Connection Lifecycle

Understand the connection process

Build docs developers (and LLMs) love

Get started for freeTalk to us