TikTok LIVE API for Python: Real-Time Livestream Events (Unofficial)

TikTok LIVE API (TikTokLive) is the #1 TikTok LIVE client for Python. Connect to any TikTok LIVE stream and receive real-time chat messages, gifts, likes, follows, shares, viewer counts, battles, and more using just a creator's @unique_id. No login, no credentials or app are required.

TikTokLive is the definitive third-party Python library for reading the TikTok LIVE websocket, building TikTok chat bots, gift trackers, live stream overlays, alerts, and analytics tools.

Note: This is not a production-ready API. It is a reverse engineering project. Use the WebSocket API for production by Euler Stream.

What Can You Build With the TikTok LIVE API?

• TikTok live chat readers and chat bots that respond to comments in real time
• Gift trackers and donation alerts for TikTok LIVE streamers (with streak handling)
• OBS overlays and stream widgets driven by live TikTok events
• TikTok LIVE analytics: viewer counts, likes, follows, battle (PK) scores
• Moderation tools that react to deleted messages and room events
• Text-to-speech (TTS) readers and interactive livestream games

TikTok LIVE API for Production

Euler Stream offers a comprehensive TikTok LIVE API, WebSocket Server, CAPTCHA Solutions and much more!

Table of Contents

• Getting Started
  • Parameters
  • Methods
  • Properties
  • WebDefaults
• Events
• Documentation
• Other Languages
• Community
• Examples
• FAQ
• Licensing
• Star History
• Contributors

Community

Join the TikTokLive discord and visit the #py-support channel for questions, contributions and ideas.

Getting Started

Install the TikTok LIVE API client for Python via pip from the PyPi repository:

pip install TikTokLive

Then create your first real-time TikTok LIVE chat connection:

from TikTokLive import TikTokLiveClient
from TikTokLive.events import ConnectEvent, CommentEvent

# Create the client
client: TikTokLiveClient = TikTokLiveClient(unique_id="@isaackogz")


# Listen to an event with a decorator!
@client.on(ConnectEvent)
async def on_connect(event: ConnectEvent):
    print(f"Connected to @{event.unique_id} (Room ID: {client.room_id}")


# Or, add it manually via "client.add_listener()"
async def on_comment(event: CommentEvent) -> None:
    print(f"{event.user.nickname} -> {event.comment}")


client.add_listener(CommentEvent, on_comment)

if __name__ == '__main__':
    # Run the client and block the main thread
    # await client.start() to run non-blocking
    client.run()

For more quickstart examples, including a TikTok live chat reader, gift tracker, and live status checker, see the examples folder provided in the source tree.

TikTok LIVE API in Other Languages: Node.js, Java, C#, Go, Rust

The TikTokLive TikTok LIVE API is available in several alternate programming languages:

• Node.JS / JavaScript / TypeScript: TikTok-Live-Connector
• Java: TikTok-Live-Java
• C# / Unity: TikTokLiveSharp
• Go: gotiktoklive
• Rust: TikTokLiveRust

Parameters

Methods

A TikTokLiveClient object contains the following methods worth mentioning:

Properties

A TikTokLiveClient object contains the following important properties:

WebDefaults

TikTokLive has a series of global defaults used to create the HTTP client which you can customize. For info on how to set these parameters, see the web_defaults.py example.

Events

The TikTok LIVE API emits real-time events for everything happening in a livestream: comments, gifts, likes, joins, follows, shares, battles (PK), polls, captions, subscriptions, and moderation actions. Events can be listened to using a decorator or non-decorator method call. The following examples illustrate how you can listen to an event:

@client.on(LikeEvent)
async def on_like(event: LikeEvent) -> None:
    ...


async def on_comment(event: CommentEvent) -> None:
    ...


client.add_listener(CommentEvent, on_comment)

There are two types of events, CustomEvent events and ProtoEvent events. Both belong to the TikTokLive Event type and can be listened to. The following events are available:

Custom Events

• ConnectEvent - Triggered when the Webcast connection is initiated
• DisconnectEvent - Triggered when the Webcast connection closes (including the livestream ending)
• LiveEndEvent - Triggered when the livestream ends
• LivePauseEvent - Triggered when the livestream is paused
• LiveUnpauseEvent - Triggered when the livestream is unpaused
• FollowEvent - Triggered when a user in the livestream follows the streamer
• ShareEvent - Triggered when a user shares the livestream
• SuperFanEvent - Triggered when a viewer becomes a super fan of the streamer
• SuperFanJoinEvent - Triggered when an existing super fan joins the live (distinct from SuperFanEvent)
• SuperFanBoxEvent - Triggered when a super-fan envelope (gift box) is delivered
• WebsocketResponseEvent - Triggered when any event is received (contains the event)
• UnknownEvent - An instance of WebsocketResponseEvent thrown whenever an event does not have an existing definition, useful for debugging

Proto Events

These events are auto-generated from the TikTokLiveProto v3 schema. Only events whose proto messages are present in v3 are emitted; if you don't see one you used to rely on, it's because TikTok removed it from the schema.

If you know what an event does that's missing a description below, make a pull request and add it.

• BarrageEvent - A "VIP" viewer (based on gifting level) joins the chat room
• CaptionEvent - Auto-caption update from the host's audio
• CommentEvent - A viewer sent a chat comment
• ControlEvent - Stream action (e.g. start, end, pause, unpause)
• EmoteChatEvent - A custom emote was sent in chat
• EnvelopeEvent - A treasure chest / envelope was sent
• GiftEvent - A gift was sent (see Gift handling below)
• GoalUpdateEvent - Subscriber/follow goal updated
• HourlyRankRewardEvent - Hourly rank reward delivered
• ImDeleteEvent - A viewer's messages were deleted by a moderator
• InRoomBannerEvent - In-room banner notice
• JoinEvent - A viewer joined the livestream
• LikeEvent - The stream received likes
• LinkEvent - Generic link-mic event
• LinkLayerEvent - Link-mic layer/visibility change
• LinkMicArmiesEvent - A battle user received points
• LinkMicBattleEvent - A battle was started
• LinkMicBattlePunishFinishEvent - A battle's punishment phase ended
• LinkMicFanTicketMethodEvent
• LinkMicMethodEvent
• LinkmicBattleTaskEvent
• LiveIntroEvent - Live-intro message appears
• MessageDetectEvent
• OecLiveShoppingEvent - Live-shopping signal
• PollEvent - The creator launched / updated a poll
• QuestionNewEvent - Someone asked a new question via the question feature
• RankTextEvent - Gift count made a viewer enter the top three
• RankUpdateEvent
• RoomEvent - Broadcast message to all room users (e.g. "Welcome to TikTok LIVE!")
• RoomPinEvent - A message was pinned
• RoomUserSeqEvent - Current viewer count information
• SocialEvent - A viewer shared or followed the host (also surfaced as FollowEvent / ShareEvent custom events)
• SystemEvent
• UnauthorizedMemberEvent

New in 7.X.X

• AccessControlEvent - Access-control update for the room (e.g. CAPTCHA challenge issued to a viewer)
• AccessRecallEvent - Access restriction lifted / recalled for a viewer
• BoostCardEvent - Boost cards delivered to the room
• BottomEvent - Bottom-of-screen notice (often a punishment or violation banner)
• CapsuleEvent - In-room capsule / promotional pill notice
• GameRankNotifyEvent - Game-rank notification
• GiftBroadcastEvent - Big gift broadcast notice across rooms
• GiftDynamicRestrictionEvent - Dynamic gift restriction update
• GiftPanelUpdateEvent - Gift panel content update
• GiftPromptEvent - Anti-addiction / spending-limit prompt before gifting
• GuideEvent - In-room guide / tooltip prompt
• LinkMicLayoutStateEvent - Link-mic layout state update
• LinkStateEvent - Link-mic channel state update
• LiveGameIntroEvent - Live-game intro message
• MarqueeAnnouncementEvent - Marquee announcement scrolling across the room
• NoticeEvent - Generic notice / system tip in the room
• PartnershipDropsUpdateEvent - Partnership drops campaign update
• PartnershipGameOfflineEvent - Partnership game taken offline
• PartnershipPunishEvent - Partnership punishment notice
• PerceptionEvent - Perception dialog (warning / violation surfaced to a viewer)
• RoomNotifyEvent - Room-wide notification banner
• RoomVerifyEvent - Room verification action (e.g. forced verify / close)
• SpeakerEvent - Active speaker update (link-mic audio)
• SubNotifyEvent - Subscription notification (subscribe / renew / gift sub)
• SubPinEventEvent - Subscription pin card action
• ToastEvent - Transient toast notification
• ViewerPicksUpdateEvent - Viewer-picks (audience-driven prompt) update

GiftEvent

Fires every time a gift is sent. Extra static metadata for every gift type in the room can be fetched once on connect by passing fetch_gift_info=True to client.run() / client.start(); the result is cached on client.gift_info.

Streaks: streakable gifts trigger multiple GiftEvents as the viewer ramps up the streak, with event.repeat_count incrementing each time. The final gift in a streak carries event.repeat_end == 1. Use the event.streaking helper to filter intermediate events out and only act on the final one.

@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
    gift = event.gift
    if gift is None:
        return

    # Streakable gift & streak is over
    if not event.streaking and gift.type == 1:  # ``type == 1`` is streakable
        print(f"{event.user.unique_id} sent {event.repeat_count}x \"{gift.name}\"")

    # Non-streakable gift
    elif gift.type != 1:
        print(f"{event.user.unique_id} sent \"{gift.name}\"")

In v3 the canonical Gift field names are name, type, and image. The v2-era prefixed names (gift_name, gift_type, gift_image) remain available as read-only aliases on ExtendedGift for backwards compatibility. Wrap a Gift in ExtendedGift(...) if you want the .streakable helper.

Checking If A User Is Live

It is considered inefficient to use the connect method to check if a user is live. It is better to use the dedicated await client.is_live() method.

There is a complete example of how to do this in the examples folder.

Frequently Asked Questions

Is there an official TikTok LIVE API?

TikTok does not offer a public official API for reading livestream events. TikTokLive is an unofficial, open-source TikTok LIVE API client that reads the same Webcast websocket data available to any viewer of a stream.

How do I get TikTok LIVE chat messages in Python?

Install with pip install TikTokLive, create a TikTokLiveClient with the streamer's @unique_id, and listen for CommentEvent. See the Getting Started example above; it takes about ten lines of code.

Is the TikTok LIVE API free?

Yes. TikTokLive is free and open source under a modified AGPL license. Signing is handled by a third-party signature server (Euler Stream) with free community rate limits; an API key raises those limits.

Can I track TikTok gifts, likes, and viewer counts in real time?

Yes. GiftEvent (with streak handling), LikeEvent, and RoomUserSeqEvent deliver gifts, likes, and live viewer counts as they happen, alongside 50+ other event types including battles, polls, captions, and subscriptions.

Does this work with Node.js, Java, C#, Go, or Rust?

Yes, sister libraries exist for each. See Other Languages.

Star History

License

This project is licensed under a modified AGPL license - see the LICENSE file for details.

Contributors

• Isaac Kogan - Creator, Primary Maintainer, and Reverse-Engineering - isaackogan
• Zerody - Creator of the NodeJS library, introduced me to scraping TikTok LIVE - Zerody

See also the full list of secondary contributors who have participated in this project.