Telegram Fragment

Bots that stay in sync with your product

Durable webhooks, typed command handlers, and a full chat data model. Drop Telegram into your stack without hand-building the glue.

Telegram Docs Quickstart

Install

npm install @fragno-dev/telegram-fragment @fragno-dev/db

npm install @fragno-dev/telegram-fragment @fragno-dev/db

Command console

Chat events to command registry to typed response

/ping

Should we ship the release?

bot reply

pong. Deployment green across all regions.

Hooks fired

onMessageReceived + onCommandMatched

Durable webhook intake

Process updates once, write durable hooks, and retry safely.

Command registry

Declare commands, scopes, and handlers in one typed place.

Chat + member sync

Persist chats, members, and messages in your database.

Typed client hooks

Query chats and send messages with generated hooks.

Setup blueprint

A focused path from webhook to bot responses.

1. Install

Install the Telegram fragment and Fragno DB.

npm install @fragno-dev/telegram-fragment @fragno-dev/db

npm install @fragno-dev/telegram-fragment @fragno-dev/db

2. Configure the fragment

Declare commands, hooks, and credentials.

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("New message", messageId, "in", 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();

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

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("New message", messageId, "in", 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();export const telegramFragment = createTelegramFragment(telegramConfig, {  databaseAdapter: "drizzle-pglite",});

3. Mount routes

Expose the webhook + command endpoints in your app.

import { telegramFragment } from "@/lib/telegram";

export const handlers = telegramFragment.handlersFor("react-router");
export const action = handlers.action;
export const loader = handlers.loader;

import { telegramFragment } from "@/lib/telegram";export const handlers = telegramFragment.handlersFor("react-router");export const action = handlers.action;export const loader = handlers.loader;

4. Create a client

Generate typed hooks for chats and messages.

import { createTelegramFragmentClient } from "@fragno-dev/telegram-fragment/react";

export const telegramClient = createTelegramFragmentClient();

import { createTelegramFragmentClient } from "@fragno-dev/telegram-fragment/react";export const telegramClient = createTelegramFragmentClient();

Command bindings

Enable or scope commands per chat.

const { data: commands } = telegramClient.useCommands();
const { mutate: bindCommand } = telegramClient.useBindCommand();

await bindCommand({
  body: { chatId: "123", commandName: "ping", enabled: true },
});

const { data: commands } = telegramClient.useCommands();const { mutate: bindCommand } = telegramClient.useBindCommand();await bindCommand({  body: { chatId: "123", commandName: "ping", enabled: true },});

Send a message

Use typed client hooks to respond instantly.

const { mutate: sendMessage, loading } = telegramClient.useSendMessage();

await sendMessage({
  path: { chatId: "123" },
  body: { text: "Hello from Fragno" },
});

const { mutate: sendMessage, loading } = telegramClient.useSendMessage();await sendMessage({  path: { chatId: "123" },  body: { text: "Hello from Fragno" },});

Routes at a glance

Everything needed to ingest updates and interact with chats.

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

Built for product ops

Use Telegram as an operations surface, not just a bot.

Incident response

Pipe alerts to Telegram and let on-call respond with commands.

Customer updates

Broadcast releases and route questions to support workflows.

Workflow approvals

Collect approvals in Telegram while persisting every decision.