Skip to main content
Gift events are triggered whenever a viewer sends a gift to the streamer. This guide covers how to properly handle gifts, including streak detection.

​
Understanding Gift Streaks

Users can send gifts in a streak, which increases the repeat_count value until they terminate the streak. A final event is triggered with repeat_end: 1 when the streak ends.
There are two types of gifts:
  1. Streakable gifts (type 1) - Can be sent multiple times in a row
  2. Non-streakable gifts - Single-send gifts that complete immediately

​
Basic Gift Handler

Here’s how to handle gift events with streak detection:
1

Import required modules

from TikTokLive import TikTokLiveClient
from TikTokLive.events import GiftEvent, ConnectEvent
2

Create the client

client: TikTokLiveClient = TikTokLiveClient(
    unique_id="@username"
)
3

Add gift event handler

@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
    # Streakable gift & streak is over
    if event.gift.streakable and not event.streaking:
        print(f"{event.user.unique_id} sent {event.repeat_count}x \"{event.gift.name}\"")
    
    # Non-streakable gift
    elif not event.gift.streakable:
        print(f"{event.user.unique_id} sent \"{event.gift.name}\"")
4

Start the client

if __name__ == '__main__':
    client.run()

​
Complete Example

from TikTokLive.client.client import TikTokLiveClient
from TikTokLive.client.logger import LogLevel
from TikTokLive.events import ConnectEvent, GiftEvent

client: TikTokLiveClient = TikTokLiveClient(
    unique_id="@tv_asahi_news"
)


@client.on(ConnectEvent)
async def on_connect(event: ConnectEvent):
    client.logger.info(f"Connected to @{event.unique_id}!")


@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
    client.logger.info("Received a gift!")

    # Can have a streak and streak is over
    if event.gift.streakable and not event.streaking:
        print(f"{event.user.unique_id} sent {event.repeat_count}x \"{event.gift.name}\"")

    # Cannot have a streak
    elif not event.gift.streakable:
        print(f"{event.user.unique_id} sent \"{event.gift.name}\"")


if __name__ == '__main__':
    # Enable debug info
    client.logger.setLevel(LogLevel.INFO.value)

    # Connect
    client.run()

​
Alternative: Low-Level Proto Access

You can also access the raw protobuf data: 
@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
    # If it's type 1 and the streak is over
    if event.gift.info.type == 1:
        if event.gift.is_repeating == 1:
            print(f"{event.user.unique_id} sent {event.repeat_count}x \"{event.gift.name}\"")

    # It's not type 1, which means it can't have a streak & is automatically over
    elif event.gift.info.type != 1:
        print(f"{event.user.unique_id} sent \"{event.gift.name}\"")
Use event.gift.streakable and event.streaking properties for cleaner code instead of checking event.gift.info.type directly.

​
Accessing Gift Information

You can fetch additional gift information when connecting: 
client.run(fetch_gift_info=True)
Then access gift details via: 
# Access all available gifts
available_gifts = client.gift_info
Don’t forget to check event.streaking to avoid counting incomplete streaks! Only process gifts when the streak is complete.

Build docs developers (and LLMs) love

Get started for freeTalk to us