Build Telegram bots in code and Visual Flow.

import { Bot } from "@bmhien/bot";

const bot = new Bot();

bot.command("start", async (ctx) => {
  await ctx.reply("Welcome to my bot 👋");
  await ctx.telegram.sendButtons("Choose an action", [
    { text: "Continue", data: "continue" },
  ]);
});

bot.callback("continue", async (ctx) => {
  await ctx.telegram.answerCallback("Done");
});

export default bot;

{
  "framework": "@bmhien/bot",
  "version": 1,
  "compatibility_date": "2026-08-25",
  "platform": "telegram",
  "entrypoint": "main.ts",
  "visual_flow": "main.ts",
  "runtime": { "delivery": "webhook" },
  "project": {
    "include": ["**/*"],
    "exclude": ["node_modules/**", "dist/**"]
  }
}

bot.command("help", (ctx) => ctx.reply("How can I help?"));

bot.callback("confirm", async (ctx) => {
  await ctx.telegram.answerCallback("Confirmed");
  await ctx.telegram.editMessage("✅ Confirmed");
});

bot.on("chat_member", async (ctx) => {
  await ctx.reply("Membership changed");
});

const topic = await ctx.telegram.createForumTopic("Support");
await ctx.telegram.closeForumTopic(
  "{{result.topic.message_thread_id}}",
);

const lookup = await ctx.http.request("https://api.example.com/user", {
  method: "GET",
});
await ctx.reply("Status {{result.lookup.status}}: {{result.lookup.body.name}}");

const telegram = new TelegramClient(token, {
  apiRoot: "https://api.telegram.org", // optional
  fetch: globalThis.fetch,                 // optional
});

const me = await telegram.call("getMe", {}, {
  signal: abortController.signal,
});

await ctx.telegram.call("banChatMember", {
  chat_id: -1001234567890,
  user_id: 123456789,
  revoke_messages: true,
});

bot.command("confirm", (ctx) =>
  ctx.telegram.sendButtons("Continue?", [
    { text: "Yes", data: "confirm:yes" },
  ])
);

bot.callback("confirm:yes", async (ctx) => {
  await ctx.telegram.answerCallback("Saved");
  await ctx.telegram.editMessage("✅ Confirmed");
});

bot.on("message", async (ctx) => {
  await ctx.telegram.sendChatAction("typing");
  const result = await createAnswer(ctx.text ?? "");
  await ctx.reply(result);
});

bot.on("message", async (ctx) => {
  await ctx.telegram.sendMessageDraft(1, "Thinking…", {
    canStop: true,
    keepOnStop: true,
  });
  const answer = await createAnswer(ctx.text ?? "");
  await ctx.reply(answer); // persists the final output
});

bot.on("stopped_message_generation", async (ctx) => {
  await cancelGeneration(ctx.draftId);
});

bot.on("message", async (ctx) => {
  await ctx.telegram.editEphemeralMessageText("Updated");
  await ctx.telegram.editEphemeralRichMessage({ markdown: "**Ready**" });
  await ctx.telegram.editEphemeralMessageMedia({
    type: "photo",
    media: "https://example.com/result.jpg",
    caption: "Result",
  });
  await ctx.telegram.editEphemeralMessageCaption("Final caption");
  await ctx.telegram.editEphemeralMessageReplyMarkup(); // removes buttons
  await ctx.telegram.deleteEphemeralMessage();
});

bot.on("business_message", async (ctx) => {
  const checklistMessage = await ctx.telegram.sendChecklist({
    title: "Launch tasks",
    tasks: [
      { id: 1, text: "Review" },
      { id: 2, text: "Ship" },
    ],
    othersCanMarkTasksAsDone: true,
  });

  await ctx.telegram.editChecklist({
    title: "Updated tasks",
    tasks: [{ id: 1, text: "Shipped" }],
  }, { messageId: "{{result.checklistMessage.message_id}}" });
});

bot.on("business_message", async (ctx) => {
  const catalog = await ctx.telegram.getAvailableGifts();
  await ctx.telegram.sendGift(catalog.gifts[0].id);
  await ctx.telegram.giftPremiumSubscription(3);

  const balance = await ctx.telegram.getBusinessAccountStarBalance();
  const owned = await ctx.telegram.getBusinessAccountGifts({ limit: 20 });
  await ctx.telegram.upgradeGift(owned.gifts[0].owned_gift_id!, {
    keepOriginalDetails: true,
  });
});

bot.on("inline_query", async (ctx) => {
  await ctx.telegram.answerInlineQuery([
    {
      type: "article",
      id: "help",
      title: "Help",
      input_message_content: { message_text: "How can I help?" },
    },
  ], { cacheTime: 60, isPersonal: true });
});

await ctx.telegram.banMember(ctx.userId!, {
  revokeMessages: true,
});

await ctx.telegram.promoteMember(ctx.userId!, {
  can_manage_chat: true,
  can_delete_messages: true,
});

bot.command("buy", (ctx) =>
  ctx.telegram.sendInvoice({
    title: "Premium access",
    description: "Unlock premium access",
    payload: "premium-order",
    currency: "XTR",
    prices: [{ label: "Premium", amount: 100 }],
  })
);

bot.on("pre_checkout_query", (ctx) =>
  ctx.telegram.answerPreCheckoutQuery(true)
);

bot.on("successful_payment", async (ctx) => {
  await deliverPurchase(ctx.successfulPayment!.invoice_payload);
});

await ctx.telegram.createForumTopic("Support", {
  iconColor: 7322096,
});

// These default to ctx.messageThreadId.
await ctx.telegram.editForumTopic({ name: "Help desk" });
await ctx.telegram.closeForumTopic();
await ctx.telegram.reopenForumTopic();
await ctx.telegram.unpinAllForumTopicMessages();

import {
  Bot,
  TelegramClient,
  createTelegramWebhookHandler,
} from "@bmhien/bot";

const bot = new Bot();
const telegram = new TelegramClient(
  process.env.TELEGRAM_BOT_TOKEN!,
);

bot.on("message", (ctx) =>
  ctx.reply(`Received: ${ctx.text ?? ""}`)
);

export const handleTelegram = createTelegramWebhookHandler(
  bot,
  telegram,
  {
    secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,
    parseMode: "HTML",
  },
);

import { Bot, TelegramClient, runTelegramPolling } from "@bmhien/bot";

const bot = new Bot();
const telegram = new TelegramClient(process.env.TELEGRAM_BOT_TOKEN!);
const controller = new AbortController();

bot.command("start", (ctx) => ctx.reply("Running locally"));

await runTelegramPolling(bot, telegram, {
  signal: controller.signal,
  offset: 0,
  timeout: 30,
  limit: 100,
  allowedUpdates: ["message", "callback_query"],
  onError: console.error,
});

const form = new FormData();
form.set("chat_id", "123456789");
form.set("document", new Blob([bytes]), "report.pdf");

await telegram.upload("sendDocument", form);

const downloadUrl = await telegram.getFileUrl(fileId);

try {
  await telegram.call("sendMessage", {
    chat_id: 123456789,
    text: "Hello",
  });
} catch (error) {
  if (error instanceof TelegramClientError) {
    console.error(error.errorCode, error.retryAfter, error.migrateToChatId);
  }
}