IRC-kosmi-relay/docs/setup/BOT_features.md

Bot Features Guide

This document describes the features available in the Kosmi-IRC relay bot when the Jackbox Game Picker integration is enabled.

Feature Summary

Feature	Where	Description
Message relay	IRC + Kosmi	Bidirectional chat relay
Vote detection	IRC + Kosmi	Automatic thisgame++/-- and ticker votes
!votes command	IRC + Kosmi	Query current game vote tally
!kreconnect	IRC	Reconnect Kosmi bridge
!jreconnect	IRC	Reconnect Jackbox WebSocket
!reconnect	IRC	Reconnect all non-IRC services
Game announcements	All bridges	Jackbox game/session notifications
Room code images	All bridges	Generated room code images in chat
Mute toggle	Operator (SIGUSR1)	Suppress Jackbox announcements

Vote Detection

The bot automatically detects votes in chat messages from both IRC and Kosmi. Votes are submitted to the Jackbox Game Picker API.

Current Game Votes

• thisgame++ -- Upvote the currently playing game
• thisgame-- -- Downvote the currently playing game

Case-insensitive. Can appear anywhere in the message. The message is still relayed normally.

Ticker Symbol Votes

• SYMBOL++ -- Upvote a specific game by ticker symbol
• SYMBOL-- -- Downvote a specific game by ticker symbol

Symbols are 2-4 alphanumeric characters. See IRC.md for the complete ticker table.

Loop Prevention

Messages prefixed with [irc] or [kosmi] (relayed messages) are excluded from vote detection to prevent duplicate counting.

Deduplication

The API rejects duplicate votes from the same user within 1 second.

Game Announcements

When connected to the Jackbox API via WebSocket (default) or webhook, the bot broadcasts events to all bridges:

Event	Example Message
Session started	🎮 Game Night is starting!
Game added	🎮 Coming up next: Fibbage 4 - Room Code ABCD
Session ended	🌙 Game Night has ended! Thanks for playing!

Room Code Images

When EnableRoomCodeImage=true, game announcements include an uploaded image of the room code. The image is uploaded to the Kosmi CDN. Timing is controlled by RoomCodeImageDelay and RoomCodePlaintextDelay in config.

If image upload fails, the bot falls back to plaintext.

IRC Commands

All commands are available to any user in the channel. See IRC.md for complete details.

Command	Effect
!kreconnect	Reconnect Kosmi bridge
!jreconnect	Reconnect Jackbox WebSocket
!reconnect	Reconnect all non-IRC services
!votes	Show current game vote tally

!votes is also available from Kosmi chat.

Mute Control

Jackbox announcements can be suppressed without stopping the bot:

• Start muted: ./matterbridge -conf matterbridge.toml -muted
• Toggle at runtime: kill -SIGUSR1 <pid> or docker kill -s SIGUSR1 <container>

When muted, vote detection and normal message relay continue to work. Only Jackbox-driven announcements (session start/end, game added) are suppressed.

See MUTE_CONTROL.md for full details.

API Communication

Authentication

The bot authenticates with POST /api/auth/login using the AdminPassword from config. The JWT is cached in memory and refreshed on 401 responses.

Vote Submission

Votes are submitted via POST /api/votes/live with:

{
  "username": "voter_name",
  "vote": "up",
  "timestamp": "2025-11-01T20:30:00Z",
  "ticker": "FBG4"
}

The ticker field is omitted for thisgame++/-- votes.

Event Transport

WebSocket (default): Connects to wss://<api>/api/sessions/live, authenticates, and subscribes to the active session. Events arrive in real-time with auto-reconnect.

Webhook (fallback): Starts an HTTP server listening for POST /webhook/jackbox with HMAC-SHA256 signature verification.

Configuration

See JACKBOX_INTEGRATION.md for the full configuration reference.

Minimal setup:

[jackbox]
Enabled=true
APIURL="https://your-jackbox-api.example.com"
AdminPassword="your_password"
UseWebSocket=true

Troubleshooting

Votes not registering

• Check that Jackbox integration is enabled
• Verify an active session exists
• Look for "Detected vote from" in debug logs
• Look for "Failed to send vote" errors

Announcements not appearing

• Check that the Jackbox WebSocket is connected
• Verify the bot is not muted (check logs for MUTED)
• Use !jreconnect to force a WebSocket reconnection

!votes returns nothing

• An active session must exist
• A game must currently have "playing" status
• The Jackbox integration must be enabled and authenticated