Skip to content

Discord Bot

Jump to bottom
Chris Nighswonger edited this page Mar 27, 2026 · 2 revisions

Discord Bot

Kanfei includes a Discord bot integration that lets you query station data and receive weather notifications in your Discord server. The bot runs as a background service inside Kanfei using Discord's gateway WebSocket — no external server, webhook, or inbound ports needed.

See also: Telegram Bot for the Telegram integration, and #64 for the broader messaging roadmap.

What It Does

Slash commands

The bot registers native Discord slash commands:

Command Response
/current Current conditions — temperature, feels-like, humidity, dew point, wind, pressure with trend, rain, UV index
/status Station connection status and data age
/help List of available commands

Outbound notifications

The bot pushes messages to configured channel(s) when events occur:

Notification type Trigger Example
Nowcast Nowcast cycle produces a new summary Forecast text, threat level, model used
Alerts A configured alert threshold is triggered or cleared "Alert: High Temperature — outside_temp is 95.5 (>= 90.0)"

Alert notifications are deduplicated — you get one message when the threshold is first exceeded and one when it clears, not on every polling cycle.

Prerequisites

  • A working Kanfei installation
  • A Discord account with "Manage Server" permission on the target server
  • Internet access from the Kanfei host (outbound only — no inbound ports needed)

The bot connects via Discord's gateway WebSocket (outbound), so it works behind NAT/CGNAT without any port forwarding.

Setup

1. Create a bot in the Discord Developer Portal

  1. Go to discord.com/developers/applications and click New Application.
  2. Give it a name (e.g. "Kanfei Weather") and click Create.
  3. Go to the Bot tab and click Reset Token to generate a bot token. Copy it — treat it like a password.
  4. Under Privileged Gateway Intents, no privileged intents are required (default intents are sufficient).

2. Invite the bot to your server

  1. Go to the OAuth2 tab in the Developer Portal.
  2. Under OAuth2 URL Generator, select the bot and applications.commands scopes.
  3. Under Bot Permissions, select:
    • Send Messages
    • Use Slash Commands
  4. Copy the generated URL and open it in a browser to invite the bot to your server.

3. Get your Guild ID and Channel ID

Guild (server) ID:

  1. In Discord, enable Developer Mode (Settings > Advanced > Developer Mode).
  2. Right-click your server name and select Copy Server ID.

Channel ID:

  1. Right-click the channel where you want notifications and select Copy Channel ID.

You can configure multiple channel IDs (comma-separated) for notifications.

4. Configure in Kanfei

  1. Open Kanfei in your browser.
  2. Go to Settings > Bots.
  3. Find the Discord Bot card.
  4. Enter your Bot Token, Guild ID, and Channel ID(s).
  5. Enable the bot toggle.
  6. Select which commands and notification types to enable.
  7. Save settings.

5. Verify

Click Send Test Message in the Settings card. You should see a message in your Discord channel. If it fails, the error is shown in the UI (with the token redacted).

Then type /current in your Discord server to confirm slash commands are working. Slash commands may take a few seconds to appear after the bot first starts — Discord caches the command list.

Configuration Keys

All bot configuration is stored in station_config and managed through the Settings UI:

Key Default Description
bot_discord_enabled false Master enable/disable
bot_discord_token "" Bot token from Discord Developer Portal
bot_discord_guild_id "" Target server ID for slash command registration
bot_discord_channel_id "" Comma-separated channel IDs for notifications
bot_discord_commands "current,status,help" Comma-separated enabled commands
bot_discord_notifications "nowcast,alerts" Comma-separated notification types
bot_discord_last_error "" Last error message (auto-populated, read-only)

Security

  • Channel whitelist — the bot only responds to slash commands in configured channels. If the channel ID list is empty, the bot responds in all channels it can see.
  • Rate limiting — 5-second cooldown per command per channel, plus 1-second debounce between different commands. Prevents spam.
  • Token protection — the bot token is never exposed in API responses, logs, or error messages shown in the UI.
  • Outbound only — the bot connects outbound to Discord's gateway. No inbound ports, no webhook URLs.
  • Minimal permissions — only Send Messages and Use Slash Commands are required.

Architecture

The bot runs as a supervisor background task within the Kanfei web app process, following the same pattern as the Telegram Bot. The supervisor:

  • Polls the database config every 30 seconds for enable/disable changes
  • Starts/stops the bot automatically when settings change
  • Restarts the bot if it crashes (with the error captured in bot_discord_last_error)
  • Updates channel IDs, commands, and notification settings in-place without restarting the bot
  • Token or guild ID changes trigger a full restart

Slash commands are synced to Discord on bot startup (on_ready). If a guild ID is configured, commands are scoped to that server; otherwise they register globally.

Event sources:

  • Alert notifications arrive via IPC subscription to the logger daemon (same path as the dashboard UI)
  • Nowcast notifications arrive via the KanfeiEventEmitter listener system

Shared infrastructure

The Discord and Telegram bots share common infrastructure extracted into bot_manager.py, bot_formatting.py, and bot_ratelimit.py. Both adapters implement the same BotAdapter protocol, so formatting and rate limiting behavior is consistent across platforms.

Troubleshooting

Slash commands don't appear

  • Slash commands sync on bot startup — give it a few seconds after enabling.
  • If the guild ID is wrong, commands may register globally (can take up to an hour to propagate).
  • Verify the bot was invited with the applications.commands scope.

Bot doesn't respond to commands

  • Verify the bot is enabled in Settings > Bots
  • Check that the bot has Send Messages and Use Slash Commands permissions in the channel
  • Confirm the Kanfei host has internet access
  • Check bot_discord_last_error in the Settings card for errors
  • If the token was reset in the Developer Portal, update it in Kanfei Settings

Notifications aren't arriving

  • Check that the channel ID is correct
  • Check that the relevant notification type is enabled (nowcast, alerts)
  • For alert notifications: verify alert thresholds are configured in Settings > Alerts
  • For nowcast notifications: verify nowcast is enabled and generating

"Send Test Message" fails

  • Double-check the token (reset in Developer Portal if unsure)
  • Verify the channel ID is correct and the bot has permission to post in that channel
  • Ensure the bot has been invited to the server

API

  • POST /api/discord/test — sends a test message to the specified channel. Accepts token and channel_id in the request body. Returns success/error status. Token is sanitized from error messages.

Related Pages

Clone this wiki locally