IRC-kosmi-relay/JACKBOX_INTEGRATION.md

Jackbox Game Picker API Integration

This document describes how the Kosmi/IRC relay integrates with the Jackbox Game Picker API for live voting and game notifications.

Features

1. Vote Detection

The relay automatically detects when users vote on games using the thisgame++ or thisgame-- syntax in either Kosmi or IRC chat.

How it works:

• Users type thisgame++ to upvote the current game
• Users type thisgame-- to downvote the current game
• Votes are case-insensitive
• The relay filters out relayed messages (messages with [irc] or [kosmi] prefix) to prevent duplicate votes
• Only votes from actual users in each chat are sent to the API

2. Game Notifications

When a new game is added to the Jackbox session via the API, the relay receives a webhook notification and broadcasts it to both Kosmi and IRC chats.

Example notification:

🎮 Coming up next: Fibbage 4!

Configuration

Add the following section to your matterbridge.toml:

[jackbox]
# Enable Jackbox integration for vote detection and game notifications
Enabled=true

# Jackbox API URL
APIURL="http://localhost:5000"

# Admin password for API authentication
AdminPassword="your_admin_password_here"

# Webhook server port (for receiving game notifications)
WebhookPort=3001

# Webhook secret for signature verification
WebhookSecret="your_webhook_secret_here"

Configuration Options

• Enabled: Set to true to enable the integration, false to disable
• APIURL: The URL of your Jackbox Game Picker API (e.g., http://localhost:5000)
• AdminPassword: Your API admin password (used to authenticate and get a JWT token)
• WebhookPort: Port for the webhook server to listen on (default: 3001)
• WebhookSecret: Shared secret for webhook signature verification (must match the secret configured in the API)

Setup Steps

1. Configure the Relay

Edit matterbridge.toml and add the Jackbox configuration section with your API URL, admin password, and webhook secret.

2. Register the Webhook

After starting the relay, register the webhook with the Jackbox API:

# Get JWT token
curl -X POST "http://localhost:5000/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "your_admin_password"}'

# Register webhook (use the JWT token from above)
curl -X POST "http://localhost:5000/api/webhooks" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kosmi/IRC Relay",
    "url": "http://your-relay-host:3001/webhook/jackbox",
    "secret": "your_webhook_secret_here",
    "events": ["game.added"]
  }'

Important: Replace your-relay-host with the actual hostname or IP address where your relay is running. If the API and relay are on the same machine, you can use localhost.

3. Test the Integration

Test Vote Detection

1. Start an active session in the Jackbox API with some games played
2. Send a message in Kosmi or IRC: thisgame++
3. Check the relay logs for: Detected vote from <username>: up
4. Verify the vote was recorded in the API

Test Game Notifications

1. Add a game to the active session via the Jackbox API
2. Both Kosmi and IRC chats should receive a notification: 🎮 Coming up next: <game title>!

How It Works

Vote Flow

1. User sends a message containing thisgame++ or thisgame-- in Kosmi or IRC
2. The bridge detects the vote pattern (case-insensitive)
3. The bridge checks if the message is relayed (has [irc] or [kosmi] prefix)
4. If not relayed, the bridge extracts the username and vote type
5. The bridge sends the vote to the Jackbox API via HTTP POST to /api/votes/live
6. The API records the vote and associates it with the current game based on timestamp

Notification Flow

1. A game is added to an active session in the Jackbox API
2. The API sends a webhook POST request to http://your-relay-host:3001/webhook/jackbox
3. The webhook includes an HMAC-SHA256 signature in the X-Webhook-Signature header
4. The relay verifies the signature using the configured webhook secret
5. If valid, the relay parses the game.added event
6. The relay broadcasts the game announcement to all connected bridges (Kosmi and IRC)

Security

Webhook Signature Verification

All incoming webhooks are verified using HMAC-SHA256 signatures to ensure they come from the legitimate Jackbox API.

How it works:

1. The API computes HMAC-SHA256(webhook_secret, request_body)
2. The signature is sent in the X-Webhook-Signature header as sha256=<hex_signature>
3. The relay computes the expected signature using the same method
4. The relay uses timing-safe comparison to verify the signatures match
5. If verification fails, the webhook is rejected with a 401 Unauthorized response

JWT Authentication

The relay authenticates with the Jackbox API using the admin password to obtain a JWT token. This token is:

• Cached to avoid re-authentication on every vote
• Automatically refreshed if it expires (detected via 401 response)
• Valid for 24 hours (configurable in the API)

Troubleshooting

Votes Not Being Recorded

Possible causes:

• No active session in the Jackbox API
• Vote timestamp doesn't match any played game
• Duplicate vote within 1 second
• Authentication failure

Check:

1. Relay logs for vote detection: grep "Detected vote" logs/matterbridge.log
2. Relay logs for API errors: grep "Failed to send vote" logs/matterbridge.log
3. API logs for incoming vote requests

Webhooks Not Being Received

Possible causes:

• Webhook URL is not accessible from the API server
• Webhook not registered in the API
• Signature verification failing
• Firewall blocking the webhook port

Check:

1. Verify webhook is registered: GET /api/webhooks (with JWT token)
2. Test webhook manually: POST /api/webhooks/test/:id (with JWT token)
3. Check webhook logs in API: GET /api/webhooks/:id/logs (with JWT token)
4. Verify webhook server is listening: curl http://localhost:3001/health
5. Check relay logs for signature verification errors

Authentication Failures

Possible causes:

• Incorrect admin password in configuration
• API is not running or not accessible

Check:

1. Verify API URL is correct and accessible
2. Test authentication manually:

   curl -X POST "http://localhost:5000/api/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"apiKey": "your_admin_password"}'
   

3. Check relay logs for authentication errors

Logs

The relay logs all Jackbox-related activity with the jackbox prefix:

[jackbox] Initializing Jackbox integration...
[jackbox] Successfully authenticated with Jackbox API
[jackbox] Starting Jackbox webhook server on port 3001
[kosmi] Detected vote from Anonymous Llama: up
[jackbox] Vote recorded for Fibbage 4: Anonymous Llama - 5👍 2👎
[jackbox] Broadcasting Jackbox message: 🎮 Coming up next: Quiplash 3!

Disabling the Integration

To disable the Jackbox integration, set Enabled=false in the [jackbox] section of matterbridge.toml and restart the relay.

The relay will continue to function normally for Kosmi ↔ IRC message relay without any Jackbox features.