Skip to content
Back to home

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 team

Once your game is registered you will receive the following data.

  • The game_id is 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_guid is only provided for Roblox games.
Format of the API key, which identifies your game.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

If 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.

RouteCredential
GET /v1/eventskey=<api_key> | x-api-key
GET /v1/events/pollx-api-key
GET /v1/configx-api-key
GET /v1/status—
Example of an authenticated request using the `x-api-key` header.
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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The 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 key URL parameter, because the browser does not allow headers on a WebSocket.
  • The HTTP routes /v1/events/poll and /v1/config receive the key only in the x-api-key header, and the key parameter is ignored there.
  • The /v1/status route 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 .html file 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 id and the action name.
  • Once it works, replace the runAction function with your game's code for each action.
Minimal and complete example of a web game that connects, reconnects on its own and shows the actions it receives.
<!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.

Request for the app status.
GET http://127.0.0.1:17920/v1/status
Response with the status of the app, the live and the connected games.
{
  "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 serving field is true when the app can deliver events to your game.
  • The serving_reason field explains why it is or is not serving, and no_valid_token means the streamer's plan is not active.
  • The tiktok_state field is disconnected without capture, waiting while waiting for the live and streaming while the live is on.
  • The connected_games and max_connected_games fields 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.

Connection address with the key, the event types and the last cursor.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41
  • The key parameter is required and carries the API key encoded with encodeURIComponent.
  • The types parameter is optional, lists the types separated by commas without spaces, and if it is missing all eight types are received.
  • The cursor parameter 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.

`hello` message with which the app confirms the connection.
{
  "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"
  }
}
Messages your game can receive after the `hello`.
{ "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.

Reply your game must send to each `ping`.
{ "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.

Request with the previous cursor and a 20-second wait.
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
ParameterRequiredDefaultRange
cursorno—^[0-9]{13}-[0-9]{1,19}$
waitno00–25 (C-021)
typesnogift,comment,like,follow,share,subscribe,join,viewersgift … viewers
limitno1001–100 (C-057)
Response with the new events and the cursor to send in the next request.
{
  "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 cursor from the previous response.
  • The has_more field is true when events were left over because of the limit, 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.

Configuration request with `If-None-Match` to avoid repeated downloads.
GET http://127.0.0.1:17920/v1/config
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If-None-Match: "cfg-7"
Response with the version and the rules of the configuration.
{ "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.

Common fields of an event, here with a gift.
{
  "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 v field is the format version and is always 1 today.
  • The id field is unique and stable per event, and your game must use it to ignore duplicates.
  • The type field is gift, comment, like, follow, share, subscribe, join or viewers.
  • The ts field is the event time in RFC 3339 UTC format with milliseconds.
  • The live_id, game_id and room_id fields identify the live, your game and the TikTok room.
  • The test field is true only in test events.
  • The user object describes the viewer and is null only in viewers events.
  • Each event carries only the object of its type (gift, comment, like, viewers or subscribe) and the others are null.
  • The actions array lists what your game must do, each one with action_key, params, rule_id and repeat.
  • Your game must run each action as many times as repeat says, 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.

VariableSource
{{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.

Example of a cursor, which your game only stores and sends back without interpreting it.
1791062100000-42
  • Store the cursor of each event message 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 reset field arrives as true, 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.

Example of the error response.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }
CodeHTTPReasonWhat to do
ORIGIN_FORBIDDEN403host_not_loopbackAlways connect to `127.0.0.1` or `localhost` and do not use any other host name.
LOCAL_KEY_INVALID401key_missingSend the API key in the WebSocket URL or in the `x-api-key` header.
LOCAL_KEY_INVALID401key_formatCheck that the key has the format `tkv_live_` followed by 32 alphanumeric characters.
LOCAL_KEY_INVALID401key_unknownCheck that you are using your game's current key and ask the team for a new one if you lost it.
LOCAL_KEY_INVALID401game_inactiveYour game is deactivated, so contact the TikAresV team.
LOCAL_KEY_INVALID401game_not_visibleYour game is not available for this streamer, so contact the TikAresV team.
LOCAL_KEY_INVALID401unresolved_offlineThe app could not validate the key because of no internet or too many attempts, so wait a few seconds and try again.
LOCAL_ACCESS_EXPIRED403no_valid_tokenThe 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_LIMIT403The 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_RESET200This is not an HTTP error but a notice that the app restarted, and your game continues with the new events.
COMMON_VALIDATION_FAILED422Check `details.fields` to see which parameter is invalid and fix it.
COMMON_NOT_FOUND404Check the route, or wait for the app to download the game's configuration if you requested `/v1/config`.
COMMON_INTERNAL500This 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.

CodeReason
1000normal
1001going_away
1008too_slow
1009message_too_big
4401key_invalid
4403access_expired
4408pong_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/status every 30 seconds until serving is true.
  • Code 4408 means your game did not reply pong in 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.

ConstantValueDescription
C-02017920Default port of the local API.
C-02125Maximum wait in seconds of a periodic request and recommended timeout for the client.
C-02210000Events kept per game, or those of the last 10 minutes.
C-02630Seconds between each WebSocket ping.
C-02710Seconds your game has to reply with the pong.
C-0281, 2, 4, 8, 16, 30Wait in seconds between reconnections, with a random variation of 20%.
C-03465536Maximum size in bytes of a WebSocket message.
C-05060Seconds without polling before the app considers the game disconnected.
C-057100Maximum events per response of a periodic request.
C-13786400Seconds an API key stays valid after being rotated.
C-138tkv_live_ + 32 base62Format of the API key.
C-1413Games connected at the same time by default.
C-155500Maximum 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.

App response to the browser's preflight request, which already includes the private network authorization.
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.1 does 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.1 instead of localhost, because the system may resolve localhost to ::1 first 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:.

Address of the test page, which opens in the browser while the app is open.
GET http://127.0.0.1:17920/harness

The 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/status in the browser and check that the app responds.
  • If localhost does not connect, switch to 127.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 pong to every ping in 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 reset field as true, the app restarted and the previous cursor is no longer valid, so your game will only receive new events.