telegram-fragment

Fragno fragment for Telegram bots with chat tracking, command registry, and durable hooks.

Configuration

import {
  createTelegramFragment,
  createTelegram,
  defineCommand,
} from "@fragno-dev/telegram-fragment";

const telegramConfig = createTelegram({
  botToken: process.env.TELEGRAM_BOT_TOKEN!,
  webhookSecretToken: process.env.TELEGRAM_WEBHOOK_SECRET!,
  botUsername: "my_bot",
  hooks: {
    onMessageReceived: async ({ messageId, chatId }) => {
      console.log("Message", messageId, "in chat", chatId);
    },
  },
})
  .command(
    defineCommand("ping", {
      description: "Ping the bot",
      scopes: ["private", "group", "supergroup"],
      handler: async ({ api, chat }) => {
        await api.sendMessage({ chat_id: chat.id, text: "pong" });
      },
    }),
  )
  .build();

const fragment = createTelegramFragment(telegramConfig, {
  databaseAdapter: "drizzle-pglite",
});

Webhook

Incoming updates must include the header:

• X-Telegram-Bot-Api-Secret-Token: <webhookSecretToken>

Webhook route: POST /telegram/webhook

Hooks

• onMessageReceived
• onCommandMatched
• onChatMemberUpdated

Routes

• POST /telegram/webhook
• POST /commands/bind
• GET /commands
• GET /chats
• GET /chats/:chatId
• GET /chats/:chatId/messages
• POST /chats/:chatId/actions
• POST /chats/:chatId/send
• POST /chats/:chatId/messages/:messageId/edit

Data model

All Telegram IDs are stored in idColumn() fields (no separate telegram_id columns).

• user (id = telegram user id)
• chat (id = telegram chat id)
• chatMember (id = ${chatId}:${userId})
• message (id = ${chatId}:${messageId})
• chat.commandBindings (json registry of per-chat command settings)

Build

npm run types:check
npm run build

Test

npm run test