Skip to content

Custom Overlays and API

Randy Northrup edited this page Nov 9, 2026 · 2 revisions

Custom Overlays and API

Your own overlay pages can read CrossChat's live chat.

Add your own overlay

Since OBS 33, a page added as a local file can't reach 127.0.0.1, so let CrossChat serve it.

  1. Set "custom_overlays": "C:\\path\\to\\your\\overlays" in config.json.
  2. Use http://localhost:4466/custom/your-page.html as 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.

A small example

<!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>

Who can use what

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.

Control CrossChat from a program

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

Clone this wiki locally