The CrossChat hub is a small web server on your PC. The chat window, the Theme Studio, the OBS widgets and the companion all use it, and so can your own overlays and tools.
- Base address:
http://127.0.0.1:4466(the"port"inconfig.json). The demo (Try the demo, orcontrol.py demo) runs on4477. - Live updates: one Server-Sent Events stream,
GET /events. - Changes:
POSTwith a JSON body, from the hub's own pages.
| Caller | Can |
|---|---|
The CrossChat window, the Theme Studio and the widgets (http://127.0.0.1:4466/…) |
Everything below |
Your own overlay pages (http://localhost:4466/custom/…) |
Their own files, and the public chat: /events (public types only), /settings, /version, /themes, /themes/<name>, and the page files under /web/ and /overlay/. Nothing else |
A program on this PC (no browser Origin) |
Every GET. POST needs Content-Type: application/json |
| A paired companion device (port 4467) | /, /whoami, /version, /events, /viewer, and POST to /send, /mod, /feature, /star, /quick, /test, /tts/say, /tts/skip |
| A page from any other website, or a local file | Nothing |
Put your own overlay pages in the folder named by "custom_overlays" in config.json. The hub serves them at http://localhost:4466/custom/<file> (an old http://127.0.0.1:4466/custom/… address is sent there). That address is kept apart from the CrossChat window's by the browser, so an overlay page you downloaded can show chat but can't reply, moderate or change anything as you. Inside one, /events and the other public addresses work as relative URLs; http://127.0.0.1:4466/events works too. See SECURITY.md for the rules in full.
<!doctype html>
<meta charset="utf-8">
<ul id="chat"></ul>
<script>
const list = document.getElementById('chat');
const feed = new EventSource('/events');
feed.onmessage = (e) => {
const event = JSON.parse(e.data);
if (event.type === 'msg' && event.kind === 'chat' && !event.hidden) {
const li = document.createElement('li');
li.dataset.id = event.id;
li.textContent = event.name + ': ' + event.text; // always textContent: chat is written by viewers
list.append(li);
}
if (event.type === 'delete') list.querySelector(`[data-id="${CSS.escape(event.id)}"]`)?.remove();
};
</script>Save it as my-chat.html in your custom overlays folder and add http://localhost:4466/custom/my-chat.html to OBS as a browser source.
The stream starts with the last 300 messages, then the current state (status, viewers, feature, emotes and the rest), then everything as it happens. Each event is one JSON object in a data: line, with a type.
Your own overlay pages get the chat as viewers see it: msg, delete, purge, clear, emotes, feature, status, theme and viewers. Messages your filters hide, and CrossChat's own notes, are left out; a message filtered after it showed arrives as a delete.
| Field | Meaning |
|---|---|
id |
CrossChat's id for the message |
t |
Time, in milliseconds since 1970 |
p |
Platform: twitch, youtube, kick, x, tiktok, facebook, instagram, rumble or system |
name |
The viewer's display name |
text |
What they wrote |
kind |
chat, event (a sub, gift, raid, cheer, Super Chat or membership) or note (a message from CrossChat itself) |
color |
The name colour the platform gave the viewer, or "" |
badges |
For example ["moderator", "subscriber"]. The streamer's own lines carry broadcaster (Twitch, Kick, TikTok, Facebook, Instagram) or owner (YouTube) |
emotes |
Twitch only: Twitch's own id:from-to,… list |
question |
true when the line looks like a question |
first |
"ever" for the viewer's first message in the channel (Twitch says so), "stream" for their first this stream |
hidden |
Why your filters hide it: bot, user, command or word. Hidden messages still arrive, so a page can show them to you; don't show them on stream |
alert |
For kind: "event": sub, resub, gift, raid, cheer, superchat, member, follow, share, like, join or other. YouTube Super Stickers and Rumble Rants come as superchat; the widgets tell them apart (a sticker's system starts with Super Sticker, a Rant has p: "rumble"). Treat any other value as other |
amount |
For alerts: months, number of gifts, viewers, bits or the Super Chat or Rant amount, as text ("5 subs", "$5.00"); for a TikTok gift, its name and count ("Rose ×5"); for TikTok likes, how many ("20"). Can be "" |
system |
For alerts: the platform's own line, such as nightowl_42 subscribed for 6 months! |
mid |
The platform's own message id, used for moderation |
uid |
The platform's user id, when it gives one |
handle |
X only: the viewer's @name |
test |
true for test events from the Theme Studio or the window |
type |
Fields | When |
|---|---|---|
delete |
id |
A message was removed (by a moderator, or by CrossChat on your say-so) |
purge |
p, name |
Everything a viewer wrote was removed (a timeout or ban) |
clear |
The chat was cleared | |
hide |
id, why |
Your filters now hide a message that already showed. Take it off stream |
status |
status (platform → off, waiting, on or retry), live, yt, health |
A platform's connection changed. health[p] has since, last (time of the last message) and reconnects |
viewers |
counts (platform → number or null), total |
Every 10 to 30 seconds while live |
feature |
msg (a msg event, or null) |
The featured message changed |
emotes |
emotes (name → picture URL) |
7TV, BetterTTV and FrankerFaceZ emotes loaded. Show a word as a picture when it matches a name exactly |
theme |
name, default |
A theme was saved or deleted, or the default changed |
starred |
ids |
Messages put aside to answer later |
quick |
replies |
The quick replies changed |
sent |
job_id, answer (platform → {ok, why}) |
A reply or moderation finished |
rumble_auth |
state |
Whether Rumble is connected |
executor |
present |
Whether the chat window with the extension is open (it posts to YouTube, X, TikTok, Facebook, Instagram and Rumble) |
twitch_auth, kick_auth |
state (off, pending, on, error), login, why |
Sign-in state |
tts, filters |
settings |
Text-to-speech or filter settings changed |
config |
the same fields as GET /config/editable |
Settings → Channels & options was saved. Sent to pages on this PC only |
say, say_stop |
text, voice, rate, volume |
Sent to the CrossChat window on this PC only: read this aloud, or stop |
devices, pair |
Sent to pages on this PC only: paired devices and pairing codes |
| Request | Answer |
|---|---|
GET /version |
{"version": "1.9.1"} |
GET /settings |
overlay from config.json (the chat widget uses overlay.platforms) and the default theme's name |
GET /themes |
{"default", "themes": [...]} |
GET /themes/<name> |
One theme |
GET /targets |
Where a typed reply goes: {"twitch", "youtube_video", "tiktok", "facebook", "instagram", "rumble_chat", "live", "tiktok_joins"} |
GET /logs |
Chat history: {"logs": [{"name", "started", "ended", "messages", "bytes"}]}. This PC's own pages only |
GET /logs/<name>.json |
One stream's messages, with deleted ones marked "gone": true |
GET /logs/<name>.csv |
The same as a spreadsheet (UTF-8, opens in Excel). Lines starting with = + - @ get a leading ' so they stay text |
GET /logs/<name>.html |
The same as a page to read or print |
GET /viewer?p=<platform>&name=<name> |
A viewer card. Also &uid= (the platform's user id, which wins over the name) and &q= (words to search for). This PC's pages and paired devices only. See below |
GET /config/editable |
Settings → Channels & options. This PC's own pages only. See below |
One viewer's messages, newest first: this stream's (from its chat history file, or the last 300 messages when history is off) and earlier streams' (from the chat history on this PC).
{"ok": true, "p": "twitch", "name": "nightowl_42", "handle": "", "uid": "102", "color": "#1e90ff", "badges": ["moderator"],
"count": 12, "first_seen": 1767225600000, "first_ever": false, "history": true,
"stream": [{"id": "…", "t": 1767225900000, "kind": "chat", "text": "welcome in", "mid": "…"}],
"past": [{"id": "…", "t": 1766620800000, "kind": "chat", "text": "gg", "stream": "2026-10-24_1900"}],
"past_streams": 3, "truncated": false}countandfirst_seencount chat lines this stream;first_everis the platform's own "first message in the channel" flag.- Deleted lines have
"gone": true, hidden oneshidden. - At most 200 lines each, from at most 60 earlier streams and 32 MB of history;
truncatedsays when there is more. Narrow it down withq. - A wrong platform, an empty or over-long name (100 characters), a strange
uidor a search over 100 characters answers400with{"ok": false, "why"}. - The demo (
--demo) never reads your real chat history.
The settings the CrossChat window may change, so nobody has to edit config.json by hand. Both answer only the hub's own pages on this PC: not paired devices, not your overlay pages, not other websites.
{"settings": {"twitch": "your_channel", "youtube": "@yourchannel", "kick": "", "tiktok": "", "facebook": false, "instagram": false, "broadcaster": "auto",
"x.enabled": true, "x.auto_go_live": false, "x.title": "Live now", "x.title_file": "", "x.source": "OBS",
"window": "auto", "open_window_on_stream_start": true, "close_window_seconds_after_stream": 120,
"emotes.bttv": true, "emotes.ffz": true, "emotes.7tv": true, "logs.enabled": true, "logs.keep_days": 90,
"remote.enabled": true, "remote.port": 4467},
"restart": ["twitch", "youtube", "kick", "tiktok", "facebook", "instagram", "broadcaster", "x.enabled"], "custom_window": false, "first_run": false}Tokens, client ids and secrets, the OBS password, browser and custom_overlays are never part of it.
POST /config takes {"settings": {…}} with any of those fields. Every value is checked: channels the way CrossChat reads them (a name, an @handle or a link), numbers within range (close_window_seconds_after_stream 0–3600, logs.keep_days 1–3650, remote.port 1024–65535 and not CrossChat's own port), text on one line (x.title up to 120 characters), and x.title_file must exist. One bad or unknown field and nothing is saved.
config.json is then replaced in one step (a new file moved into place), the previous one kept as config.json.bak, and every key the window doesn't edit kept as it was. A config.json that can't be read is never overwritten.
The answer says what happens next:
{"ok": true, "why": "Saved. Restart OBS to apply: Twitch channel.", "restart_needed": true, "restart": ["twitch"]}The channels, Facebook, Instagram and X on or off and the streaming app apply when OBS restarts (or, when CrossChat follows Streamlabs or nothing, when it opens again); everything else at once (emotes, chat history, the window, X's title and source, and the companion, which reopens on its new port).
Every POST answers {"ok": true} or {"ok": false, "why": "…"}.
Replies and moderation are jobs: the answer comes at once with a job_id, and the outcome follows on /events as sent.
POST /send
{"to": ["twitch", "youtube", "kick", "x"], "text": "Thanks for the raid!", "reply": {"p": "twitch", "id": "<the message's mid>", "name": "<their name>"}}textbecomes one line. Limits: Facebook 8000 characters, Instagram 2200, Twitch and Kick 500, YouTube and Rumble 200, TikTok 150, X 140.- Twitch and Kick replies go through their APIs and need Connect Twitch / Connect Kick in Settings. YouTube, X, TikTok, Facebook, Instagram and Rumble replies need the chat window with the extension open (and each platform's own live page, for those that have one).
"dry": truechecks everything and posts nothing.
POST /mod
{"p": "twitch", "action": "timeout", "message_id": "…", "user_id": "…", "name": "spammer", "seconds": 600, "reason": "spam"}| Platform | Actions |
|---|---|
| Twitch | delete, timeout, ban, unban |
| Kick | delete, timeout (rounded up to whole minutes, 1 minute to 7 days), ban, unban |
| YouTube | delete, timeout, ban |
delete |
|
| Rumble | delete, timeout (5 minutes), mute (this stream), ban (forever) |
| Request | Body |
|---|---|
POST /feature |
{"id": "<message id>"}, or {"id": ""} to clear. Also GET /feature?id=… and GET /feature?clear=1 from this PC, for hotkeys |
POST /star |
{"id": "<message id>", "on": true} |
POST /quick |
{"replies": ["…"]}: up to 30 lines of up to 100 characters |
| Request | Body |
|---|---|
POST /tts |
The settings: enabled, read (all, questions, events, command or featured), command, names, max_chars, skip_links, platforms ("all" or a list), voice, rate, volume. This PC only |
POST /tts/say |
{"id": "<message id>"}: read that chat message now. Only messages from the chat can be read |
POST /tts/skip |
Stop the current line |
The CrossChat window on this PC does the speaking, with the voices Windows and the browser have.
POST /filters, this PC only:
{"words": ["spoiler"], "users": ["@someone"], "bots": true, "hide_commands": true, "joins": false}words and users each hold up to 200 entries of up to 50 characters. Words match whole words, ignoring case. Filtered messages arrive with hidden set; nothing is deleted on the platform.
POST /test with {"kind": "chat"}, "alert", "featured" or "viewers" sends a made-up event, marked "test": true.
These answer only the hub's own pages on this PC:
/pair/start,/devices/revoke;/twitch/connect,/twitch/disconnect;/kick/connect(answers the Kick sign-inurlto open),/kick/disconnect;/themes/save,/themes/delete,/themes/default;/config(refused in the demo);/outbox/result, used by the extension.
POST /rumble/connect ({"url"}) and /rumble/disconnect set or remove the Rumble Live Stream API URL, this PC only.
Also this PC only:
POST /discord/connect({"url", "live", "featured", "chat"}) checks a Discord webhook with Discord and keeps it encrypted;/discord/options(any oflive,featured,chatas booleans) changes what is posted;/discord/testposts a test line;/discord/disconnectforgets the webhook. Thediscord_authevent saysstate(on,off,error),why, the webhook'snameand the three choices, never the URL.POST /companion/tailscale({"on": true|false}) switches the companion on the PC's Tailscale address and savesremote.tailscaleinconfig.json. Thecompanionevent (to the window on this PC) saystailscale(the switch),address(the Tailscale address found, or""),listeningandwhy.POST /updates({"check": true|false}) switches the update notice and savesupdates.check. Theupdateevent (to the window on this PC) sayscheck, and the newerversionwith its release pageurlwhen there is one (both""otherwise).
GET /tiktok/feed, GET /facebook/feed and GET /instagram/feed are how the extension passes on your TikTok LIVE chat (with its gifts, follows, shares, likes and joins), Facebook Live comments and Instagram Live comments. It accepts lines only for your own TikTok name, and only from the extension or a program on this PC.
GET /show opens the chat window. GET /x/go goes live on X (?mode=private or ?mode=dry for a test). GET /stream?go=start or ?go=end says the stream has started or ended (only with "broadcaster": "manual"). GET /leave closes CrossChat (only when it follows Streamlabs or nothing). GET /whoami says how this page is connected, including the streaming app it follows. All refuse other websites.