Skip to content

Telegram Bot

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

Telegram Bot

Kanfei includes a Telegram bot integration that lets you query station data and receive weather notifications directly in Telegram. The bot runs as a background service inside Kanfei — no external server or webhook infrastructure required.

This is the first messaging platform in a planned series (see #64 for Discord and Slack roadmap).

What It Does

Inbound commands

Users send commands in the Telegram chat and the bot replies:

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
/start Same as /help (Telegram convention for first interaction)

Outbound notifications

The bot pushes messages to your chat 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 Telegram account
  • Internet access from the Kanfei host (outbound only — no inbound ports needed)

The bot uses long polling (getUpdates), so it works behind NAT/CGNAT without any port forwarding or webhook setup.

Setup

1. Create a bot with BotFather

  1. Open Telegram and search for @BotFather.
  2. Send /newbot.
  3. Follow the prompts to choose a name and username for your bot.
  4. BotFather will give you an API token — copy it. Treat it like a password.

2. Get your chat ID

You need the numeric chat ID for the chat (or group) where the bot should respond and send notifications.

For a private chat:

  1. Send any message to your new bot in Telegram.
  2. Open https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in a browser.
  3. Look for "chat":{"id": 123456789} in the JSON response — that number is your chat ID.

For a group:

  1. Add the bot to the group.
  2. Send a message in the group.
  3. Check getUpdates as above — group chat IDs are typically negative numbers.

You can configure multiple chat IDs (comma-separated) to have the bot respond in several chats.

3. Configure in Kanfei

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

4. Verify

Click Send Test Message in the Settings card. You should receive a test message in your Telegram chat. If it fails, the error is shown in the UI (with the token redacted).

Then send /current to your bot in Telegram to confirm command handling works.

Configuration Keys

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

Key Default Description
bot_telegram_enabled false Master enable/disable
bot_telegram_token "" Bot API token from @BotFather
bot_telegram_chat_id "" Comma-separated chat IDs to respond to
bot_telegram_commands "current,status,help" Comma-separated enabled commands
bot_telegram_notifications "nowcast,alerts" Comma-separated notification types
bot_telegram_last_error "" Last error message (auto-populated, read-only)

Security

  • Chat ID whitelist — the bot only responds to commands from configured chat IDs. Messages from other chats are silently ignored.
  • Rate limiting — 5-second cooldown per command per chat, plus 1-second debounce between different commands. Prevents abuse in group chats.
  • Token protection — the bot token is never exposed in API responses, logs, or error messages shown in the UI.
  • Outbound only — all connections are initiated by Kanfei (long polling to Telegram servers). No inbound ports required.

Architecture

The bot runs as a supervisor background task within the Kanfei web app process. 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_telegram_last_error)
  • Updates chat IDs, commands, and notification settings in-place without restarting the bot
  • Token changes trigger a full restart

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

Troubleshooting

Bot doesn't respond to commands

  • Verify the bot is enabled in Settings > Services
  • Check that your chat ID is correct and listed in the config
  • Confirm the Kanfei host has internet access
  • Check bot_telegram_last_error in the Settings card for errors
  • If the token was regenerated in BotFather, update it in Kanfei Settings

Notifications aren't arriving

  • 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 (regenerate in BotFather if unsure)
  • Verify the chat ID is correct
  • Ensure the bot has been started in the chat (send /start to it first)
  • For groups: make sure the bot has been added to the group

API

  • POST /api/telegram/test — sends a test message using the currently saved token and chat ID. Returns success/error status. Token is sanitized from error messages.

Related Pages

Clone this wiki locally