tiktok-live-api 1.4.5 ā 1.4.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +579 -427
- package/dist/index.d.mts +105 -1
- package/dist/index.d.ts +105 -1
- package/dist/index.js +216 -2
- package/dist/index.mjs +213 -1
- package/package.json +84 -84
package/README.md
CHANGED
|
@@ -1,427 +1,579 @@
|
|
|
1
|
-
<p align="center">
|
|
2
|
-
<img src="https://raw.githubusercontent.com/tiktool/tiktok-live-api/main/banner.png" alt="tiktok-live-api" width="100%" />
|
|
3
|
-
</p>
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
});
|
|
49
|
-
|
|
50
|
-
client.on('
|
|
51
|
-
console.log(`${event.user.uniqueId}
|
|
52
|
-
});
|
|
53
|
-
|
|
54
|
-
client.on('
|
|
55
|
-
console.log(`${event.user.uniqueId}
|
|
56
|
-
});
|
|
57
|
-
|
|
58
|
-
client.on('
|
|
59
|
-
console.log(`${event.
|
|
60
|
-
});
|
|
61
|
-
|
|
62
|
-
client.
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
**
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
client
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
client.on('
|
|
95
|
-
|
|
96
|
-
client.
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
//
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
});
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
##
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
|
264
|
-
|
|
265
|
-
| `
|
|
266
|
-
| `
|
|
267
|
-
| `
|
|
268
|
-
| `
|
|
269
|
-
| `
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
|
334
|
-
|
|
335
|
-
| `
|
|
336
|
-
| `
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
- `
|
|
341
|
-
- `
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/tiktool/tiktok-live-api/main/banner.png" alt="tiktok-live-api" width="100%" />
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<a href="https://discord.com/oauth2/authorize?client_id=1482386543233597470">
|
|
7
|
+
<img src="https://img.shields.io/badge/Add%20TikTool%20Bot%20to%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Add TikTool Bot to Discord" height="46">
|
|
8
|
+
</a>
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center"><b>Agency rank feeds in Discord</b>: gaming ranks, creator ranks and 99+ movers across all 30 regions, copy-paste usernames for backstage. Run <code>/ranks</code> to start (Global Agency).</p>
|
|
12
|
+
|
|
13
|
+
# tiktok-live-api
|
|
14
|
+
|
|
15
|
+
> š **Full documentation, guides, and dashboard ā [tik.tools](https://tik.tools)** | š **Python SDK ā [tik.tools/guides/python-tiktok-live](https://tik.tools/guides/python-tiktok-live)** | š **WebSocket API ā [tik.tools/websocket](https://tik.tools/websocket)**
|
|
16
|
+
|
|
17
|
+
**Unofficial TikTok LIVE API Client for Node.js & TypeScript** - Connect to any TikTok LIVE stream and receive real-time chat messages, gifts, likes, follows, viewer counts, battles, and more. Includes AI-powered live captions (speech-to-text). Powered by the [TikTool](https://tik.tools) managed API.
|
|
18
|
+
|
|
19
|
+
[](https://www.npmjs.com/package/tiktok-live-api)
|
|
20
|
+
[](https://www.npmjs.com/package/tiktok-live-api)
|
|
21
|
+
[](https://www.typescriptlang.org/)
|
|
22
|
+
[](https://github.com/tiktool/tiktok-live-api/blob/main/LICENSE)
|
|
23
|
+
|
|
24
|
+
<p align="center">
|
|
25
|
+
<img src="https://raw.githubusercontent.com/tiktool/tiktok-live-api/main/tiktok-live-api.gif" alt="TikTok Live API Demo - real-time chat, gifts, and viewer events" width="700">
|
|
26
|
+
</p>
|
|
27
|
+
|
|
28
|
+
> This package is **not affiliated with or endorsed by TikTok**. It connects to the [TikTool Live](https://tik.tools) managed API service - 99.9% uptime, no reverse engineering, no maintenance required. Also available for [Python](https://pypi.org/project/tiktok-live-api/) and [any language via WebSocket](https://tik.tools/docs).
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npm install tiktok-live-api
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
# or with yarn / pnpm / bun
|
|
38
|
+
yarn add tiktok-live-api
|
|
39
|
+
pnpm add tiktok-live-api
|
|
40
|
+
bun add tiktok-live-api
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Quick Start
|
|
44
|
+
|
|
45
|
+
```typescript
|
|
46
|
+
import { TikTokLive } from 'tiktok-live-api';
|
|
47
|
+
|
|
48
|
+
const client = new TikTokLive('streamer_username', { apiKey: 'YOUR_API_KEY' });
|
|
49
|
+
|
|
50
|
+
client.on('chat', (event) => {
|
|
51
|
+
console.log(`${event.user.uniqueId}: ${event.comment}`);
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
client.on('gift', (event) => {
|
|
55
|
+
console.log(`${event.user.uniqueId} sent ${event.giftName} (${event.diamondCount} š)`);
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
client.on('like', (event) => {
|
|
59
|
+
console.log(`${event.user.uniqueId} liked (total: ${event.totalLikes})`);
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
client.on('follow', (event) => {
|
|
63
|
+
console.log(`${event.user.uniqueId} followed!`);
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
client.on('roomUserSeq', (event) => {
|
|
67
|
+
console.log(`${event.viewerCount} viewers watching`);
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
client.connect();
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
That's it. **No complex setup, no protobuf, no reverse engineering, no breakages when TikTok updates.**
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## š Try It Now - Live Demo
|
|
78
|
+
|
|
79
|
+
Copy-paste this into a file and run it. Connects to a live TikTok stream and prints every event in real time. Works on the free Community tier - 2 hours per WebSocket connection.
|
|
80
|
+
|
|
81
|
+
**Save as `demo.mjs` and run with `node demo.mjs`:**
|
|
82
|
+
|
|
83
|
+
```javascript
|
|
84
|
+
// demo.mjs - TikTok LIVE in real time
|
|
85
|
+
// npm install tiktok-live-api
|
|
86
|
+
import { TikTokLive } from 'tiktok-live-api';
|
|
87
|
+
|
|
88
|
+
const API_KEY = 'YOUR_API_KEY'; // Get free key ā https://tik.tools
|
|
89
|
+
const LIVE_USERNAME = 'tv_asahi_news'; // Any live TikTok username
|
|
90
|
+
|
|
91
|
+
const client = new TikTokLive(LIVE_USERNAME, { apiKey: API_KEY });
|
|
92
|
+
let events = 0;
|
|
93
|
+
|
|
94
|
+
client.on('chat', e => { events++; console.log(`š¬ ${e.user.uniqueId}: ${e.comment}`); });
|
|
95
|
+
client.on('gift', e => { events++; console.log(`š ${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount}š)`); });
|
|
96
|
+
client.on('like', e => { events++; console.log(`ā¤ļø ${e.user.uniqueId} liked Ć ${e.likeCount}`); });
|
|
97
|
+
client.on('member', e => { events++; console.log(`š ${e.user.uniqueId} joined`); });
|
|
98
|
+
client.on('follow', e => { events++; console.log(`ā ${e.user.uniqueId} followed`); });
|
|
99
|
+
client.on('roomUserSeq', e => { events++; console.log(`š Viewers: ${e.viewerCount}`); });
|
|
100
|
+
|
|
101
|
+
client.on('connected', () => console.log(`\nā
Connected to @${LIVE_USERNAME} - streaming events...\n`));
|
|
102
|
+
client.on('disconnected', () => console.log(`\nš Disconnected. Received ${events} events.\n`));
|
|
103
|
+
|
|
104
|
+
client.connect();
|
|
105
|
+
// Press Ctrl+C to stop. Community tier caps each WebSocket at 2 hours.
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
<details>
|
|
109
|
+
<summary><strong>š Pure WebSocket version (no SDK, any language)</strong></summary>
|
|
110
|
+
|
|
111
|
+
```javascript
|
|
112
|
+
// ws-demo.mjs - Pure WebSocket, zero SDK
|
|
113
|
+
// npm install ws
|
|
114
|
+
import WebSocket from 'ws';
|
|
115
|
+
|
|
116
|
+
const API_KEY = 'YOUR_API_KEY';
|
|
117
|
+
const LIVE_USERNAME = 'tv_asahi_news';
|
|
118
|
+
|
|
119
|
+
const ws = new WebSocket(`wss://api.tik.tools?uniqueId=${LIVE_USERNAME}&apiKey=${API_KEY}`);
|
|
120
|
+
let events = 0;
|
|
121
|
+
|
|
122
|
+
ws.on('open', () => console.log(`\nā
Connected to @${LIVE_USERNAME} - streaming events...\n`));
|
|
123
|
+
ws.on('message', (raw) => {
|
|
124
|
+
const msg = JSON.parse(raw);
|
|
125
|
+
events++;
|
|
126
|
+
const d = msg.data || {};
|
|
127
|
+
const user = d.user?.uniqueId || '';
|
|
128
|
+
switch (msg.event) {
|
|
129
|
+
case 'chat': console.log(`š¬ ${user}: ${d.comment}`); break;
|
|
130
|
+
case 'gift': console.log(`š ${user} sent ${d.giftName} (${d.diamondCount}š)`); break;
|
|
131
|
+
case 'like': console.log(`ā¤ļø ${user} liked Ć ${d.likeCount}`); break;
|
|
132
|
+
case 'member': console.log(`š ${user} joined`); break;
|
|
133
|
+
case 'roomUserSeq': console.log(`š Viewers: ${d.viewerCount}`); break;
|
|
134
|
+
case 'roomInfo': console.log(`š” Room: ${msg.roomId}`); break;
|
|
135
|
+
default: console.log(`š¦ ${msg.event}`); break;
|
|
136
|
+
}
|
|
137
|
+
});
|
|
138
|
+
ws.on('close', () => console.log(`\nš Disconnected. Received ${events} events.\n`));
|
|
139
|
+
// Press Ctrl+C to stop. Community tier caps each WebSocket at 2 hours.
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
</details>
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## JavaScript (CommonJS)
|
|
147
|
+
|
|
148
|
+
```javascript
|
|
149
|
+
const { TikTokLive } = require('tiktok-live-api');
|
|
150
|
+
|
|
151
|
+
const client = new TikTokLive('streamer_username', { apiKey: 'YOUR_API_KEY' });
|
|
152
|
+
client.on('chat', (e) => console.log(`${e.user.uniqueId}: ${e.comment}`));
|
|
153
|
+
client.connect();
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## Get a Free API Key
|
|
157
|
+
|
|
158
|
+
1. Go to [tik.tools](https://tik.tools)
|
|
159
|
+
2. Sign up (no credit card required)
|
|
160
|
+
3. Copy your API key
|
|
161
|
+
|
|
162
|
+
The free **Community** tier gives you 2,500 requests/day and 15 WebSocket connections (2 hours per connection). Forever free.
|
|
163
|
+
|
|
164
|
+
## Environment Variable
|
|
165
|
+
|
|
166
|
+
Instead of passing `apiKey` directly, you can set it as an environment variable:
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
# Linux / macOS
|
|
170
|
+
export TIKTOOL_API_KEY=your_api_key_here
|
|
171
|
+
|
|
172
|
+
# Windows (CMD)
|
|
173
|
+
set TIKTOOL_API_KEY=your_api_key_here
|
|
174
|
+
|
|
175
|
+
# Windows (PowerShell)
|
|
176
|
+
$env:TIKTOOL_API_KEY="your_api_key_here"
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
```typescript
|
|
180
|
+
import { TikTokLive } from 'tiktok-live-api';
|
|
181
|
+
|
|
182
|
+
// Automatically reads TIKTOOL_API_KEY from environment
|
|
183
|
+
const client = new TikTokLive('streamer_username');
|
|
184
|
+
client.on('chat', (e) => console.log(e.comment));
|
|
185
|
+
client.connect();
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## REST API - leaderboards, recruiting, profiles, gifts
|
|
189
|
+
|
|
190
|
+
The WebSocket client streams live events. For everything else - leaderboards,
|
|
191
|
+
gaming ranks, recruiting, live status, gift catalogs, profiles - use the
|
|
192
|
+
`TikTool` REST client. One method per endpoint, fully promise-based.
|
|
193
|
+
|
|
194
|
+
```typescript
|
|
195
|
+
import { TikTool } from 'tiktok-live-api';
|
|
196
|
+
|
|
197
|
+
const api = new TikTool({ apiKey: 'YOUR_KEY' });
|
|
198
|
+
|
|
199
|
+
// Live status (single + bulk)
|
|
200
|
+
await api.liveStatus('charlidamelio');
|
|
201
|
+
await api.bulkLiveCheck(['user1', 'user2', 'user3']);
|
|
202
|
+
|
|
203
|
+
// Leaderboards + rankings
|
|
204
|
+
await api.leaderboard({ region: 'US+' });
|
|
205
|
+
await api.ranklistGaming('US+');
|
|
206
|
+
await api.regionMovers('US+'); // entered top today, below cutoff now
|
|
207
|
+
|
|
208
|
+
// Recruiting (Global Agency) - find eligible creators
|
|
209
|
+
await api.eligibleCreators({ region: 'US+', limit: 50, min_score: 1000 });
|
|
210
|
+
|
|
211
|
+
// Profiles + gifts
|
|
212
|
+
await api.profileInfo('khaby.lame');
|
|
213
|
+
await api.userProfile('khaby.lame');
|
|
214
|
+
await api.giftsByCountry('US');
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Tier gating is enforced server-side: a call above your tier throws a
|
|
218
|
+
`TikToolError` with `status === 403`. Any endpoint not yet wrapped is reachable
|
|
219
|
+
via `api.request('/webcast/...', { query })`.
|
|
220
|
+
|
|
221
|
+
```typescript
|
|
222
|
+
import { TikTool, TikToolError } from 'tiktok-live-api';
|
|
223
|
+
try {
|
|
224
|
+
await api.eligibleCreators({ region: 'US+' });
|
|
225
|
+
} catch (e) {
|
|
226
|
+
if (e instanceof TikToolError && e.status === 403) {
|
|
227
|
+
console.log('Upgrade required:', e.message);
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Method groups: signing/connection, live status, rankings/leaderboards, gifts,
|
|
233
|
+
user/profile, content/feed, live analytics, moderation, CAPTCHA solver, captions.
|
|
234
|
+
See [the full endpoint + tier matrix](https://tik.tools/docs).
|
|
235
|
+
|
|
236
|
+
## Events (54 v3 event types)
|
|
237
|
+
|
|
238
|
+
Every event is dispatched by name. `client.on('chat', e => ...)` is fully typed end-to-end. Each event payload extends `BaseEvent` (`type`, `timestamp`, `msgId`, optional `protoVersion: 1 | 2 | 3`).
|
|
239
|
+
|
|
240
|
+
### Core live events
|
|
241
|
+
|
|
242
|
+
| Event | Description |
|
|
243
|
+
|---|---|
|
|
244
|
+
| `connected` | WebSocket open. |
|
|
245
|
+
| `disconnected` | WebSocket close. |
|
|
246
|
+
| `roomInfo` | One-shot post-connect: `{ roomId, wsHost, clusterRegion, connectedAt }`. |
|
|
247
|
+
| `chat` | Chat message. `user`, `comment`, `emotes`, optional `starred`. **v3** adds `language` (auto-detected ISO 639-1) + `messageUuid` (moderation correlation). |
|
|
248
|
+
| `gift` | Virtual gift. `giftId`, `giftName`, `diamondCount`, `repeatCount`, `repeatEnd`, `giftType`. **v3** adds `transactionId` (dedup key), `senderUserId`, `relationship` (`joinDayNumber`, `fromUser`, `toUser`). |
|
|
249
|
+
| `like` | Like batch. `likeCount`, `totalLikes`. |
|
|
250
|
+
| `member` | Viewer joined. **v3** adds `actionCode`, `entrySource` (`"homepage_hot-live_cell"`, `"follow-tab"`, ...), `entryAction` (`"draw"`/`"click"`), `entryType` (`"rec"` = algorithmic). |
|
|
251
|
+
| `social` | Follow / share. |
|
|
252
|
+
| `roomUserSeq` | Periodic viewer count tick. |
|
|
253
|
+
| `subscribe` | A viewer subscribed. |
|
|
254
|
+
|
|
255
|
+
### PK / battle events
|
|
256
|
+
|
|
257
|
+
| Event | Description |
|
|
258
|
+
|---|---|
|
|
259
|
+
| `battle` | PK lifecycle. `status` (1=ACTIVE, 2=STARTING, 3=ENDED, 4=PREPARING), `battleDuration`, `teams`. **v3** adds `extraHostUserIds`, `layoutSubtype`. |
|
|
260
|
+
| `battleArmies` | Per-host MVP breakdown ticking through the PK. `hosts[].contributors[]` sorted MVP first. **v3** adds `transactionId`. |
|
|
261
|
+
| `battleItemCard` | Booster card: x2 / x3 multipliers, gloves (crit), mist, thunder, extra-time, match-guide. Includes overlay assets from TikTok's CDN. |
|
|
262
|
+
| `battlePunishFinish` | Loser-side punishment screen ended. |
|
|
263
|
+
| `battleNotice` | PK notice (version-mismatch toast, invite-failure). |
|
|
264
|
+
| `battleGameplay` | PK mini-game state (Whack-A-Mole, Tic-Tac-Toe variants). |
|
|
265
|
+
| `linkLayer` | PK / link-mic negotiation (invite, cancel, accept, source change). |
|
|
266
|
+
| `linkMicOpponentGift` | Per-gift breakdown from the OPPONENT side of a PK. |
|
|
267
|
+
| `linkScreenChange` | PK split-screen layout flip (1v1 / 1vN / cohost mode swap). |
|
|
268
|
+
| `cohostLayoutUpdate` | Cohost layout subtype change. |
|
|
269
|
+
| `linkMic`, `linkMicLayoutState`, `link` | Generic link-mic envelopes. |
|
|
270
|
+
| `competition`, `competitionContributor` | Cross-stream competition + per-contributor breakdown. |
|
|
271
|
+
| `guestShowdown` | Guest showdown lifecycle. |
|
|
272
|
+
|
|
273
|
+
### Native captions (v3)
|
|
274
|
+
|
|
275
|
+
| Event | Description |
|
|
276
|
+
|---|---|
|
|
277
|
+
| `caption` | **NEW in v3.** TikTok native auto-captions on the LIVE WebSocket. `text`, `isFinal`, `startedAtMs`, `endsAtMs`. Independent of the operator-managed [TikTok Live Captions](https://tik.tools/captions) product. |
|
|
278
|
+
|
|
279
|
+
### Creator-side events
|
|
280
|
+
|
|
281
|
+
| Event | Description |
|
|
282
|
+
|---|---|
|
|
283
|
+
| `goalUpdate` | Stream goal progress (subscriber / gift / watch-time goals). |
|
|
284
|
+
| `commentTray` | Comment tray UI state change. |
|
|
285
|
+
| `roomPin` | A chat got pinned by the host or a moderator. |
|
|
286
|
+
| `hostBoard` | Host leaderboard board update. |
|
|
287
|
+
| `privilegeAdvance` | Viewer privilege tier-up notification with overlay assets. |
|
|
288
|
+
| `anchorToolModification` | Creator modified a panel/widget. |
|
|
289
|
+
| `inRoomBanner` | In-room activity banner. |
|
|
290
|
+
| `roomSticker` | Room-wide sticker drop. |
|
|
291
|
+
| `bottomMessage` | Bottom-bar safety / risk notice. |
|
|
292
|
+
| `accessRecall`, `roomVerify` | Content-classification recheck events. |
|
|
293
|
+
| `smbBoard` | SMB (small-business) board overlay. |
|
|
294
|
+
| `streamStatus` | Stream status flip. |
|
|
295
|
+
| `shareRevenueNotice` | Share-revenue subscriber count change. |
|
|
296
|
+
| `capsule` | TikTok service-plus pin reminder. |
|
|
297
|
+
| `hotRoom` | TikTok promoted the room to a high-traffic slot. |
|
|
298
|
+
| `linkMicAnchorGuide` | Anchor (creator) guide nudges. |
|
|
299
|
+
|
|
300
|
+
### Moderation / safety
|
|
301
|
+
|
|
302
|
+
| Event | Description |
|
|
303
|
+
|---|---|
|
|
304
|
+
| `imDelete` | Chat moderation delete. Correlate via `chat.messageUuid` (v3). |
|
|
305
|
+
| `unauthorizedMember` | Unauthorized viewer hit a gated feature. |
|
|
306
|
+
| `barrage` | Raw barrage feed (announcements, special effects). |
|
|
307
|
+
| `superFan`, `superFanJoin`, `superFanBox` | Super-fan lifecycle. |
|
|
308
|
+
| `emoteChat` | Inline emote message. |
|
|
309
|
+
|
|
310
|
+
### Gift catalog + ecommerce
|
|
311
|
+
|
|
312
|
+
| Event | Description |
|
|
313
|
+
|---|---|
|
|
314
|
+
| `giftPanelUpdate` | Real-time gift catalog change. Cache-bust your local catalog. |
|
|
315
|
+
| `giftDynamicRestriction` | Per-room gift availability flip / age-gating. |
|
|
316
|
+
| `giftGallery` | Host-side gift wall snapshot. |
|
|
317
|
+
| `giftUnlock` | Host unlocked a gated gift. |
|
|
318
|
+
| `viewerPicksUpdate` | TikTok-promoted viewer-pick gift highlights. |
|
|
319
|
+
| `oecLiveShopping`, `oecLiveManager`, `oecLiveBillboard` | OEC live-shopping events. |
|
|
320
|
+
| `ecShortItemRefresh` | Lucky-bag drop refreshed. |
|
|
321
|
+
|
|
322
|
+
### Engagement + AI
|
|
323
|
+
|
|
324
|
+
| Event | Description |
|
|
325
|
+
|---|---|
|
|
326
|
+
| `aiSummary` | TikTok AI summary of the room (entry-time recap, multi-language). |
|
|
327
|
+
| `poll`, `shortTouch` | In-stream poll lifecycle. |
|
|
328
|
+
| `rankText`, `rankUpdate`, `hourlyRank` | Rank events. |
|
|
329
|
+
| `question`, `questionSelected`, `questionSlideDown` | Q&A round events. |
|
|
330
|
+
| `pictionaryUpdate`, `pictionaryEnd`, `pictionaryExit` | Drawing-game round events. |
|
|
331
|
+
| `fansEvent`, `fanTicket` | Fan-club events. |
|
|
332
|
+
| `envelope`, `envelopePortal` | Red-envelope drops + multi-room portal chain. |
|
|
333
|
+
| `gameMoment`, `gameServerFeature` | TikTok Gaming live integration. |
|
|
334
|
+
| `groupLiveMemberNotify` | Group-live member join / leave. |
|
|
335
|
+
| `perception` | Perception event (mute cancel, TikTok hint signal). |
|
|
336
|
+
| `control`, `room`, `liveIntro` | Stream control + room metadata. |
|
|
337
|
+
|
|
338
|
+
### Catch-all
|
|
339
|
+
|
|
340
|
+
- `event` - Fires for every decoded event (dump-to-queue pattern).
|
|
341
|
+
- `unknown` - Fires when TikTok ships a method we don't yet model (forward-compat hook).
|
|
342
|
+
|
|
343
|
+
All events are fully typed with TypeScript interfaces. Your IDE will show autocompletion for every field. See [full per-event JSON examples + field tables](https://tik.tools/docs).
|
|
344
|
+
|
|
345
|
+
### Battle / PK example
|
|
346
|
+
|
|
347
|
+
```typescript
|
|
348
|
+
import { TikTokLive } from 'tiktok-live-api';
|
|
349
|
+
|
|
350
|
+
const client = new TikTokLive({ uniqueId: 'creator_username', apiKey: 'tk_...' });
|
|
351
|
+
|
|
352
|
+
client.on('battle', e => console.log('PK', e.status, e.battleId, 'duration=', e.battleDuration));
|
|
353
|
+
|
|
354
|
+
client.on('battleArmies', e => {
|
|
355
|
+
console.log('Countdown:', e.secsRemaining, 's');
|
|
356
|
+
for (const host of e.hosts ?? []) {
|
|
357
|
+
console.log(`@${host.hostUserId} team total=${host.teamTotalScore}`);
|
|
358
|
+
const mvp = host.contributors[0];
|
|
359
|
+
if (mvp) console.log(` MVP @${mvp.nickname} score=${mvp.score}`);
|
|
360
|
+
}
|
|
361
|
+
});
|
|
362
|
+
|
|
363
|
+
client.on('battleItemCard', e => {
|
|
364
|
+
if (e.multiplier > 0) console.log(`x${e.multiplier} booster from @${e.senderUniqueId}`);
|
|
365
|
+
else console.log(`Effect ${e.effect} from @${e.senderUniqueId} (${e.durationSec}s)`);
|
|
366
|
+
});
|
|
367
|
+
|
|
368
|
+
await client.connect();
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
|
|
372
|
+
## Live Captions (Speech-to-Text)
|
|
373
|
+
|
|
374
|
+
Transcribe and translate any TikTok LIVE stream in real-time. **This feature is unique to TikTool Live - no other TikTok library offers it.**
|
|
375
|
+
|
|
376
|
+
```typescript
|
|
377
|
+
import { TikTokCaptions } from 'tiktok-live-api';
|
|
378
|
+
|
|
379
|
+
const captions = new TikTokCaptions('streamer_username', {
|
|
380
|
+
apiKey: 'YOUR_API_KEY',
|
|
381
|
+
translate: 'en', // translate to English
|
|
382
|
+
diarization: true, // identify who is speaking
|
|
383
|
+
});
|
|
384
|
+
|
|
385
|
+
captions.on('caption', (event) => {
|
|
386
|
+
const speaker = event.speaker ? `[${event.speaker}] ` : '';
|
|
387
|
+
console.log(`${speaker}${event.text}${event.isFinal ? ' ā' : '...'}`);
|
|
388
|
+
});
|
|
389
|
+
|
|
390
|
+
captions.on('translation', (event) => {
|
|
391
|
+
console.log(` ā ${event.text}`);
|
|
392
|
+
});
|
|
393
|
+
|
|
394
|
+
captions.on('credits', (event) => {
|
|
395
|
+
console.log(`${event.remaining}/${event.total} minutes remaining`);
|
|
396
|
+
});
|
|
397
|
+
|
|
398
|
+
captions.connect();
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
### Caption Events
|
|
402
|
+
|
|
403
|
+
| Event | Description | Key Fields |
|
|
404
|
+
|-------|-------------|------------|
|
|
405
|
+
| `caption` | Real-time caption text | `text`, `speaker`, `isFinal`, `language` |
|
|
406
|
+
| `translation` | Translated caption | `text`, `sourceLanguage`, `targetLanguage` |
|
|
407
|
+
| `credits` | Credit balance update | `total`, `used`, `remaining` |
|
|
408
|
+
| `credits_low` | Low credit warning | `remaining`, `percentage` |
|
|
409
|
+
| `status` | Session status | `status`, `message` |
|
|
410
|
+
|
|
411
|
+
## Chat Bot Example
|
|
412
|
+
|
|
413
|
+
```typescript
|
|
414
|
+
import { TikTokLive } from 'tiktok-live-api';
|
|
415
|
+
|
|
416
|
+
const client = new TikTokLive('streamer_username', { apiKey: 'YOUR_API_KEY' });
|
|
417
|
+
const giftLeaderboard = new Map<string, number>();
|
|
418
|
+
let messageCount = 0;
|
|
419
|
+
|
|
420
|
+
client.on('chat', (event) => {
|
|
421
|
+
messageCount++;
|
|
422
|
+
const msg = event.comment.toLowerCase().trim();
|
|
423
|
+
const user = event.user.uniqueId;
|
|
424
|
+
|
|
425
|
+
if (msg === '!hello') {
|
|
426
|
+
console.log(`>> BOT: Welcome ${user}! š`);
|
|
427
|
+
} else if (msg === '!stats') {
|
|
428
|
+
console.log(`>> BOT: ${messageCount} messages, ${giftLeaderboard.size} gifters`);
|
|
429
|
+
} else if (msg === '!top') {
|
|
430
|
+
const top = [...giftLeaderboard.entries()]
|
|
431
|
+
.sort((a, b) => b[1] - a[1])
|
|
432
|
+
.slice(0, 5);
|
|
433
|
+
top.forEach(([name, diamonds], i) => {
|
|
434
|
+
console.log(` ${i + 1}. ${name} - ${diamonds} š`);
|
|
435
|
+
});
|
|
436
|
+
}
|
|
437
|
+
});
|
|
438
|
+
|
|
439
|
+
client.on('gift', (event) => {
|
|
440
|
+
const user = event.user.uniqueId;
|
|
441
|
+
const diamonds = event.diamondCount || 0;
|
|
442
|
+
giftLeaderboard.set(user, (giftLeaderboard.get(user) || 0) + diamonds);
|
|
443
|
+
});
|
|
444
|
+
|
|
445
|
+
client.connect();
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
## TypeScript
|
|
449
|
+
|
|
450
|
+
This package ships with full TypeScript support. All events are typed:
|
|
451
|
+
|
|
452
|
+
```typescript
|
|
453
|
+
import { TikTokLive, ChatEvent, GiftEvent } from 'tiktok-live-api';
|
|
454
|
+
|
|
455
|
+
const client = new TikTokLive('streamer', { apiKey: 'KEY' });
|
|
456
|
+
|
|
457
|
+
// Full autocompletion - your IDE knows the type of `event`
|
|
458
|
+
client.on('chat', (event: ChatEvent) => {
|
|
459
|
+
console.log(event.user.uniqueId); // ā typed
|
|
460
|
+
console.log(event.comment); // ā typed
|
|
461
|
+
});
|
|
462
|
+
|
|
463
|
+
client.on('gift', (event: GiftEvent) => {
|
|
464
|
+
console.log(event.giftName); // ā typed
|
|
465
|
+
console.log(event.diamondCount); // ā typed
|
|
466
|
+
});
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
## API Reference
|
|
470
|
+
|
|
471
|
+
### `new TikTokLive(uniqueId, options?)`
|
|
472
|
+
|
|
473
|
+
| Option | Type | Default | Description |
|
|
474
|
+
|--------|------|---------|-------------|
|
|
475
|
+
| `apiKey` | `string` | `process.env.TIKTOOL_API_KEY` | Your TikTool API key |
|
|
476
|
+
| `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
|
|
477
|
+
| `maxReconnectAttempts` | `number` | `5` | Max reconnection attempts |
|
|
478
|
+
|
|
479
|
+
**Methods:**
|
|
480
|
+
- `client.on(event, handler)` - Register event handler
|
|
481
|
+
- `client.off(event, handler)` - Remove event handler
|
|
482
|
+
- `client.connect()` - Connect to stream (returns Promise)
|
|
483
|
+
- `client.disconnect()` - Disconnect from stream
|
|
484
|
+
- `client.connected` - Whether currently connected
|
|
485
|
+
- `client.eventCount` - Total events received
|
|
486
|
+
|
|
487
|
+
### `new TikTokCaptions(uniqueId, options?)`
|
|
488
|
+
|
|
489
|
+
| Option | Type | Default | Description |
|
|
490
|
+
|--------|------|---------|-------------|
|
|
491
|
+
| `apiKey` | `string` | `process.env.TIKTOOL_API_KEY` | Your TikTool API key |
|
|
492
|
+
| `translate` | `string` | `undefined` | Target translation language |
|
|
493
|
+
| `diarization` | `boolean` | `true` | Enable speaker identification |
|
|
494
|
+
| `maxDurationMinutes` | `number` | `60` | Auto-disconnect timer |
|
|
495
|
+
|
|
496
|
+
**Methods:**
|
|
497
|
+
- `captions.on(event, handler)` - Register event handler
|
|
498
|
+
- `captions.off(event, handler)` - Remove event handler
|
|
499
|
+
- `captions.connect()` - Start receiving captions (returns Promise)
|
|
500
|
+
- `captions.disconnect()` - Stop receiving captions
|
|
501
|
+
- `captions.connected` - Whether currently connected
|
|
502
|
+
|
|
503
|
+
## Why tiktok-live-api?
|
|
504
|
+
|
|
505
|
+
| | tiktok-live-api | tiktok-live-connector | TikTokLive (Python) |
|
|
506
|
+
|---|---|---|---|
|
|
507
|
+
| **Type** | Managed agency-grade platform | Self-hosted client | Self-hosted client |
|
|
508
|
+
| **Hosting** | ā Fully managed, 99.9% uptime | You run the client; signing via paid backend | You run the client; signing via paid backend |
|
|
509
|
+
| **TypeScript** | ā First-class, fully typed | ā Typed | N/A (Python) |
|
|
510
|
+
| **AI Live Captions (STT + translation)** | ā 60+ languages | ā | ā |
|
|
511
|
+
| **Unreal Engine plugin** | ā | ā | ā |
|
|
512
|
+
| **Gifter Intel (LTV, archetypes)** | ā | ā | ā |
|
|
513
|
+
| **Live Leaderboards (real-time)** | ā Regional + global | ā | ā |
|
|
514
|
+
| **Battle History + Per-Match Timeline** | ā | ā | ā |
|
|
515
|
+
| **League Rankings (Diamond Rush)** | ā | ā | ā |
|
|
516
|
+
| **Real-time Discord + Telegram Alerts** | ā | ā | ā |
|
|
517
|
+
| **Sniper Gap (live battle tracker)** | ā | ā | ā |
|
|
518
|
+
| **Agency CRM + Watchlists** | ā | ā | ā |
|
|
519
|
+
| **Public Profile Pages (creator + gifter)** | ā Indexed | ā | ā |
|
|
520
|
+
| **CAPTCHA Solving** | ā Built-in (Pro+) | Via signing backend | Via signing backend |
|
|
521
|
+
| **Feed Discovery** | ā See who's live | ā | ā |
|
|
522
|
+
| **Free Tier** | ā 2,500 req/day, 15 WS, 2h per WS | ā MIT-licensed | ā MIT-licensed |
|
|
523
|
+
| **ESM + CJS** | ā Both supported | ā | N/A (Python) |
|
|
524
|
+
|
|
525
|
+
## Pricing
|
|
526
|
+
|
|
527
|
+
Tier is enforced server-side by your API key. Snapshot below; the full feature matrix lives at [tik.tools/pricing](https://tik.tools/pricing).
|
|
528
|
+
|
|
529
|
+
| Tier | Weekly | Monthly | Req/min | Req/day | Concurrent WS | WS max duration | Bulk check |
|
|
530
|
+
|---|---|---|---|---|---|---|---|
|
|
531
|
+
| Community | free | free | 5 (300/h) | 2,500 | 1 | 2h | - |
|
|
532
|
+
| Basic | $7 | $19 | 60 | 10,000 | 20 | 8h | 10/req |
|
|
533
|
+
| Pro | $15 | $49 | 300 | 75,000 | 50 | 12h | 50/req |
|
|
534
|
+
| Ultra | $45 | $149 | 1,000 | 300,000 | 250 | 24h | 100/req |
|
|
535
|
+
| **Global Agency** | $119 | $399 | 5,000 | 1,000,000 | 500 | 24h | 200/req |
|
|
536
|
+
|
|
537
|
+
- **Community** ($0 forever): 1 concurrent WS, 2h per session, masked leaderboards. Designed for devs building apps - upgrade when you need real usernames. No datacenter proxies; calls come from your own IP.
|
|
538
|
+
- **Basic** ($7/wk - $19/mo): 60 req/min, 20 concurrent WS, 8h per WS, datacenter proxies, masked leaderboards, **12h/wk - 60h/mo of bundled AI Live Captions**.
|
|
539
|
+
- **Pro** ($15/wk - $49/mo): 300 req/min, 50 concurrent WS, 12h per WS, **unmasked leaderboards**, Feed Discovery, regional leaderboard signed URLs, **30h/wk - 140h/mo of bundled AI Live Captions**.
|
|
540
|
+
- **Ultra** ($45/wk - $149/mo): 1,000 req/min, 250 concurrent WS, 24h per WS, **Gift Catalog API** (full TikTok gift catalog continuously re-synced), **League Rankings unmasked**, CSV exports, 99.5% uptime SLA, **60h/wk - 260h/mo of bundled AI Live Captions**.
|
|
541
|
+
- **Global Agency** ($119/wk - $399/mo): Everything in Ultra plus **Live Gifter Firehose WS** (region / league / global filters + min-diamond threshold), VIP Telegram alerts, VIP Web Vault (unmasked historical visual access), **gifter intel unmasked**, 500 concurrent WS, **120h/wk - 500h/mo of bundled AI Live Captions**.
|
|
542
|
+
|
|
543
|
+
Standalone AI Live Captions plans (no API key needed) on [tik.tools/captions](https://tik.tools/captions): Casual ($7/wk - $29/mo for 12h/wk - 60h/mo), Pro ($15/wk - $59/mo for 30h/wk - 140h/mo), Extreme ($29/wk - $99/mo for 60h/wk - 260h/mo). Auto-renew + early-renewal on exhaust so captions never drop mid-stream.
|
|
544
|
+
|
|
545
|
+
### Live Gifter Firehose - Global Agency
|
|
546
|
+
|
|
547
|
+
Real-time gift event stream from our Dragonfly fan-out. Filter by region, league, or globally; cap by minimum diamond threshold. Mid-stream filter updates supported via `update_filter` frame, no reconnect needed.
|
|
548
|
+
|
|
549
|
+
```js
|
|
550
|
+
const ws = new WebSocket(
|
|
551
|
+
`wss://api.tik.tools/firehose/gifters?apiKey=${KEY}&mode=region®ion=US%2B&min_diamonds=1000`
|
|
552
|
+
)
|
|
553
|
+
ws.on('message', (raw) => {
|
|
554
|
+
const evt = JSON.parse(raw)
|
|
555
|
+
// evt: { type:'gifter_alert', ts, gifter:{username,displayName,isAnonymous},
|
|
556
|
+
// creator:{uniqueId}, gift:{name,totalDiamonds}, region }
|
|
557
|
+
})
|
|
558
|
+
// Update filter without reconnect
|
|
559
|
+
ws.send(JSON.stringify({ type: 'update_filter', mode: 'global', min_diamonds: 5000 }))
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
Modes: `global` (all regions), `region` (single region code), `league` (region + league class, e.g. `B2`).
|
|
563
|
+
|
|
564
|
+
## Also Available
|
|
565
|
+
|
|
566
|
+
- **Python**: [`pip install tiktok-live-api`](https://pypi.org/project/tiktok-live-api/)
|
|
567
|
+
- **Any language**: Connect via WebSocket: `wss://api.tik.tools?uniqueId=USERNAME&apiKey=KEY`
|
|
568
|
+
- **Unreal Engine**: Native C++/Blueprint plugin
|
|
569
|
+
|
|
570
|
+
## Links
|
|
571
|
+
|
|
572
|
+
- š **Website**: [tik.tools](https://tik.tools)
|
|
573
|
+
- š **Documentation**: [tik.tools/docs](https://tik.tools/docs)
|
|
574
|
+
- š **Python SDK**: [pypi.org/project/tiktok-live-api](https://pypi.org/project/tiktok-live-api/)
|
|
575
|
+
- š» **GitHub**: [github.com/tiktool/tiktok-live-api](https://github.com/tiktool/tiktok-live-api)
|
|
576
|
+
|
|
577
|
+
## License
|
|
578
|
+
|
|
579
|
+
MIT
|