c88b75f30d
Rewrite README.md and all setup guides to reflect the current native GraphQL WebSocket architecture (replacing stale headless Chrome/WebSocket interception descriptions). Add new docs/IRC.md with complete IRC command reference, vote syntax, and ticker symbol table. Archive pre-edit docs to docs/archive/setup-backup-2026-05-10/ and move historical development notes from docs/ root into docs/archive/. Co-authored-by: Cursor <cursoragent@cursor.com>
146 lines
4.7 KiB
Markdown
146 lines
4.7 KiB
Markdown
# 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
|