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](../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](../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](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:

```json
{
  "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](JACKBOX_INTEGRATION.md) for the full configuration reference.

Minimal setup:

```toml
[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