Grambot

A declarative framework for building menu-driven Telegram bots. No boilerplate — just menus, buttons, and conversations.

Install • Quick Start • Documentation • Releases

📦 Install

npm install grambot grammy

🚀 Quick Start

import { Grambot } from "grambot";

const greetAction = Grambot.action(async ({ conversation }) => {
  const name = await conversation.ask("What is your name?");
  await conversation.say(`Hello, ${name}!`);
});

const mainMenu = Grambot.menu((layout) => {
  layout.text("Welcome! Choose an option:");
  layout.button("👋 Say Hello").primary().action(greetAction);
  layout.button("🌐 Website").url("https://github.com/dortanes/grambot");
});

const bot = Grambot.create({
  token: process.env.BOT_TOKEN!,
  menu: mainMenu,
});

bot.start();

✨ Features

| | Feature | Description | | --- | ----------------------- | -------------------------------------------------------- | | 🏗️ | Declarative Menus | Define layouts with a fluent builder API | | 🔄 | Auto Navigation | Nested menus with built-in "Back" buttons | | 💬 | Conversations | Collect input with ask() and form() | | 📝 | Single-Message Flow | Edits one message for a clean chat history | | 🎨 | Button Styling | Colors (danger, success, primary) and custom emoji icons | | 🛡️ | Error Handling | Built-in error boundary — no crashes | | 🌐 | i18n Support | Localization hooks for all internal strings | | 🔡 | Type-Safe | Full TypeScript with JSDoc |

🎨 Button Styling

Color your buttons and add custom emoji icons (Bot API 9.4+):

layout.button("Delete").danger(); // 🔴 Red
layout.button("Confirm").success(); // 🟢 Green
layout.button("Highlight").primary(); // 🔵 Blue

layout.button("VIP").icon("custom_emoji_id");

⚙️ Configuration

const bot = Grambot.create({
  token: "BOT_TOKEN",
  menu: mainMenu,

  // Resolve user data from DB on every update
  resolveUser: async (ctx) => {
    return await db.users.find(ctx.from.id);
  },

  // Localize internal strings
  translator: (key, ctx) => i18n.t(ctx.from.language_code, key),

  // Custom error handler (default: console.error)
  onError: (error, ctx) => {
    logger.error("Bot error", { error, chatId: ctx.chat?.id });
  },
});

📖 Documentation

| Guide | Description | | ------------------------------------------------ | ------------------------------------------- | | Menus and Navigation | Layouts, rows, buttons, styling, pagination | | Conversations and Forms | User input, validation, multi-step forms | | Actions and Triggers | Commands, regex, inline handlers | | State Management | Sessions, storage adapters, user resolution | | Advanced Patterns | i18n, webhooks, manual rendering |

Development

git clone https://github.com/dortanes/grambot.git
cd grambot

npm install

npm run build

BOT_TOKEN=your_token npm run start:example

License

MIT