Proto Events - TikTokLive

Overview

Proto events are automatically generated from TikTok’s protocol buffers and represent real-time interactions in a TikTok LIVE stream. These events are defined in TikTokLive/events/proto_events.py and include over 200 different event types.

Most Common Events

CommentEvent

Triggered when a user sends a chat message in the livestream. Properties:

user_info (ExtendedUser) - Information about the user who commented
at_user (ExtendedUser) - User mentioned in the comment (if any)
content (str) - The comment text
comment (str) - Alias for content
user_is_super_fan (bool) - Whether the user is a TikTok super fan

Example:

from TikTokLive.events import CommentEvent

@client.on(CommentEvent)
async def on_comment(event: CommentEvent):
    print(f"{event.user_info.nickname}: {event.comment}")
    if event.user_is_super_fan:
        print("This user is a super fan!")

GiftEvent

Triggered when a user sends a gift during the livestream. Properties:

from_user (ExtendedUser) - User who sent the gift
to_user (ExtendedUser) - User receiving the gift (streamer)
gift (Gift) - The gift object
repeat_count (int) - Number of gifts in the batch
repeat_end (bool) - Whether the gift streak has ended
streaking (bool) - Whether the gift is part of an ongoing streak
value (Optional[float]) - USD value of the gift (None during streaks)
user_is_super_fan (bool) - Whether the sender is a super fan

Example:

from TikTokLive.events import GiftEvent

@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
    print(f"{event.from_user.nickname} sent {event.gift.name}")
    print(f"Count: {event.repeat_count}")
    
    if not event.streaking and event.value:
        print(f"Value: ${event.value:.2f}")

LikeEvent

Triggered when a user likes the livestream. Properties:

user (ExtendedUser) - User who liked
count (int) - Number of likes
total (int) - Total likes

Example:

from TikTokLive.events import LikeEvent

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

JoinEvent

Triggered when a user joins the livestream. Properties:

user (ExtendedUser) - User who joined
operator (ExtendedUser) - Operator information

Example:

from TikTokLive.events import JoinEvent

@client.on(JoinEvent)
async def on_join(event: JoinEvent):
    print(f"{event.user.nickname} joined the stream!")

FollowEvent

Triggered when a user follows the streamer (proto version). Properties:

user (ExtendedUser) - User who followed

Example:

from TikTokLive.events import FollowEvent

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

ShareEvent

Triggered when a user shares the stream (proto version). Properties:

user (ExtendedUser) - User who shared
users_joined (Optional[int]) - Number of users who joined 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!")

Room & Control Events

ControlEvent

General control messages for stream state changes.

RoomEvent

General room state updates.

RoomPinEvent

Triggered when a message is pinned in the room.

operator (ExtendedUser) - User who pinned the message

RoomNotifyEvent

Room notification messages.

user (ExtendedUser) - User associated with the notification

RoomUserSeqEvent

User sequence updates in the room.

RoomVerifyEvent

Room verification status updates.

RoomBottomEvent

Bottom banner updates.

Social & Engagement Events

Gift & Economy Events

GiftUpdateEvent

Gift panel/availability updates.

GiftBroadcastEvent

Broadcast notifications for special gifts.

GiftCollectionUpdateEvent

Gift collection progress updates.

GiftDynamicRestrictionEvent

Dynamic gift sending restrictions.

GiftGalleryEvent

Gift gallery display events.

user (ExtendedUser) - User associated with the gallery
to_user (ExtendedUser) - Target user

GiftGuideEvent

Gift sending guidance messages.

GiftNoticeEvent

Gift notification messages.

GiftPanelUpdateEvent

Gift panel UI updates.

GiftProgressEvent

Gift goal progress updates.

GiftPromptEvent

Gift sending prompts.

GiftRecordCapsuleEvent

Gift record capsule events.

GiftUnlockEvent

Gift unlock notifications.

GoalUpdateEvent

Stream goal progress updates.

GoodyBagEvent

Goody bag distribution events.

Battle & Competition Events

LinkMicBattleEvent

Triggered during link mic battles between streamers.

LinkMicArmiesEvent

Army/fan group events during battles.

LinkMicBattleItemCardEvent

Item card events during battles.

LinkMicBattlePunishFinishEvent

Battle punishment completion events.

LinkMicBattleVictoryLapEvent

Victory celebration events.

LinkmicBattleNoticeEvent

Battle notification messages.

LinkmicBattleTaskEvent

Battle task events.

Link & Collaboration Events

LinkEvent

General link/connection events.

LinkLayerEvent

Link layer updates.

LinkLayoutEvent

Link layout configuration changes.

LinkStateEvent

Link state changes.

LinkBusinessEvent

Business-related link events.

LinkScreenChangeEvent

Screen layout changes during links.

LinkMicAdEvent

Advertisement events during link mics.

LinkMicAnchorGuideEvent

Anchor guidance during link mics.

user (ExtendedUser) - Associated user

LinkMicMethodEvent

Link mic method calls.

LinkMicSignalingMethodEvent

Signaling method events.

LinkMicFanTicketMethodEvent

Fan ticket method events.

Game Events

GameMomentEvent

Game highlight moments.

GameEmoteUpdateEvent

Game emote updates.

GameGuessPinCardEvent

Guessing game pin card events.

GameGuessToastEvent

Guessing game toast notifications.

GameGuessWidgetsEvent

Guessing game widget updates.

GameOcrPingEvent

OCR ping events for games.

GameRankNotifyEvent

Game ranking notifications.

GameRecommendCreateGuessEvent

Recommendations to create guessing games.

GameReqSetGuessEvent

Request to set up guessing games.

GameServerFeatureEvent

Game server feature updates.

GameSettingChangeEvent

Game settings changes.

LiveGameIntroEvent

Live game introduction messages.

PreviewGameMomentEvent

Preview of game moments.

Shopping & Commerce Events

VideoLiveGoodsOrderEvent

Product order events.

user (ExtendedUser) - User who ordered

VideoLiveGoodsRcmdEvent

Product recommendation events.

VideoLiveCouponRcmdEvent

Coupon recommendation events.

EcBarrageEvent

E-commerce barrage messages.

EcDrawEvent

E-commerce draw/lottery events.

EcTaskRefreshCouponListEvent

Coupon list refresh events.

PaidContentLiveShoppingEvent

Paid content shopping events.

Interactive Features

PollEvent

Polling/voting events.

QuestionNewEvent

New Q&A questions.

QuestionSelectedEvent

Selected Q&A questions.

QuestionDeleteEvent

Deleted Q&A questions.

QuestionSlideDownEvent

Question slide-down animations.

QuestionSwitchEvent

Question switching events.

EnvelopeEvent

Red envelope events.

EnvelopePortalEvent

Envelope portal displays.

CapsuleEvent

Capsule/time capsule events.

Karaoke Events

KaraokeQueueEvent

Karaoke queue updates.

KaraokeQueueListEvent

Complete karaoke queue list.

KaraokeRedDotEvent

Karaoke notification indicators.

KaraokeReqEvent

Karaoke song requests.

KaraokeSwitchEvent

Karaoke mode switching.

KaraokeYouSingReqEvent

Requests for specific users to sing.

Ranking & Leaderboard Events

RankUpdateEvent

Ranking list updates.

RankTextEvent

Ranking text messages.

RankToastEvent

Ranking toast notifications.

HourlyRankRewardEvent

Hourly ranking rewards.

WeeklyRankRewardEvent

Weekly ranking rewards.

Miscellaneous Events

Miscellaneous Events (200+ Total)

AccessControlEvent

Access control changes.

AccessRecallEvent

Access recall notifications.

ActivityQuizCardEvent

Activity quiz card displays.

ActivityQuizUserIdentityEvent

Quiz user identity updates.

AiLiveSummaryEvent

AI-generated live summaries.

AiSummaryEvent

General AI summary events.

AnchorGetSubQuotaEvent

Anchor subscription quota updates.

AnchorGrowLevelEvent

Anchor growth level changes.

AnchorReminderWordEvent

Anchor reminder messages.

AnchorTaskReminderEvent

Anchor task reminders.

AnchorToolModificationEvent

Anchor tool modification events.

AssetEvent

Asset-related events.

from_user (ExtendedUser)
to_user (ExtendedUser)

AudienceReserveUserStateEvent

Audience reservation state changes.

AuthorizationNotifyEvent

Authorization notification events.

AvatarGenerateResultEvent

Avatar generation results.

AvatarReportDeleteEvent

Avatar report deletion events.

AvatarStyleResultEvent

Avatar style change results.

BaLeadGenEvent

Lead generation events.

BackpackEvent

Backpack/inventory events.

BizStickerEvent

Business sticker events.

BoostCardEvent

Boost card display events.

BoostedUsersEvent

Boosted user notifications.

BottomEvent

Bottom panel events.

CaptionEvent

Closed caption events.

CohostReserveEvent

Co-host reservation events.

CohostTopicEvent

Co-host topic events.

ColdStartEvent

Cold start optimization events.

CommentsEvent

Batch comment events.

user (ExtendedUser)

CommentTrayEvent

Comment tray updates.

CommercialCustomEvent

Custom commercial events.

CommonPopupEvent

Generic popup events.

CommonToastEvent

Generic toast notifications.

CompetitionEvent

Competition/contest events.

CountdownEvent

Countdown timer events.

CountdownForAllEvent

Global countdown events.

DonationEvent

Charity donation events.

DonationInfoEvent

Donation information updates.

DonationStickerModifyMethodEvent

Donation sticker modifications.

EffectControlEvent

Visual effect control events.

EffectPreloadingEvent

Effect preloading events.

EpiEvent

Episodic content events.

EventEvent

Generic event wrapper.

FansEventEvent

Fan event notifications.

user (ExtendedUser)

FeedUserRoomMonitorEvent

Feed monitoring events.

FollowCardEvent

Follow card display events.

ForceFetchRecommendationsEvent

Forced recommendation fetch events.

GreetingEvent

Greeting message events.

GroupLiveMemberNotifyEvent

Group live member notifications.

GuessQuestionAuditEvent

Guess question audit events.

GuestInviteEvent

Guest invitation events.

GuestInviteGuideEvent

Guest invitation guidance.

GuestShowdownEvent

Guest showdown events.

GuideEvent

User guidance events.

GuideTaskEvent

Guided task events.

HashtagEvent

Hashtag-related events.

HighlightFragementReadyEvent

Highlight fragment ready events.

HotRoomEvent

Hot room notifications.

ImDeleteEvent

Instant message deletion events.

InRoomBannerEvent

In-room banner displays.

InRoomBannerEventEvent

Banner event notifications.

InRoomBannerRefreshEvent

Banner refresh events.

InteractionHubGoalEvent

Interaction hub goal updates.

InteractiveEffectEvent

Interactive effect triggers.

LinkmicAnimationEvent

Link mic animation events.

LinkmicAudienceNoticeEvent

Link mic audience notices.

LiveIntroEvent

Live introduction messages.

user (ExtendedUser)

LiveJourneyEvent

Live journey milestone events.

LiveShowEvent

Live show events.

MarqueeAnnouncementEvent

Marquee announcement displays.

MessageDetectEvent

Message detection/moderation events.

MgPunishCenterActionEvent

Moderation punishment actions.

MiddleTouchEvent

Middle screen touch events.

MultiGuestSuggestEvent

Multi-guest suggestions.

NewAnchorGuideEvent

New anchor guidance messages.

NoticeEvent

General notice events.

NoticeboardEvent

Noticeboard updates.

NoticeboardReviewEvent

Noticeboard review events.

OChannelAnchorEvent

O-channel anchor events.

OChannelModifyEvent

O-channel modification events.

OChannelUserEvent

O-channel user events.

OecLiveHotRoomEvent

OEC live hot room events.

OecLiveManagerEvent

OEC live manager events.

PartnershipCardChangeEvent

Partnership card changes.

PartnershipDownloadCountEvent

Partnership download counts.

PartnershipDropsAnchorEvent

Partnership drops anchor events.

PartnershipDropsCardChangeEvent

Partnership drops card changes.

PartnershipDropsUpdateEvent

Partnership drops updates.

PartnershipGameOfflineEvent

Partnership game offline events.

PartnershipPunishEvent

Partnership punishment events.

PartnershipTaskShowEvent

Partnership task display events.

PerceptionEvent

User perception tracking events.

PictionaryEndEvent

Pictionary game end events.

PictionaryExitEvent

Pictionary exit events.

PictionaryStartEvent

Pictionary start events.

PictionaryUpdateEvent

Pictionary game updates.

PlayTogetherEvent

Play together invitation events.

PlaybookEvent

Playbook execution events.

PopularCardEvent

PortalEvent

Portal/gateway events.

PrivilegeAdvanceEvent

Privilege advancement events.

PrivilegeDynamicEffectEvent

Privilege dynamic effect events.

ProjectDModifyH5Event

Project D H5 modification events.

PromoteAdStatusEvent

Promotion/ad status events.

QuickChatListEvent

Quick chat list updates.

RealtimeLiveCenterMethodEvent

Realtime live center method calls.

RealTimePerformancePageEvent

Real-time performance metrics.

RoomEventEvent

Room event wrapper.

RoomStickerEvent

Room sticker events.

RoomStreamAdaptationEvent

Stream quality adaptation events.

ScreenChatEvent

Screen chat messages.

user_info (ExtendedUser)

ShareGuideEvent

Share guidance prompts.

ShortTouchEvent

Short touch interaction events.

SpeakerEvent

Speaker audio events.

SpecialPushEvent

Special push notification events.

StarCommentNotificationEvent

Star comment notifications.

operator (ExtendedUser)

StarCommentPushEvent

Star comment push events.

StreamStatusEvent

Stream status change events.

SubContractStatusEvent

Sub-contract status events.

SubPinEventEvent

Subscription pin events.

SubQueueEvent

Subscription queue events.

current_user (ExtendedUser)

SubTimerStickerEvent

Subscription timer sticker events.

SubWaveEvent

Subscription wave events.

SubscriptionGuideEvent

Subscription guidance messages.

ToastEvent

Generic toast notification events.

TrayEvent

Tray display events.

user (ExtendedUser)

UnauthorizedMemberEvent

Unauthorized member access events.

UpgradeEvent

Upgrade notification events.

UserStatsEvent

User statistics updates.

WalletLiveRewardsRatioEvent

Wallet rewards ratio events.

WallpaperEvent

Wallpaper change events.

WallpaperReviewEvent

Wallpaper review events.

WishlistUpdateEvent

Wishlist update events.

Event Mappings

The SDK maintains an EVENT_MAPPINGS dictionary that maps protocol buffer message types to their corresponding event classes. This allows automatic event routing based on incoming message types.

Using Proto Events

All proto events can be listened to using the @client.on() decorator:

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

@client.on(CommentEvent)
async def handle_comment(event: CommentEvent):
    print(f"Comment: {event.comment}")

@client.on(GiftEvent)
async def handle_gift(event: GiftEvent):
    print(f"Gift: {event.gift.name}")

@client.on(LikeEvent)
async def handle_like(event: LikeEvent):
    print(f"Like from: {event.user.nickname}")

Next Steps

Learn about Custom Events
See the Event System Overview
Explore the Client Reference

Client

Events

Web Client

WebSocket

Errors

​Overview

​Most Common Events

​CommentEvent

​GiftEvent

​LikeEvent

​JoinEvent

​FollowEvent

​ShareEvent

​Room & Control Events

​ControlEvent

​RoomEvent

​RoomPinEvent

​RoomNotifyEvent

​RoomUserSeqEvent

​RoomVerifyEvent

​RoomBottomEvent

​Social & Engagement Events

​SocialEvent

​DiggEvent

​EmoteChatEvent

​BarrageEvent

​SubNotifyEvent

​Gift & Economy Events

​GiftUpdateEvent

​GiftBroadcastEvent

​GiftCollectionUpdateEvent

​GiftDynamicRestrictionEvent

​GiftGalleryEvent

​GiftGuideEvent

​GiftNoticeEvent

​GiftPanelUpdateEvent

​GiftProgressEvent

​GiftPromptEvent

​GiftRecordCapsuleEvent

​GiftUnlockEvent

​GoalUpdateEvent

​GoodyBagEvent

​Battle & Competition Events

​LinkMicBattleEvent

​LinkMicArmiesEvent

​LinkMicBattleItemCardEvent

​LinkMicBattlePunishFinishEvent

​LinkMicBattleVictoryLapEvent

​LinkmicBattleNoticeEvent

​LinkmicBattleTaskEvent

​Link & Collaboration Events

​LinkEvent

​LinkLayerEvent

​LinkLayoutEvent

​LinkStateEvent

​LinkBusinessEvent

​LinkScreenChangeEvent

​LinkMicAdEvent

​LinkMicAnchorGuideEvent

​LinkMicMethodEvent

​LinkMicSignalingMethodEvent

​LinkMicFanTicketMethodEvent

​Game Events

​GameMomentEvent

​GameEmoteUpdateEvent

​GameGuessPinCardEvent

​GameGuessToastEvent

​GameGuessWidgetsEvent

​GameOcrPingEvent

​GameRankNotifyEvent

​GameRecommendCreateGuessEvent

​GameReqSetGuessEvent

​GameServerFeatureEvent

​GameSettingChangeEvent

​LiveGameIntroEvent

​PreviewGameMomentEvent

​Shopping & Commerce Events

​VideoLiveGoodsOrderEvent

​VideoLiveGoodsRcmdEvent

​VideoLiveCouponRcmdEvent

Overview

Most Common Events

CommentEvent

GiftEvent

LikeEvent

JoinEvent

FollowEvent

ShareEvent

Room & Control Events

ControlEvent

RoomEvent

RoomPinEvent

RoomNotifyEvent

RoomUserSeqEvent

RoomVerifyEvent

RoomBottomEvent

Social & Engagement Events

SocialEvent

DiggEvent

EmoteChatEvent

BarrageEvent

SubNotifyEvent

Gift & Economy Events

GiftUpdateEvent

GiftBroadcastEvent

GiftCollectionUpdateEvent

GiftDynamicRestrictionEvent

GiftGalleryEvent

GiftGuideEvent

GiftNoticeEvent

GiftPanelUpdateEvent

GiftProgressEvent

GiftPromptEvent

GiftRecordCapsuleEvent

GiftUnlockEvent

GoalUpdateEvent

GoodyBagEvent

Battle & Competition Events

LinkMicBattleEvent

LinkMicArmiesEvent

LinkMicBattleItemCardEvent

LinkMicBattlePunishFinishEvent

LinkMicBattleVictoryLapEvent

LinkmicBattleNoticeEvent

LinkmicBattleTaskEvent

Link & Collaboration Events

LinkEvent

LinkLayerEvent

LinkLayoutEvent

LinkStateEvent

LinkBusinessEvent

LinkScreenChangeEvent

LinkMicAdEvent

LinkMicAnchorGuideEvent

LinkMicMethodEvent

LinkMicSignalingMethodEvent

LinkMicFanTicketMethodEvent

Game Events

GameMomentEvent

GameEmoteUpdateEvent

GameGuessPinCardEvent

GameGuessToastEvent

GameGuessWidgetsEvent

GameOcrPingEvent

GameRankNotifyEvent

GameRecommendCreateGuessEvent

GameReqSetGuessEvent

GameServerFeatureEvent

GameSettingChangeEvent

LiveGameIntroEvent

PreviewGameMomentEvent

Shopping & Commerce Events

VideoLiveGoodsOrderEvent

VideoLiveGoodsRcmdEvent

VideoLiveCouponRcmdEvent

EcBarrageEvent

EcDrawEvent

EcTaskRefreshCouponListEvent

PaidContentLiveShoppingEvent

Interactive Features