LobotomyLabs/dumpsterChat
2
0
Fork 0
Code Issues Pull Requests Actions Packages Releases 10 Wiki Activity
Page: Phase 4
Pages
API Reference Architecture Frontend Design Getting Started Home Phase 3 Phase 4 Phase 5 Phase 6 Profiles Roadmap Self Hosting Troubleshooting Voice and Video
Clone
2
Phase 4
hobokenchicken edited this page 2026-07-15 15:42:38 -04:00
Table of Contents

Phase 4: Bots & Extensibility

Phase 4 brings the bot framework, slash commands, incoming webhooks, and built-in bots to Dumpster.

Features Implemented

Bot Framework

Feature Status Description
Bot CRUD ✅ Create, list, get, update, delete bots
Bot tokens ✅ 64-char hex tokens, shown once on create/regenerate
Bot server management ✅ Add/remove bots from servers
Bot WebSocket ✅ /ws/bot endpoint for real-time events
Bot message sending ✅ Bots send messages via WS with bot auth
Bot store ✅ Public listing at /bots with server counts
Bot message badges ✅ Green name + BOT tag on bot messages in chat
Built-in bot runner ✅ Server-manages bots, no SSH required
Built-in bot: steamfree ✅ Polls Steam API for free games, auto-posts

Slash Commands

Feature Status Description
Command registration ✅ Register commands per bot per server
Command management ✅ CRUD for slash commands
Command autocomplete ✅ / triggers popup with registered commands
Server commands API ✅ List all commands for a server

Incoming Webhooks

Feature Status Description
Webhook creation ✅ Create webhooks per channel
Webhook execution ✅ Public endpoint (no auth) to send messages
Username/avatar override ✅ Webhook messages can override bot name/avatar
Webhook management ✅ CRUD for webhooks

Example Bots

Bot Description
Modbot Auto-delete messages with banned words, /kick, /ban, /purge commands
Welcome bot Send welcome message when member joins server
Steam Free Games Polls Steam's featured categories for 100%-off games (built-in)

Using Built-in Bots

Built-in bots run inside the dumpsterChat server. No SSH, no separate process.

  1. Go to /bots/manage in the web UI
  2. Click [CREATE BOT]
  3. Name it, pick a type from the dropdown (e.g. "Steam Free Games")
  4. Select the server and channel to post to
  5. Click [SAVE]

The bot starts immediately. It restarts automatically when the server restarts.

Adding New Built-in Bot Types

Three touch points:

  1. internal/bot/yourbot.go — write a BotFunc that takes (ctx, config, send)
  2. cmd/server/main.go — register it: botRunner.Register("yourbot", bot.YourBot)
  3. web/src/components/BotManager.tsx — add config fields to BOT_TYPE_CONFIGS

Running External Example Bots

External bots connect via WebSocket and run as separate processes.

Modbot

cd examples/modbot
BOT_TOKEN=your_bot_token go run main.go

Welcome Bot

cd examples/welcome
BOT_TOKEN=your_bot_token DUMPSTER_HOST=dumpster.dustin.coffee go run main.go

Steam Free Games (standalone)

cd examples/steamfree
BOT_TOKEN=your_bot_token CHANNEL_ID=channel-uuid DUMPSTER_HOST=dumpster.dustin.coffee go run main.go

API Reference

Bot Management

# Create a bot (external)
POST /api/v1/bots
{ "name": "Modbot", "description": "Moderation bot" }

# Create a built-in bot
POST /api/v1/bots
{ "name": "Free Games", "description": "Posts free Steam games", "bot_type": "steamfree", "config": { "channel_id": "...", "poll_minutes": 30 } }

# List my bots
GET /api/v1/bots

# Bot store (all bots, public)
GET /api/v1/bots/store

# Available bot types
GET /api/v1/bots/types

# Add bot to server
POST /api/v1/bots/{id}/servers
{ "server_id": "..." }

# Regenerate token
POST /api/v1/bots/{id}/regenerate-token

Bot WebSocket

# Connect as bot
ws://host/ws/bot?token=abc123...

# Receive events
{ "type": "MESSAGE_CREATE", "payload": { ... } }
{ "type": "SERVER_MEMBER_ADD", "payload": { ... } }

# Send message
{ "type": "SEND_MESSAGE", "payload": { "channel_id": "...", "content": "Hello!" } }

# Delete message
{ "type": "DELETE_MESSAGE", "payload": { "channel_id": "...", "message_id": "..." } }

Slash Commands

# Register command
POST /api/v1/bots/{id}/commands
{ "server_id": "...", "name": "kick", "description": "Kick a user" }

# List server commands (for autocomplete)
GET /api/v1/bots/servers/{id}/commands
→ [{ "name": "kick", "description": "Kick a user", "bot_name": "Modbot" }]

Webhooks

# Create webhook
POST /api/v1/channels/{id}/webhooks
{ "name": "GitHub" }
→ { "id": "...", "token": "...", "url": "https://host/webhooks/{id}/{token}" }

# Execute webhook (public, no auth)
POST /webhooks/{id}/{token}
{ "content": "New commit pushed", "username": "GitHub", "avatar_url": "..." }

Navigation