# TikTok LIVE Room Status & Chat Capture Tool (`nimbryxo-studio/tiktok-live-room-status-and-chat-capture-tool`) Actor

Check TikTok usernames for an active LIVE stream and get room title, viewer counts, and host profile, or capture real-time chat, gifts, likes, and other events while the stream runs.

- **URL**: https://apify.com/nimbryxo-studio/tiktok-live-room-status-and-chat-capture-tool.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** Social media, Videos, Automation
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## TikTok LIVE Room Status & Chat Capture Tool

Check whether a TikTok creator is currently LIVE and pull the room's title, viewer counts, and host profile — no login needed. Optionally, with a TikTok session cookie, stay connected to the stream and capture its chat messages, gifts, likes, and other events as they happen.

### What this actor does

- **Checks usernames or LIVE URLs** for an active broadcast
- **Room-status mode (no cookie):** one record per live user with title, viewer counts, stream URLs, and host profile
- **Event-capture mode (session cookie):** stays connected and records every chat message, gift, like, join, share, and viewer-stats update as its own record
- **Time and count limits:** stops after `connectionDuration` seconds or `eventCap` events, whichever comes first
- **Event-type filter:** capture only the event categories you care about — unmapped (`other`) events always pass through regardless of the filter, since they can't be matched to a selected category
- **Exits cleanly with zero records when nobody is live** — that's expected behavior, not an error, and empty fields are always omitted

### Output per room-status record

- `roomId` — TikTok's LIVE room identifier
- `hostUsername` — broadcaster's TikTok username
- `hostUserId` — broadcaster's TikTok user ID
- `hostDisplayName` — broadcaster's display name
- `hostVerified` — whether the host's account is verified
- `hostBio` — the host's profile bio text
- `hostAvatarUrl` — host's avatar image URL
- `hostFollowerCount`, `hostFollowingCount` — the host's follower and following counts
- `liveTitle` — the current LIVE stream's title
- `liveStatus`, `liveRoomMode` — TikTok's room status and mode values
- `startTime`, `startedAt` — when the stream started, as a raw timestamp and as an ISO 8601 string
- `totalViewers` — cumulative viewer count since the stream started
- `currentViewers` — current live viewer count
- `liveUrl` — the broadcaster's LIVE URL
- `streamUrls` — a map of stream quality labels (e.g. `hls_720p`, `flv_1080p60`) to their playback URLs, when TikTok exposes them
- `scrapedAt` — when the record was fetched

### Output per captured event record

- `roomId` — the LIVE room the event came from
- `eventType` — `chat`, `gift`, `like`, `follow`, `share`, `join`, `stats`, `other`, or `raw`
- `receivedAt` — ISO 8601 UTC timestamp when the event arrived
- `user` — object with `id`, `username`, `displayName`, `avatarUrl` for the user tied to the event, when TikTok includes one
- `payload` — event-specific details:
  - chat: `text`, and `emotes` when the message includes them
  - gift: `giftName`, `giftId`, `giftCount`
  - like: `totalLikes`
  - stats: `viewerCount`, `totalUsers`
  - other (unmapped event types): `rawMethod` and `payloadSize` for reference
  - raw (undecodable WebSocket frames): `rawBase64` and `frameSize`
  - follow/share/join events carry only the `user` object, with no extra `payload`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `usernames` | array | – | TikTok usernames to check for an active LIVE session (without `@`) |
| `liveUrls` | array | – | Direct TikTok LIVE URLs, an alternative to `usernames` |
| `connectionDuration` | integer | `60` | Seconds to stay connected to each LIVE stream (10–3600) |
| `eventCap` | integer | `500` | Stop capturing events from a stream after this many (1–10,000), per stream |
| `eventTypes` | array | `["all"]` | Which event categories to keep: `chat`, `gift`, `like`, `follow`, `share`, `join`, `stats`, or `all` |
| `sessionCookie` | string | – | TikTok `sessionid` cookie value. Without it, the actor only returns room-status records |

#### Example: check room status, no cookie

```json
{ "usernames": ["natgeo"], "connectionDuration": 10 }
```

#### Example: capture events with a session cookie

```json
{
  "usernames": ["khaby.lame"],
  "connectionDuration": 120,
  "eventCap": 1000,
  "eventTypes": ["chat", "gift", "stats"],
  "sessionCookie": "your_sessionid_value_here"
}
```

#### Example: check several accounts at once

```json
{ "usernames": ["natgeo", "bbcnews", "cnn"], "connectionDuration": 60 }
```

#### Example: check a specific LIVE URL

```json
{ "liveUrls": ["https://www.tiktok.com/@natgeo/live"], "connectionDuration": 30 }
```

### Use cases

- **Live status alerts** — check a watchlist of creators and know within seconds who's currently live
- **Community management** — follow your own brand's chat in real time during a live event
- **Audience research** — capture viewer counts and gift activity to gauge how a stream performed
- **Event archiving** — record the chat and event timeline from a launch or performance streamed on TikTok LIVE
- **Moderation review** — pull a stream's chat for later review of comments or reported behavior

### FAQ

**Is this affiliated with TikTok?**
No. This is an independent, third-party actor that reads TikTok's publicly available LIVE room data and is not affiliated with or endorsed by TikTok.

**What happens if the account isn't live when the actor runs?**
The actor returns zero records and logs that the creator wasn't live — this is expected, not a failure. Run it during the creator's usual streaming hours for the best chance of a hit.

**Do I need a cookie for room-status mode?**
No. Checking whether someone is live and getting the room's title, viewer counts, and host profile works without any login.

**How do I get a session cookie for event-capture mode?**
Log into TikTok in a browser, open its developer tools, find the cookie named `sessionid` under Application/Storage, and paste its value into `sessionCookie`.

**Is my session cookie stored anywhere?**
No. It's used only to connect to the LIVE stream during the run and isn't saved or logged.

**What does `connectionDuration` actually limit?**
How long the actor stays connected to each stream before moving on. A short window (10–60 seconds) is enough to confirm live status; a longer one is needed to capture a meaningful chat/event history.

**Can I check multiple accounts in one run?**
Yes — list several usernames, and the actor checks each one in turn, connecting and collecting for `connectionDuration` seconds before moving to the next.

**What are the `other` and `raw` event types?**
Some TikTok LIVE message types aren't mapped to a named category — those are kept as `other` events with `rawMethod` and `payloadSize` in the payload, and they're always captured regardless of your `eventTypes` filter. Occasionally a WebSocket frame can't be decoded at all; when that happens and `eventTypes` includes `all` (the default), it's kept as a `raw` event with the frame's base64 bytes and size, so nothing is silently dropped.

**What quality options appear in `streamUrls`?**
Whatever TikTok exposes for that stream at the time — typically a mix of HLS and FLV links across resolutions such as 360p, 720p, and 1080p60, when the room is actively broadcasting.

# Actor input Schema

## `usernames` (type: `array`):

TikTok usernames to watch for LIVE streams (without the @ symbol). The actor will check each username for an active LIVE session. Note: the prefill account may not always be live — runs during off-hours may produce 0 rows. This is expected behavior.

## `liveUrls` (type: `array`):

Direct TikTok LIVE URLs (e.g. https://www.tiktok.com/@username/live). Alternative to usernames.

## `connectionDuration` (type: `integer`):

How long to stay connected to each LIVE stream and collect events.

## `eventCap` (type: `integer`):

Stop collecting events from a stream after capturing this many. Applies per stream.

## `eventTypes` (type: `array`):

Which event types to capture and push to the dataset. Use 'all' to capture every event type.

## `sessionCookie` (type: `string`):

Optional. Value of the TikTok `sessionid` cookie from a logged-in browser session. When provided, the actor captures real-time events (chat, gifts, likes, follows, joins) from the LIVE stream. Without this, the actor runs in room-metadata mode (1 row per live user: title, viewer count, stream URLs, host profile). To obtain: open TikTok in a browser → DevTools → Application → Cookies → copy the `sessionid` value.

## Actor input object example

```json
{
  "usernames": [
    "natgeo"
  ],
  "connectionDuration": 10,
  "eventCap": 100,
  "eventTypes": [
    "all"
  ]
}
```

# Actor output Schema

## `events` (type: `string`):

Dataset containing all captured LIVE stream events.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "usernames": [
        "natgeo"
    ],
    "connectionDuration": 10,
    "eventCap": 100,
    "eventTypes": [
        "all"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/tiktok-live-room-status-and-chat-capture-tool").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "usernames": ["natgeo"],
    "connectionDuration": 10,
    "eventCap": 100,
    "eventTypes": ["all"],
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/tiktok-live-room-status-and-chat-capture-tool").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "usernames": [
    "natgeo"
  ],
  "connectionDuration": 10,
  "eventCap": 100,
  "eventTypes": [
    "all"
  ]
}' |
apify call nimbryxo-studio/tiktok-live-room-status-and-chat-capture-tool --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/tiktok-live-room-status-and-chat-capture-tool"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/wec60fCwOTbQwAqg7/builds/iiC9O1whFFD37TDyD/openapi.json