How to Build Your Own TikTok LIVE Integration
A TikTok LIVE integration is a small service that connects to a creator's live room, receives gift, follow, like and chat events over a WebSocket, and turns them into something your app can act on. The connection is the easy part. Keeping it alive, deduplicating events and mapping gifts to actions is where the work is.
What a TikTok LIVE integration actually does
TikTok does not hand third-party developers a simple public event feed for LIVE rooms. Most hobby and indie integrations connect to a creator's room by username and read the same stream of events the TikTok app shows to viewers.
Once connected, you get a steady flow of small messages: a viewer sent a gift, someone followed, a comment arrived, the like count moved. Your job is to turn those into things like a game action, an on-screen alert or a spoken shout-out.
- Gifts: the most valuable event, and the one most integrations are built around
- Follows and shares: good for milestone triggers and thank-you alerts
- Likes: arrive in bursts, so you usually aggregate them
- Comments: useful for commands, polls and moderation filters
The architecture in four pieces
Keep it boring. Four small pieces are enough for almost every use case, and separating them makes each one easy to debug.
The mistake most people make is wiring the TikTok connection straight into the game or overlay code. When the connection drops mid-stream, everything downstream breaks with it.
- A listener that connects to the live room by username and reconnects on failure
- A normalizer that turns raw events into one clean shape: type, user, gift name, count, timestamp
- A mapping layer that decides which gift or event triggers which action
- An output channel, such as a WebSocket to a browser overlay, an HTTP queue a game polls, or a local command
Step one: connect and read events
Pick a client library in the language you already know. Several open-source libraries exist for Python, Node and other languages, and they all work the same way: give them a username, register handlers for each event type, and start the connection.
Test against a creator who is live right now, because you cannot receive gift events from an offline room. Log every raw event to a file for the first session. Those logs become your fixtures for testing later without needing anyone to be live.
Be aware that many libraries rely on a signing service to connect, and those services can rate-limit unauthenticated use. If connections start failing after a few attempts, check whether you need an API key for the signing service before blaming your code.
Step two: handle the messy parts
Gifts are the event that bites you. TikTok sends a streak gift as several events while the viewer keeps tapping, and only the final one carries the true total. If you fire an action on every event, a single rose streak can trigger ten times.
Gift names also arrive with inconsistent whitespace, so trim and normalize them before comparing against your mapping. A mapping that silently never matches is one of the most common bugs, and it looks like the integration is broken when it is just a stray space.
Connections will drop. Build a supervisor loop with a capped, increasing delay between retries, and surface the connection state somewhere you can see it during a stream.
- Dedupe events so a reconnect does not replay the same gift twice
- Only act on a streak when it ends, or track the count delta per event
- Aggregate likes into batches instead of firing on every tap
- Never echo raw comment text into a game or overlay without filtering it
Step three: map gifts to actions
A gift mapping is just a table: gift name on one side, action on the other, plus optional rules like a minimum count or a cooldown. Store it as data rather than code so the streamer can change it without you redeploying.
Start with three to five actions. Cheap gifts trigger small, funny effects, and expensive gifts trigger big ones. Viewers quickly learn what each gift does, and that is what makes them send more of them.
If you want a rough idea of what different gift volumes are worth to a creator, the free gift and earnings calculator is a quick way to sanity-check your tiers.
Free gift & earnings calculator →
Step four: deliver actions to the game or overlay
There are two patterns that work well. For browser overlays, push events over a WebSocket to a page the streamer adds as an OBS or TikTok LIVE Studio browser source. For games, expose a small queue over HTTP and have the game poll it every second or so.
Polling beats pushing for games because most game scripting environments cannot hold a socket open, or cannot run a server at all. A queue also means that if the game freezes for ten seconds, the actions are waiting for it instead of lost.
Whatever you pick, make actions idempotent where you can and give each one a unique ID, so a retry never doubles an effect.
When to use a ready-made API instead
Running the listener yourself means owning reconnects, signing quotas, event dedupe and uptime for every creator you support. For one personal stream that is a fun weekend project. For several creators it becomes a maintenance job.
TikPlays offers a developer WebSocket API that streams every gift, follow, like and comment from a live room, so you can skip the connection layer and build straight on top of the events. It is a separate service billed on usage, not part of the TikPlays subscription. The developer docs cover authentication and the event format.
Because TikPlays is not affiliated with TikTok, check TikTok's own terms and the rules for your region before shipping anything public.
Or skip the build and use a finished game
If your goal is simply to let viewers play something with gifts, you may not need to build anything. TikPlays turns a TikTok LIVE into a game the viewers play: you map gifts on the dashboard, and each one triggers an action in the game in real time. Follows, likes, shares and chat can trigger things too in many games.
There are 33 interactives in one subscription, from PC game mods like Minecraft, GTA V, Terraria and Granny, to Roblox games and OBS browser-source arcade games like Gift Tower and Raid Boss. Setup is a dashboard link plus an installer for mod games, with no port forwarding, and it works alongside TikTok LIVE Studio or OBS.