Documentation for web games
Connect your browser game to TikTok live events through the TikAresV desktop app.
What it is and how it works
TikAresV is a desktop app that reads the streamer's TikTok live events (gifts, comments, likes, follows, shares, subscriptions, joins and viewers) and delivers them to your game.
The app opens a local API at 127.0.0.1 on the streamer's computer, and your game, which runs in the browser on that same computer, connects to it with an API key.
- The local API only exists while the desktop app is open on the computer where the game runs.
- Each event arrives with a stable
id, so your game can ignore the ones it already processed. - The streamer defines in the app which action fires with each gift, comment or like, and your game only runs the actions it receives.
- You can receive events over WebSocket, which is the most convenient option in the browser, or by periodic polling (long-poll) if you prefer plain HTTP.
To receive events you only need your game's API key, a browser on the streamer's computer and the instructions on this page.
Game registration and API key
The TikAresV team registers games, so write to us to register yours.
Contact the TikAresV teamOnce your game is registered you will receive the following data.
- The
game_idis the unique identifier of your game. - The API key looks like
tkv_live_plus 32 alphanumeric characters and is shown only once, so save it right away. - The
game_guidis only provided for Roblox games.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxIf you need to change the key, the team generates a new one and the old one stays valid for 24 hours (86400 seconds) so you can update your game without downtime.
Treat the key like a password for your game and do not publish it in open repositories that are not yours.
Authentication with the API key
Every call that delivers events or configuration is authenticated with your game's API key, which looks like tkv_live_ followed by 32 alphanumeric characters.
| Route | Credential |
|---|---|
GET /v1/events | key=<api_key> | x-api-key |
GET /v1/events/poll | x-api-key |
GET /v1/config | x-api-key |
GET /v1/status | — |
GET http://127.0.0.1:17920/v1/events/poll?wait=0 HTTP/1.1
Host: 127.0.0.1:17920
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxThe key travels inside your game's code and identifies it as a game to the app, so do not share it with other games.
- The WebSocket receives the key in the
keyURL parameter, because the browser does not allow headers on a WebSocket. - The HTTP routes
/v1/events/polland/v1/configreceive the key only in thex-api-keyheader, and thekeyparameter is ignored there. - The
/v1/statusroute does not need a key, so it is useful to check whether the app is open before connecting.
Quick start
With these steps your game receives its first event in a few minutes.
- Ask the TikAresV team to register your game and save the API key you receive, because it is shown only once.
- Ask the streamer to open the TikAresV desktop app and sign in.
- Copy the example in this section into an
.htmlfile and replace the API key placeholder with yours. - Open the file in the browser on the same computer where the app runs, and if Chrome asks about local network access, accept.
- Ask the streamer to open their game in the app, edit a rule and press the Test button.
- Check that the page log shows a line with the test event
idand the action name. - Once it works, replace the
runActionfunction with your game's code for each action.
<!doctype html>
<html lang="es">
<head>
<meta charset="utf-8">
<title>TikAresV: juego web de ejemplo</title>
</head>
<body>
<pre id="log"></pre>
<script>
const API_KEY = 'tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; // la key de tu juego
const PORT = 17920; // C-020
const TYPES = 'gift,comment,like,follow,share,subscribe,join';
const BACKOFF_S = [1, 2, 4, 8, 16, 30]; // C-028
let cursor = null;
let attempt = 0;
function log(line) {
document.getElementById('log').textContent += line + '\n';
}
// Aquí va el código de tu juego para cada acción.
function runAction(actionKey, params) {
console.log('acción', actionKey, params);
}
function handleEvent(ev) {
for (const action of ev.actions) {
log(ev.id + ' ' + action.action_key);
for (let i = 0; i < (action.repeat || 1); i++) runAction(action.action_key, action.params);
}
}
function retryIn(seconds) {
const jitter = 0.8 + Math.random() * 0.4;
setTimeout(connect, seconds * 1000 * jitter);
}
function onClose(code) {
if (code === 4401) return log('key inválida (4401): cámbiala antes de reconectar');
if (code === 1009) return log('mensaje demasiado grande (1009): corrige el cliente');
if (code === 1000) return log('conexión cerrada por el juego (1000)');
if (code === 4403) return retryIn(30); // el plan del streamer no está vigente
retryIn(BACKOFF_S[Math.min(attempt++, BACKOFF_S.length - 1)]); // 1001, 1008, 4408 y caídas
}
function connect() {
let url = 'ws://127.0.0.1:' + PORT + '/v1/events?key=' + encodeURIComponent(API_KEY) + '&types=' + TYPES;
if (cursor) url += '&cursor=' + encodeURIComponent(cursor);
const ws = new WebSocket(url);
ws.onmessage = (message) => {
const msg = JSON.parse(message.data);
if (msg.type === 'hello') {
attempt = 0;
if (msg.data.reset) log('la app se reinició: solo llegarán eventos nuevos');
} else if (msg.type === 'event') {
cursor = msg.data.cursor;
handleEvent(msg.data.event);
} else if (msg.type === 'ping') {
ws.send(JSON.stringify({ type: 'pong', data: { ts: msg.data.ts } }));
} else if (msg.type === 'config.changed') {
log('config.changed ' + msg.data.config_version);
} else if (msg.type === 'error') {
log('error ' + msg.data.code);
}
};
ws.onclose = (close) => onClose(close.code);
}
connect();
</script>
</body>
</html>
If something fails, check the errors table and the troubleshooting section below.
App status: GET /v1/status
This route tells you whether the app is open and able to serve events, and it needs no API key.
GET http://127.0.0.1:17920/v1/status{
"api": "local/v1",
"agent_version": "0.1.245",
"port": 17920,
"server_time": "2026-10-03T21:15:30.000Z",
"tiktok_state": "streaming",
"live": { "active": true, "observer": false, "started_at": "2026-10-03T21:15:00.000Z" },
"serving": true,
"serving_reason": "live_started_with_token",
"connected_games": 1,
"max_connected_games": 3,
"control_channel": "websocket"
}- The
servingfield istruewhen the app can deliver events to your game. - The
serving_reasonfield explains why it is or is not serving, andno_valid_tokenmeans the streamer's plan is not active. - The
tiktok_statefield isdisconnectedwithout capture,waitingwhile waiting for the live andstreamingwhile the live is on. - The
connected_gamesandmax_connected_gamesfields show how many games are connected and how many the plan allows.
WebSocket connection: GET /v1/events
The WebSocket delivers events as soon as they arrive, and it is the recommended way for web games.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41- The
keyparameter is required and carries the API key encoded withencodeURIComponent. - The
typesparameter is optional, lists the types separated by commas without spaces, and if it is missing all eight types are received. - The
cursorparameter is optional and resumes delivery from the last event your game processed.
Right after connecting, the app sends a hello message with the session state.
{
"type": "hello",
"data": {
"api": "local/v1", "agent_version": "0.1.245", "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"game_name": "Juego de prueba", "platform": "web", "types": ["gift", "comment"],
"cursor": "1791062100000-41", "reset": false, "config_version": 7,
"live": { "live_id": "01a1039e-c820-7028-9d1f-b2da68991b17", "unique_id": "ana_streams", "observer": false,
"started_at": "2026-10-03T21:15:00.000Z" },
"server_time": "2026-10-03T21:15:30.010Z"
}
}{ "type": "event", "data": { "cursor": "1791062100000-42", "event": { "v": 1, "id": "tt:7421234567890001001", "…": "…" } } }
{ "type": "config.changed", "data": { "config_version": 8 } }
{ "type": "ping", "data": { "ts": 1791062130000 } }
{ "type": "error", "data": { "code": "LOCAL_ACCESS_EXPIRED", "message": "local access expired", "details": { "reason": "no_valid_token" } } }The app sends a ping every 30 seconds and your game must reply pong with the same ts within 10 seconds, or the app closes the connection with code 4408.
{ "type": "pong", "data": { "ts": 1791062130000 } }Periodic polling: GET /v1/events/poll
This route is the alternative to WebSockets for clients that can only make HTTP requests, and it waits up to wait seconds before answering empty.
GET http://127.0.0.1:17920/v1/events/poll?cursor=1791062100000-41&wait=20&types=gift,comment&limit=100
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx| Parameter | Required | Default | Range |
|---|---|---|---|
cursor | no | — | ^[0-9]{13}-[0-9]{1,19}$ |
wait | no | 0 | 0–25 (C-021) |
types | no | gift,comment,like,follow,share,subscribe,join,viewers | gift … viewers |
limit | no | 100 | 1–100 (C-057) |
{
"events": [ { "v": 1, "id": "tt:7421234567890001001", "type": "gift", "…": "…" } ],
"cursor": "1791062100000-43",
"reset": false,
"has_more": false,
"config_version": 7,
"live": { "live_id": "01a1039e-c820-7028-9d1f-b2da68991b17", "unique_id": "ana_streams", "observer": false,
"started_at": "2026-10-03T21:15:00.000Z" },
"server_time": "2026-10-03T21:15:30.010Z"
}- Repeat the request as soon as you receive the response, sending the
cursorfrom the previous response. - The
has_morefield istruewhen events were left over because of thelimit, and then you must request again without waiting. - If you stop polling for 60 seconds, the app considers that your game disconnected.
Current rules: GET /v1/config
This route returns the rules the streamer configured for your game, and it is useful for showing on-screen hints.
GET http://127.0.0.1:17920/v1/config
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If-None-Match: "cfg-7"{ "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e", "config_version": 7, "updated_at": "2026-10-03T20:58:41.512Z",
"is_default": false, "config": { "schema": "config/v1", "rules": [ { "rule_id": "r-rosa-mensaje", "…": "…" } ] } }Your game does not need to interpret the rules, because each event already carries its resolved actions.
Content of each event
Every event has the same common fields, and each type adds its own object with the specific data.
{
"v": 1,
"id": "tt:7421234567890001001",
"type": "gift",
"ts": "2026-10-03T21:15:04.512Z",
"live_id": "01a1039e-c820-7028-9d1f-b2da68991b17",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421234567890123456",
"test": false,
"user": { "user_id": "…", "unique_id": "…", "nickname": "…", "avatar_url": "…", "badges": { "…": "…" } },
"gift": { "…": "…" }, "comment": null, "like": null, "viewers": null, "subscribe": null,
"actions": [
{ "action_key": "show_message", "params": { "text": "…", "color": "#FF3366" }, "rule_id": "r-rosa-mensaje", "repeat": 1 }
]
}- The
vfield is the format version and is always1today. - The
idfield is unique and stable per event, and your game must use it to ignore duplicates. - The
typefield isgift,comment,like,follow,share,subscribe,joinorviewers. - The
tsfield is the event time in RFC 3339 UTC format with milliseconds. - The
live_id,game_idandroom_idfields identify the live, your game and the TikTok room. - The
testfield istrueonly in test events. - The
userobject describes the viewer and isnullonly inviewersevents. - Each event carries only the object of its type (
gift,comment,like,viewersorsubscribe) and the others arenull. - The
actionsarray lists what your game must do, each one withaction_key,params,rule_idandrepeat. - Your game must run each action as many times as
repeatsays, which is 1 except in the every-N-likes rules.
Examples of the eight event types
gift
{
"v": 1,
"id": "tt:7421000000000001001",
"type": "gift",
"ts": "2026-10-03T18:05:12.345Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": false,
"follower": true,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 3
}
},
"gift": {
"gift_id": "5655",
"name": "Rose",
"image_url": "https://p16-webcast.tiktokcdn.com/img/maliva/webcast-va/eba3a9bb85c33e017f3648eaf88d7189-tplv-obj.webp",
"roblox_image_id": null,
"count": 2,
"diamonds_unit": 1,
"diamonds_total": 2,
"streakable": true,
"streak": {
"streak_id": "7421000000000000777",
"total": 3,
"ended": false
}
},
"comment": null,
"like": null,
"viewers": null,
"subscribe": null,
"actions": [
{
"action_key": "show_message",
"params": {
"text": "Ana envió 3 Rose",
"color": "#FF3B5C"
},
"rule_id": "rose-message",
"repeat": 1
}
]
}comment
{
"v": 1,
"id": "tt:7421000000000001002",
"type": "comment",
"ts": "2026-10-03T18:05:13.100Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": false,
"follower": true,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 3
}
},
"gift": null,
"comment": {
"text": "!spawn 2 por favor"
},
"like": null,
"viewers": null,
"subscribe": null,
"actions": [
{
"action_key": "spawn_item",
"params": {
"count": 1
},
"rule_id": "spawn-command",
"repeat": 1
},
{
"action_key": "show_message",
"params": {
"text": "Ana usó !spawn",
"color": "#22C55E"
},
"rule_id": "spawn-command",
"repeat": 1
}
]
}like
{
"v": 1,
"id": "tt:7421000000000001003",
"type": "like",
"ts": "2026-10-03T18:05:14.020Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": false,
"follower": true,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 3
}
},
"gift": null,
"comment": null,
"like": {
"count": 15,
"total": 1200
},
"viewers": null,
"subscribe": null,
"actions": [
{
"action_key": "spawn_item",
"params": {
"count": 5
},
"rule_id": "likes-100",
"repeat": 1
}
]
}follow
{
"v": 1,
"id": "tt:7421000000000001004",
"type": "follow",
"ts": "2026-10-03T18:05:15.500Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": false,
"follower": true,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 3
}
},
"gift": null,
"comment": null,
"like": null,
"viewers": null,
"subscribe": null,
"actions": [
{
"action_key": "show_message",
"params": {
"text": "¡Gracias por seguir, Ana!",
"color": "#3B82F6"
},
"rule_id": "follow-thanks",
"repeat": 1
}
]
}share
{
"v": 1,
"id": "tt:7421000000000001005",
"type": "share",
"ts": "2026-10-03T18:05:16.250Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": false,
"follower": true,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 3
}
},
"gift": null,
"comment": null,
"like": null,
"viewers": null,
"subscribe": null,
"actions": []
}subscribe
{
"v": 1,
"id": "tt:7421000000000001006",
"type": "subscribe",
"ts": "2026-10-03T18:05:17.000Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": true,
"follower": true,
"top_gifter": false,
"fan_club_level": 4,
"gifter_level": 3
}
},
"gift": null,
"comment": null,
"like": null,
"viewers": null,
"subscribe": {
"months": 3
},
"actions": []
}join
{
"v": 1,
"id": "tt:7421000000000001007",
"type": "join",
"ts": "2026-10-03T18:05:18.750Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000002",
"unique_id": "beto",
"nickname": "Beto",
"avatar_url": "https://api.tikaresv.com/v1/media/avatars/default.png",
"badges": {
"moderator": false,
"subscriber": false,
"follower": false,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 0
}
},
"gift": null,
"comment": null,
"like": null,
"viewers": null,
"subscribe": null,
"actions": []
}viewers
{
"v": 1,
"id": "ag:01928f3d-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
"type": "viewers",
"ts": "2026-10-03T18:05:20.000Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": null,
"gift": null,
"comment": null,
"like": null,
"viewers": {
"current": 1234,
"total_unique": 5678
},
"subscribe": null,
"actions": []
}These are the eight event types with a real example of each.
| Variable | Source |
|---|---|
{{nickname}} | user.nickname |
{{unique_id}} | user.unique_id |
{{gift_name}} | gift.name |
{{gift_count}} | gift.count |
{{diamonds}} | gift.diamonds_total |
{{comment}} | comment.text |
{{likes}} | like.total |
The params texts already have their variables replaced, and none exceeds 500 characters.
Cursor and resuming
The cursor is an opaque marker that shows which event your game reached, and it helps you not to lose events if the connection drops.
1791062100000-42- Store the cursor of each
eventmessage or of each polling response. - When reconnecting, send the last stored cursor to receive what you missed.
- Without a cursor, you only receive events that happen after connecting.
- If the
resetfield arrives astrue, the app restarted or the cursor is no longer available, and you will only receive new events.
The cursor also advances over events that your type filter discards, so you will not receive them again.
Errors
All HTTP errors have the same shape, with a stable code you can compare in your code and a message in English.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }| Code | HTTP | Reason | What to do |
|---|---|---|---|
ORIGIN_FORBIDDEN | 403 | host_not_loopback | Always connect to `127.0.0.1` or `localhost` and do not use any other host name. |
LOCAL_KEY_INVALID | 401 | key_missing | Send the API key in the WebSocket URL or in the `x-api-key` header. |
LOCAL_KEY_INVALID | 401 | key_format | Check that the key has the format `tkv_live_` followed by 32 alphanumeric characters. |
LOCAL_KEY_INVALID | 401 | key_unknown | Check that you are using your game's current key and ask the team for a new one if you lost it. |
LOCAL_KEY_INVALID | 401 | game_inactive | Your game is deactivated, so contact the TikAresV team. |
LOCAL_KEY_INVALID | 401 | game_not_visible | Your game is not available for this streamer, so contact the TikAresV team. |
LOCAL_KEY_INVALID | 401 | unresolved_offline | The app could not validate the key because of no internet or too many attempts, so wait a few seconds and try again. |
LOCAL_ACCESS_EXPIRED | 403 | no_valid_token | The streamer's plan is not active, so they must renew it in the Plan section of the app and your game must retry every 30 seconds. |
LOCAL_GAMES_LIMIT | 403 | The plan's maximum number of connected games was reached, so close another game or ask the streamer for a plan with more games. | |
LOCAL_CURSOR_RESET | 200 | This is not an HTTP error but a notice that the app restarted, and your game continues with the new events. | |
COMMON_VALIDATION_FAILED | 422 | Check `details.fields` to see which parameter is invalid and fix it. | |
COMMON_NOT_FOUND | 404 | Check the route, or wait for the app to download the game's configuration if you requested `/v1/config`. | |
COMMON_INTERNAL | 500 | This is an unexpected app error, so retry with increasing delay and tell the team if it persists. |
The table shows what to do for each error.
WebSocket close codes
When the connection closes, the code tells your game what to do.
| Code | Reason |
|---|---|
1000 | normal |
1001 | going_away |
1008 | too_slow |
1009 | message_too_big |
4401 | key_invalid |
4403 | access_expired |
4408 | pong_timeout |
- Code 1000 means your game closed the connection, and no action is needed.
- Code 1001 means the app closed or changed port, and your game must reconnect with increasing delay and the last cursor.
- Code 1008 means your game is too slow, and it must reconnect with the last cursor.
- Code 1009 means your game sent a message that was too large, and you must fix the client.
- Code 4401 means the key is invalid or was revoked, and your game must not reconnect until it is changed.
- Code 4403 means access has expired, and your game must query
/v1/statusevery 30 seconds untilservingistrue. - Code 4408 means your game did not reply
pongin time, and it must reconnect with increasing delay and the last cursor.
Limits and fixed values
These are the limits applied by the local API, and the C-### identifiers are the internal names of each value.
| Constant | Value | Description |
|---|---|---|
C-020 | 17920 | Default port of the local API. |
C-021 | 25 | Maximum wait in seconds of a periodic request and recommended timeout for the client. |
C-022 | 10000 | Events kept per game, or those of the last 10 minutes. |
C-026 | 30 | Seconds between each WebSocket ping. |
C-027 | 10 | Seconds your game has to reply with the pong. |
C-028 | 1, 2, 4, 8, 16, 30 | Wait in seconds between reconnections, with a random variation of 20%. |
C-034 | 65536 | Maximum size in bytes of a WebSocket message. |
C-050 | 60 | Seconds without polling before the app considers the game disconnected. |
C-057 | 100 | Maximum events per response of a periodic request. |
C-137 | 86400 | Seconds an API key stays valid after being rotated. |
C-138 | tkv_live_ + 32 base62 | Format of the API key. |
C-141 | 3 | Games connected at the same time by default. |
C-155 | 500 | Maximum length in characters of a text with variables. |
Local network notice in Chrome
When a public page connects to 127.0.0.1, Chrome shows a permission prompt for local network access.
The streamer must accept that prompt once, or the browser will block your game's connection to the app.
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: x-api-key, if-none-match
Access-Control-Allow-Private-Network: true
Access-Control-Max-Age: 600- The prompt only appears on public pages, and a page opened from a local file or from
http://127.0.0.1does not show it. - If the streamer denied the permission, they must enable it in the site settings in Chrome and reload the page.
- Always use
127.0.0.1instead oflocalhost, because the system may resolvelocalhostto::1first and the app does not listen there.
How to test your game
To test without waiting for a real gift, the streamer can send test events from the app.
- Open the TikAresV desktop app and sign in.
- Enter the game in the app's game list.
- Open an existing rule or create a new one in the rules editor.
- Press the Test button in the rules editor.
- Check that your game receives the event and runs the action.
Test events arrive with test: true and with an id that starts with test:.
GET http://127.0.0.1:17920/harnessThe app also includes a test page that shows what a game would receive, without needing to have one.
Troubleshooting
Check these causes in order when your game does not receive events.
- If the connection fails immediately, open
http://127.0.0.1:17920/v1/statusin the browser and check that the app responds. - If
localhostdoes not connect, switch to127.0.0.1, because the app does not listen on::1. - If you get error 401, check that the key has the format
tkv_live_plus 32 characters and that it has not been rotated. - If you get error 403 with
LOCAL_ACCESS_EXPIRED, ask the streamer to renew their plan in the Plan section of the app. - If you get error 403 with
LOCAL_GAMES_LIMIT, close another connected game or ask the streamer for a plan with more games. - If the browser blocks the connection without showing an app error, accept the Chrome local network prompt.
- If the connection drops every few seconds, check that your game replies
pongto everypingin under 10 seconds. - If you see repeated events after restarting the app, ignore the ones you already processed using the event
id. - If you see the
resetfield astrue, the app restarted and the previous cursor is no longer valid, so your game will only receive new events.