668 lines
15 KiB
Markdown
668 lines
15 KiB
Markdown
# Bot Integration Guide
|
|
|
|
This guide explains how to integrate your bot with the Jackbox Game Picker API for live voting and game notifications.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Live Voting (Bot → API)](#live-voting-bot--api)
|
|
2. [Game Notifications (API → Bot)](#game-notifications-api--bot)
|
|
- [WebSocket Integration (Recommended)](#websocket-integration-recommended)
|
|
- [Webhook Integration](#webhook-integration)
|
|
3. [Webhook Management](#webhook-management)
|
|
4. [Testing](#testing)
|
|
|
|
---
|
|
|
|
## Live Voting (Bot → API)
|
|
|
|
Your bot can send real-time votes to the API when it detects "thisgame++" or "thisgame--" in Kosmi chat.
|
|
|
|
### Endpoint
|
|
|
|
```
|
|
POST /api/votes/live
|
|
```
|
|
|
|
### Authentication
|
|
|
|
Requires JWT token in Authorization header:
|
|
|
|
```
|
|
Authorization: Bearer YOUR_JWT_TOKEN
|
|
```
|
|
|
|
### Request Body
|
|
|
|
```json
|
|
{
|
|
"username": "string", // Username of the voter
|
|
"vote": "up" | "down", // "up" for thisgame++, "down" for thisgame--
|
|
"timestamp": "string" // ISO 8601 timestamp (e.g., "2025-11-01T20:30:00Z")
|
|
}
|
|
```
|
|
|
|
### Response (Success)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Vote recorded successfully",
|
|
"session": {
|
|
"id": 123,
|
|
"games_played": 5
|
|
},
|
|
"game": {
|
|
"id": 45,
|
|
"title": "Fibbage 4",
|
|
"upvotes": 46,
|
|
"downvotes": 3,
|
|
"popularity_score": 43
|
|
},
|
|
"vote": {
|
|
"username": "TestUser",
|
|
"type": "up",
|
|
"timestamp": "2025-11-01T20:30:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Error Responses
|
|
|
|
- **400 Bad Request**: Invalid payload or timestamp format
|
|
- **404 Not Found**: No active session or timestamp doesn't match any game
|
|
- **409 Conflict**: Duplicate vote (within 1 second of previous vote from same user)
|
|
- **500 Internal Server Error**: Server error
|
|
|
|
### Example Implementation (Node.js)
|
|
|
|
```javascript
|
|
// When bot detects "thisgame++" or "thisgame--" in Kosmi chat
|
|
async function handleVote(username, message) {
|
|
const isUpvote = message.includes('thisgame++');
|
|
const isDownvote = message.includes('thisgame--');
|
|
|
|
if (!isUpvote && !isDownvote) return;
|
|
|
|
try {
|
|
const response = await fetch('http://your-api-url/api/votes/live', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Authorization': `Bearer ${process.env.JWT_TOKEN}`,
|
|
'Content-Type': 'application/json'
|
|
},
|
|
body: JSON.stringify({
|
|
username: username,
|
|
vote: isUpvote ? 'up' : 'down',
|
|
timestamp: new Date().toISOString()
|
|
})
|
|
});
|
|
|
|
const data = await response.json();
|
|
|
|
if (response.ok) {
|
|
console.log(`Vote recorded for ${data.game.title}: ${data.game.upvotes}👍 ${data.game.downvotes}👎`);
|
|
} else {
|
|
console.error('Vote failed:', data.error);
|
|
}
|
|
} catch (error) {
|
|
console.error('Error sending vote:', error);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Important Notes
|
|
|
|
- **Deduplication**: Votes from the same user within 1 second are automatically rejected to prevent spam
|
|
- **Timestamp Matching**: The API matches the vote timestamp to the correct game based on when games were played
|
|
- **Active Session Required**: Votes can only be recorded when there's an active session with games played
|
|
|
|
---
|
|
|
|
## Game Notifications (API → Bot)
|
|
|
|
The API can notify your bot when games are added to a session, allowing you to announce "Coming up next: Game Title!" in Kosmi chat.
|
|
|
|
There are two integration methods available:
|
|
|
|
1. **WebSocket (Recommended)**: Real-time bidirectional communication, simpler setup, works through firewalls
|
|
2. **Webhooks**: Traditional HTTP callbacks, good for serverless/stateless integrations
|
|
|
|
### WebSocket Integration (Recommended)
|
|
|
|
WebSocket provides real-time event streaming from the API to your bot. This is the recommended approach as it:
|
|
|
|
- Works through firewalls and NAT (bot initiates connection)
|
|
- No need to expose inbound ports
|
|
- Automatic reconnection on disconnect
|
|
- Lower latency than webhooks
|
|
- Bidirectional communication
|
|
|
|
#### Connection Flow
|
|
|
|
1. Bot connects to WebSocket endpoint
|
|
2. Bot authenticates with JWT token
|
|
3. Bot subscribes to active session
|
|
4. Bot receives `game.added` events in real-time
|
|
|
|
#### WebSocket Endpoint
|
|
|
|
```
|
|
wss://your-api-url/api/sessions/live
|
|
```
|
|
|
|
#### Message Protocol
|
|
|
|
All messages are JSON-formatted.
|
|
|
|
**Client → Server Messages:**
|
|
|
|
```json
|
|
// 1. Authenticate (first message after connecting)
|
|
{
|
|
"type": "auth",
|
|
"token": "YOUR_JWT_TOKEN"
|
|
}
|
|
|
|
// 2. Subscribe to a session
|
|
{
|
|
"type": "subscribe",
|
|
"sessionId": 123
|
|
}
|
|
|
|
// 3. Unsubscribe from a session
|
|
{
|
|
"type": "unsubscribe",
|
|
"sessionId": 123
|
|
}
|
|
|
|
// 4. Heartbeat (keep connection alive)
|
|
{
|
|
"type": "ping"
|
|
}
|
|
```
|
|
|
|
**Server → Client Messages:**
|
|
|
|
```json
|
|
// Authentication success
|
|
{
|
|
"type": "auth_success",
|
|
"message": "Authenticated successfully"
|
|
}
|
|
|
|
// Authentication failure
|
|
{
|
|
"type": "auth_error",
|
|
"message": "Invalid or expired token"
|
|
}
|
|
|
|
// Subscription confirmed
|
|
{
|
|
"type": "subscribed",
|
|
"sessionId": 123,
|
|
"message": "Subscribed to session 123"
|
|
}
|
|
|
|
// Game added event
|
|
{
|
|
"type": "game.added",
|
|
"timestamp": "2025-11-01T20:30:00Z",
|
|
"data": {
|
|
"session": {
|
|
"id": 123,
|
|
"is_active": true,
|
|
"games_played": 5
|
|
},
|
|
"game": {
|
|
"id": 45,
|
|
"title": "Fibbage 4",
|
|
"pack_name": "The Jackbox Party Pack 9",
|
|
"min_players": 2,
|
|
"max_players": 8,
|
|
"manually_added": false
|
|
}
|
|
}
|
|
}
|
|
|
|
// Heartbeat response
|
|
{
|
|
"type": "pong"
|
|
}
|
|
|
|
// Error
|
|
{
|
|
"type": "error",
|
|
"message": "Error description"
|
|
}
|
|
```
|
|
|
|
#### Example Implementation (Node.js)
|
|
|
|
```javascript
|
|
const WebSocket = require('ws');
|
|
|
|
class JackboxWebSocketClient {
|
|
constructor(apiURL, jwtToken) {
|
|
this.apiURL = apiURL.replace(/^http/, 'ws') + '/api/sessions/live';
|
|
this.jwtToken = jwtToken;
|
|
this.ws = null;
|
|
this.reconnectDelay = 1000;
|
|
this.maxReconnectDelay = 30000;
|
|
}
|
|
|
|
connect() {
|
|
this.ws = new WebSocket(this.apiURL);
|
|
|
|
this.ws.on('open', () => {
|
|
console.log('WebSocket connected');
|
|
this.authenticate();
|
|
this.startHeartbeat();
|
|
});
|
|
|
|
this.ws.on('message', (data) => {
|
|
this.handleMessage(JSON.parse(data));
|
|
});
|
|
|
|
this.ws.on('close', () => {
|
|
console.log('WebSocket disconnected, reconnecting...');
|
|
this.reconnect();
|
|
});
|
|
|
|
this.ws.on('error', (err) => {
|
|
console.error('WebSocket error:', err);
|
|
});
|
|
}
|
|
|
|
authenticate() {
|
|
this.send({ type: 'auth', token: this.jwtToken });
|
|
}
|
|
|
|
subscribe(sessionId) {
|
|
this.send({ type: 'subscribe', sessionId });
|
|
}
|
|
|
|
send(message) {
|
|
if (this.ws && this.ws.readyState === WebSocket.OPEN) {
|
|
this.ws.send(JSON.stringify(message));
|
|
}
|
|
}
|
|
|
|
handleMessage(message) {
|
|
switch (message.type) {
|
|
case 'auth_success':
|
|
console.log('Authenticated successfully');
|
|
// Get active session and subscribe
|
|
this.getActiveSessionAndSubscribe();
|
|
break;
|
|
|
|
case 'auth_error':
|
|
console.error('Authentication failed:', message.message);
|
|
break;
|
|
|
|
case 'subscribed':
|
|
console.log('Subscribed to session:', message.sessionId);
|
|
break;
|
|
|
|
case 'game.added':
|
|
this.handleGameAdded(message.data);
|
|
break;
|
|
|
|
case 'pong':
|
|
// Heartbeat response
|
|
break;
|
|
|
|
case 'error':
|
|
console.error('Server error:', message.message);
|
|
break;
|
|
}
|
|
}
|
|
|
|
handleGameAdded(data) {
|
|
const { game } = data;
|
|
const announcement = `🎮 Coming up next: ${game.title}!`;
|
|
|
|
// Send to your chat platform
|
|
this.broadcastToChat(announcement);
|
|
}
|
|
|
|
startHeartbeat() {
|
|
setInterval(() => {
|
|
this.send({ type: 'ping' });
|
|
}, 30000); // Every 30 seconds
|
|
}
|
|
|
|
reconnect() {
|
|
setTimeout(() => {
|
|
this.connect();
|
|
this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxReconnectDelay);
|
|
}, this.reconnectDelay);
|
|
}
|
|
|
|
async getActiveSessionAndSubscribe() {
|
|
// Fetch active session from REST API
|
|
const response = await fetch(`${this.apiURL.replace('/api/sessions/live', '')}/api/sessions/active`, {
|
|
headers: { 'Authorization': `Bearer ${this.jwtToken}` }
|
|
});
|
|
|
|
if (response.ok) {
|
|
const session = await response.json();
|
|
if (session && session.id) {
|
|
this.subscribe(session.id);
|
|
}
|
|
}
|
|
}
|
|
|
|
broadcastToChat(message) {
|
|
// Implement your chat platform integration here
|
|
console.log('Broadcasting:', message);
|
|
}
|
|
}
|
|
|
|
// Usage
|
|
const client = new JackboxWebSocketClient('https://your-api-url', 'YOUR_JWT_TOKEN');
|
|
client.connect();
|
|
```
|
|
|
|
#### Example Implementation (Go)
|
|
|
|
See the reference implementation in `irc-kosmi-relay/bridge/jackbox/websocket_client.go`.
|
|
|
|
---
|
|
|
|
### Webhook Integration
|
|
|
|
Webhooks are HTTP callbacks sent from the API to your bot when events occur. This is an alternative to WebSocket for bots that prefer stateless integrations.
|
|
|
|
#### Webhook Event: `game.added`
|
|
|
|
Triggered whenever a game is added to an active session (either via picker or manual selection).
|
|
|
|
### Webhook Payload
|
|
|
|
```json
|
|
{
|
|
"event": "game.added",
|
|
"timestamp": "2025-11-01T20:30:00Z",
|
|
"data": {
|
|
"session": {
|
|
"id": 123,
|
|
"is_active": true,
|
|
"games_played": 5
|
|
},
|
|
"game": {
|
|
"id": 45,
|
|
"title": "Fibbage 4",
|
|
"pack_name": "The Jackbox Party Pack 9",
|
|
"min_players": 2,
|
|
"max_players": 8,
|
|
"manually_added": false
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Webhook Headers
|
|
|
|
The API sends the following headers with each webhook:
|
|
|
|
- `Content-Type: application/json`
|
|
- `X-Webhook-Signature: sha256=<hmac_signature>` - HMAC-SHA256 signature for verification
|
|
- `X-Webhook-Event: game.added` - Event type
|
|
- `User-Agent: Jackbox-Game-Picker-Webhook/1.0`
|
|
|
|
### Signature Verification
|
|
|
|
**IMPORTANT**: Always verify the webhook signature to ensure the request is authentic.
|
|
|
|
```javascript
|
|
const crypto = require('crypto');
|
|
|
|
function verifyWebhookSignature(signature, payload, secret) {
|
|
if (!signature || !signature.startsWith('sha256=')) {
|
|
return false;
|
|
}
|
|
|
|
const expectedSignature = 'sha256=' + crypto
|
|
.createHmac('sha256', secret)
|
|
.update(JSON.stringify(payload))
|
|
.digest('hex');
|
|
|
|
// Use timing-safe comparison
|
|
try {
|
|
return crypto.timingSafeEqual(
|
|
Buffer.from(signature),
|
|
Buffer.from(expectedSignature)
|
|
);
|
|
} catch (err) {
|
|
return false;
|
|
}
|
|
}
|
|
```
|
|
|
|
### Example Implementation (Express.js)
|
|
|
|
```javascript
|
|
const express = require('express');
|
|
const crypto = require('crypto');
|
|
|
|
const app = express();
|
|
|
|
// IMPORTANT: Use express.json() with verify option to get raw body
|
|
app.use(express.json({
|
|
verify: (req, res, buf) => {
|
|
req.rawBody = buf.toString('utf8');
|
|
}
|
|
}));
|
|
|
|
app.post('/webhook/jackbox', (req, res) => {
|
|
const signature = req.headers['x-webhook-signature'];
|
|
const secret = process.env.WEBHOOK_SECRET; // Your webhook secret
|
|
|
|
// Verify signature
|
|
if (!signature || !signature.startsWith('sha256=')) {
|
|
return res.status(401).send('Missing or invalid signature');
|
|
}
|
|
|
|
const expectedSignature = 'sha256=' + crypto
|
|
.createHmac('sha256', secret)
|
|
.update(req.rawBody)
|
|
.digest('hex');
|
|
|
|
// Timing-safe comparison
|
|
try {
|
|
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
|
|
return res.status(401).send('Invalid signature');
|
|
}
|
|
} catch (err) {
|
|
return res.status(401).send('Invalid signature');
|
|
}
|
|
|
|
// Handle the event
|
|
if (req.body.event === 'game.added') {
|
|
const game = req.body.data.game;
|
|
|
|
// Send message to Kosmi chat
|
|
sendKosmiMessage(`🎮 Coming up next: ${game.title}!`);
|
|
|
|
console.log(`Announced game: ${game.title} from ${game.pack_name}`);
|
|
}
|
|
|
|
// Always respond with 200 OK
|
|
res.status(200).send('OK');
|
|
});
|
|
|
|
function sendKosmiMessage(message) {
|
|
// Your Kosmi chat integration here
|
|
console.log('Sending to Kosmi:', message);
|
|
}
|
|
|
|
app.listen(3001, () => {
|
|
console.log('Webhook receiver listening on port 3001');
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Webhook Management
|
|
|
|
You can manage webhooks through the API using the following endpoints (all require JWT authentication).
|
|
|
|
### List All Webhooks
|
|
|
|
```bash
|
|
GET /api/webhooks
|
|
Authorization: Bearer YOUR_JWT_TOKEN
|
|
```
|
|
|
|
### Create Webhook
|
|
|
|
```bash
|
|
POST /api/webhooks
|
|
Authorization: Bearer YOUR_JWT_TOKEN
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"name": "Kosmi Bot",
|
|
"url": "http://your-bot-url/webhook/jackbox",
|
|
"secret": "your_shared_secret_key",
|
|
"events": ["game.added"]
|
|
}
|
|
```
|
|
|
|
### Update Webhook
|
|
|
|
```bash
|
|
PATCH /api/webhooks/:id
|
|
Authorization: Bearer YOUR_JWT_TOKEN
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"enabled": false // Disable webhook
|
|
}
|
|
```
|
|
|
|
### Delete Webhook
|
|
|
|
```bash
|
|
DELETE /api/webhooks/:id
|
|
Authorization: Bearer YOUR_JWT_TOKEN
|
|
```
|
|
|
|
### Test Webhook
|
|
|
|
```bash
|
|
POST /api/webhooks/test/:id
|
|
Authorization: Bearer YOUR_JWT_TOKEN
|
|
```
|
|
|
|
Sends a test `game.added` event to verify your webhook is working.
|
|
|
|
### View Webhook Logs
|
|
|
|
```bash
|
|
GET /api/webhooks/:id/logs?limit=50
|
|
Authorization: Bearer YOUR_JWT_TOKEN
|
|
```
|
|
|
|
Returns recent webhook delivery attempts with status codes and errors.
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
### Test Live Voting
|
|
|
|
```bash
|
|
# Get your JWT token first
|
|
curl -X POST "http://localhost:5000/api/auth/login" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"apiKey": "YOUR_API_KEY"}'
|
|
|
|
# Send a test vote
|
|
curl -X POST "http://localhost:5000/api/votes/live" \
|
|
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"username": "TestUser",
|
|
"vote": "up",
|
|
"timestamp": "2025-11-01T20:30:00Z"
|
|
}'
|
|
```
|
|
|
|
### Test Webhooks
|
|
|
|
```bash
|
|
# Create a webhook
|
|
curl -X POST "http://localhost:5000/api/webhooks" \
|
|
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name": "Test Webhook",
|
|
"url": "http://localhost:3001/webhook/jackbox",
|
|
"secret": "test_secret_123",
|
|
"events": ["game.added"]
|
|
}'
|
|
|
|
# Test the webhook
|
|
curl -X POST "http://localhost:5000/api/webhooks/test/1" \
|
|
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
|
|
|
# Check webhook logs
|
|
curl -X GET "http://localhost:5000/api/webhooks/1/logs" \
|
|
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
|
```
|
|
|
|
---
|
|
|
|
## Available Events
|
|
|
|
Currently supported webhook events:
|
|
|
|
- `game.added` - Triggered when a game is added to an active session
|
|
|
|
More events may be added in the future (e.g., `session.started`, `session.ended`, `vote.recorded`).
|
|
|
|
---
|
|
|
|
## Security Best Practices
|
|
|
|
1. **Always verify webhook signatures** - Never trust webhook payloads without verification
|
|
2. **Use HTTPS in production** - Webhook URLs should use HTTPS to prevent man-in-the-middle attacks
|
|
3. **Keep secrets secure** - Store webhook secrets in environment variables, never in code
|
|
4. **Implement rate limiting** - Protect your webhook endpoints from abuse
|
|
5. **Log webhook activity** - Keep logs of webhook deliveries for debugging
|
|
6. **Use strong secrets** - Generate cryptographically secure random strings for webhook secrets
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Votes Not Being Recorded
|
|
|
|
- Check that there's an active session with games played
|
|
- Verify the timestamp is within the timeframe of a played game
|
|
- Ensure you're not sending duplicate votes within 1 second
|
|
- Check API logs for error messages
|
|
|
|
### Webhooks Not Being Received
|
|
|
|
- Verify your webhook URL is publicly accessible
|
|
- Check webhook logs via `/api/webhooks/:id/logs`
|
|
- Test with `ngrok` or similar tool if developing locally
|
|
- Ensure your webhook endpoint responds with 200 OK
|
|
- Check that webhook is enabled in the database
|
|
|
|
### Signature Verification Failing
|
|
|
|
- Ensure you're using the raw request body for signature verification
|
|
- Check that the secret matches what's stored in the database
|
|
- Verify you're using HMAC-SHA256 algorithm
|
|
- Make sure to prefix with "sha256=" when comparing
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
For issues or questions, contact: cottongin@cottongin.xyz
|
|
|