Custom TikTok bridge
Connect Vfinity to a TikTok LIVE connector you run yourself, instead of the built-in bridge
Vfinity normally starts its own TikTok helper when you connect. If you already run a connector, such as TikFinity or one you wrote, Vfinity can read TikTok LIVE events from its WebSocket instead.
Starts with Vfinity and talks to it privately, without opening a port. It can rejoin a dropped LIVE, wait for your LIVE to start, and report each viewer's roles.
Connects to a WebSocket server you keep running. Vfinity reads whatever events it sends, and your connector decides how and when it joins the LIVE.
Your events, alerts, throws, goals and leaderboards work the same either way. Twitch, Kick and YouTube are not affected by this choice.
Switch to your connector
Disconnect TikTok
The connection type is locked while TikTok is connected. Click Disconnect on the TikTok LIVE card in SettingsConnections first.
Choose Custom WebSocket
On the same card, open Advanced TikTok connection and set Connection Type to Custom WebSocket (TikFinity or other).
Enter its address
Fill in WebSocket Host and WebSocket Port to match your connector.
Vfinity starts you at localhost and 21213.
Connect
Start your connector, then click Connect to LIVE. Vfinity connects to
ws://host:port and counts the room as joined as soon as the socket opens.
The built-in helper opens no port of its own, so nothing in Vfinity competes with your connector for its port.
What Vfinity sends to your connector
If the TikTok Username field is filled in, Vfinity asks your connector to join that LIVE as soon as the socket opens:
{ "command": "connect", "username": "yourname" }Leave the username empty when your connector already knows which LIVE to read.
Clicking Refresh gift list sends {"command":"getGifts"}. Answer with a
giftList message whose data is a list of gifts, each with id, name,
diamondCount and imageUrl.
What your connector sends
Send one JSON object per message, naming the event and its data:
{
"event": "gift",
"data": {
"uniqueId": "mika_22",
"nickname": "Mika",
"profilePictureUrl": "https://example.com/mika.jpg",
"giftId": 5655,
"giftName": "Rose",
"diamondCount": 1,
"repeatCount": 5,
"giftType": 1,
"repeatEnd": true
}
}type works in place of event. A message without data is read as the data
itself. Numbers can also arrive as numeric strings, the way TikTok sends large
counters.
event | Fields Vfinity reads |
|---|---|
gift | the viewer, giftId, giftName, diamondCount, repeatCount, giftType, repeatEnd, giftPictureUrl |
chat | the viewer, comment |
like | the viewer, likeCount, totalLikeCount |
follow, share | the viewer |
subscribe | the viewer, subMonth, gifted |
question | the viewer, questionText |
envelope | the viewer, coins, people |
roomUser | viewerCount |
roomStats | followerCount, viewerCount, totalLikeCount, title |
It also understands member, social, emote, superFan, battle and
goalUpdate in the shape Vfinity's built-in bridge sends them. An event name
it does not know is ignored.
The viewer
Every viewer event starts with the same fields: uniqueId (the @handle),
nickname, and optionally userId and profilePictureUrl. A viewer with no
uniqueId shows as "unknown".
To make role rules work, add a roles object with any of isModerator,
isSubscriber, isSuperFan, isFollower and isOwner as true or false, and
followRole, gifterLevel or teamMemberLevel as numbers. Leave out what you
do not know: a missing role counts as unknown, never as false, and a rule that
needs it does not pass.
Gift combos
TikTok sends a combo gift (giftType 1) many times while the viewer keeps
tapping. Send those updates with repeatEnd: false, then a last message with
repeatEnd: true. Vfinity reacts only to the last one, so a 5-Rose combo
counts once as 5 Roses. Without giftType or repeatEnd, every gift message
counts on its own.
Test with a small server
This Node.js server stands in for a connector. It prints what Vfinity sends and replies with a chat message and a Rose combo.
// npm install ws
const { WebSocketServer } = require('ws');
const server = new WebSocketServer({ port: 21213 });
server.on('connection', (socket) => {
socket.on('message', (raw) => console.log('Vfinity says', raw.toString()));
const viewer = { uniqueId: 'testviewer', nickname: 'Test Viewer' };
socket.send(JSON.stringify({ event: 'chat', data: { ...viewer, comment: 'hello' } }));
socket.send(JSON.stringify({
event: 'gift',
data: { ...viewer, giftId: 5655, giftName: 'Rose', diamondCount: 1,
repeatCount: 5, giftType: 1, repeatEnd: true },
}));
});Run it, connect Vfinity to localhost and 21213, and both events appear in
the Dashboard's event log.
What needs the built-in bridge
Rejoin the LIVE automatically and Wait for the LIVE to start are
features of the built-in bridge. With a custom connector the card says so in
their place, and the Local API's tiktok.connect ignores them. Reconnecting
to TikTok is up to your connector.
If the connection fails or times out, check that your connector is running and listening on the host and port you entered. Vfinity gives up on a connection that does not open within 10 seconds.