Telegram Mod

Telegram notification Capability. Provides:

• cap.notify.send — sendMessage against a Telegram bot token. Write-only.

The capability id is provider-agnostic (per architecture spec §6) — Mods that declare requires: ["cap.notify.send"] work transparently against any installed cap.notify.send provider (telegram-mod here; future console-mod, email-mod, discord-mod; community providers). Users pin the backend they want with moltbank mod prefer cap.notify.send=telegram.

Per architecture spec §4 (write-only integration tier), this mod does not provide scan / history capabilities. Agent-readable team signal lives in canonical .md files (read via cap.kb.search) — not pulled from chat history.

Install

moltbank mod install telegram
moltbank mod prefer cap.notify.send=telegram

Lifecycle

moltbank mod setup telegram          # interactive: optional defaultChatId, draftChatId, defaultParseMode
moltbank mod doctor telegram --json  # token + getMe + default chat sanity
moltbank mod estimate telegram --json
moltbank mod status telegram --json

Used as a capability provider

import { useNotify } from '@moltbankhq/mod-sdk';

const notify = useNotify();
await notify.send({
  text: 'Hello world',                 // primary content
  title: 'Daily Brief 2026-04-28',     // optional bold header (HTML/MarkdownV2)
  format: 'html',                      // 'plain' | 'markdown' | 'html' | 'auto'
  metadata: {
    chatId: '@moltbank-ops',           // telegram-specific: numeric -100... or @channelusername
    disableWebPagePreview: true,       // optional Bot-API knob
    replyToMessageId: 12345            // optional Bot-API knob
  }
});

For Mods that don't know which backend resolves cap.notify.send, simply omit telegram-specific metadata — telegram-mod falls back to config.defaultChatId. A future console-mod / email-mod ignores Telegram-specific metadata keys entirely.

Format mapping

The provider-agnostic format field in NotifySendRequest maps to the Telegram Bot API's parse_mode as follows:

| format | Telegram parse_mode | Notes | |---|---|---| | 'auto' (default) | config.defaultParseMode → HTML | LLM-generated text default | | 'plain' | (omitted) | renders as plain text, no formatting | | 'markdown' | MarkdownV2 | requires backslash-escape of _*[](){}~>#+-=|.!` | | 'html' | HTML | requires escape of <, >, & only |

HTML is the default because LLM-generated text routinely contains characters MarkdownV2 requires escaping (especially - at line starts in bullet lists, which MarkdownV2 mangles to \-).

Title handling

When title is provided, telegram-mod prepends it as a bold header in the chosen format:

• format: 'html' → <b>{title}</b>\n\n{text}
• format: 'markdown' → *{title}*\n\n{text} (callers should pre-escape MarkdownV2 special chars in the title themselves)
• format: 'plain' / 'auto' → {title}\n\n{text}

Telegram has no native "subject" field, so this is a sensible best-effort. Future providers (email-mod) will use title for the email subject line directly.

Caveats

• Bot API rate limits: ~30 msgs/sec across all chats, ~1 msg/sec to one chat, ~20 msgs/min to a group. Mods publishing high volume should pace their calls.
• The token (TELEGRAM_BOT_TOKEN) is forwarded via permissions.envPassthrough. Keep it out of source control.
• Bot must be added to the destination chat (and made admin in groups, for write access). The mod cannot self-bootstrap chat membership — that is a one-time human step via @BotFather + the chat settings.