Chat Overlay for OBS - Documentation

Display live chat messages as a transparent overlay in OBS, Streamlabs, or any broadcast software.

Quick Start

Enable Guest Access

In your Dashboard, make sure "Guest" is enabled in Allowed Providers. The overlay connects as a read-only guest viewer.

Get Your Overlay URL

Use the URL builder below or manually construct:

https://ninjachatter.com/overlay.html?room=YOUR_ROOM_ID

Add Browser Source in OBS

In OBS: Sources → Add → Browser. Paste your overlay URL. Set width/height as needed (e.g., 400x600).

Tip: The overlay has a transparent background by default. In OBS, the chat will appear floating over your stream content.

URL Builder

Room ID: Show avatars Fade older messages at top Show connection status Compact mode (smaller text) Fully transparent bubbles (text only) Max messages: Auto-hide (sec):

https://ninjachatter.com/overlay.html?room=

Live Preview

Transparent background simulated

Query Parameters

Parameter	Default	Description
`room`	—	Required. Your room ID
`max`	50	Maximum messages to display
`avatars`	1	Show user avatars (0 to hide)
`fade`	1	Fade older messages at top (0 to disable)
`status`	1	Show connection status indicator (0 to hide)
`compact`	0	Compact mode with smaller text (1 to enable)
`transparent`	0	Fully transparent bubbles, text only (1 to enable)
`hide`	0	Auto-hide messages after N seconds (0 = never)
`ws`	wss://api...	WebSocket base URL (advanced)
`api`	https://api...	API base URL (advanced)

OBS Setup Tips

Recommended Browser Source Settings

Width: 350-500px (adjust to taste)
Height: 400-800px (taller = more messages visible)
FPS: 30 is fine for chat
Custom CSS: Leave empty (styling is built-in)

Positioning

Common placements:

Bottom-left corner: Classic chat position
Right side: Good for vertical chat layouts
Full sidebar: Set height to match canvas, position on edge

Important: The overlay requires "Guest" to be enabled in your room's Allowed Providers. If guests are disabled, the overlay cannot connect.

Custom Styling

Want to customize colors, fonts, or layout? You have options:

Option 1: OBS Custom CSS

In your Browser Source settings, add Custom CSS to override styles:

/* Example: Change text color and font */
.name { color: #ff6b6b; }
.body { font-family: 'Comic Sans MS', cursive; }

/* Example: Larger text */
.body { font-size: 18px; }

/* Example: Different bubble style */
.bubble {
  background: rgba(100, 50, 150, 0.7);
  border-radius: 20px;
}

Option 2: Self-Host

Download overlay.html and embed.js, modify as needed, and host on your own server or use a local file.

Option 3: Build Your Own

Use our embed.js SDK to build a completely custom overlay. The SDK handles WebSocket connections, reconnection, and message handling.

// Minimal custom overlay
const client = ChatEmbed.createChatClient({
  room: 'your-room-id',
  token: await ChatEmbed.mintGuestToken({
    apiBase: 'https://api.ninjachatter.com',
    room: 'your-room-id',
    username: 'Overlay'
  }),
  wsBase: 'wss://api.ninjachatter.com/ws',
  onMessage: (msg) => {
    // Render msg.payload.text however you want
    console.log(msg.user.name + ': ' + msg.payload.text);
  }
});
client.connect();

Troubleshooting

"Room requires login" error

Enable "Guest" in your room's Allowed Providers in the Dashboard.

Messages not appearing

Check that chat messages are being sent to the room
Verify the room ID is correct
Check browser console for errors (right-click → Inspect in OBS preview)

Overlay shows in preview but not on stream

In OBS, make sure the Browser Source is visible (eye icon) and not covered by other sources.