Repository navigation
Custom Overlays and API
Randy Northrup edited this page Nov 9, 2026
·
2 revisions
Your own overlay pages can read CrossChat's live chat.
Since OBS 33, a page added as a local file can't reach 127.0.0.1, so let CrossChat serve it.
- Set
"custom_overlays": "C:\\path\\to\\your\\overlays"in config.json. - Use
http://localhost:4466/custom/your-page.htmlas the Browser Source URL.
Subfolders, images, fonts, video and audio work. Nothing outside that folder is served.
These pages get their own address, which the browser keeps apart from the CrossChat window. An overlay you downloaded can show chat, but can't reply, moderate or change anything as you.
<!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>| Caller | Can |
|---|---|
| The CrossChat window, the Theme Studio and the widgets | Everything |
| Your own overlay pages | Their own files, and the public chat: /events, /settings, /version, /themes, /themes/<name>, and the page files under /web/ and /overlay/
|
| A program on this PC | Every GET. POST needs Content-Type: application/json
|
| A paired companion device | The chat, replies, moderation and featuring |
| A page from any other website, or a local file | Nothing |
The full reference, with every event and field, is in docs/API.md.
A Stream Deck or script can run control.py in CrossChat's hub folder:
| Command | Does |
|---|---|
show |
Bring up the chat window, starting CrossChat if needed |
studio |
Open the Theme Studio |
x-live |
Go live on X now |
x-private |
Test: a livestream on X only you can see |
x-dry |
Test: fill X's form, never press Go Live |
unfeature |
Take the featured message off the stream |
demo |
Try CrossChat with made-up chat |
stream-start, stream-end
|
Say the stream has started or ended, with Another app |
leave |
Close CrossChat, when it follows Streamlabs or nothing |
Get started
Use it
Reference
Help
Developers