Imported from terminalskills/skills (skills/telegram-bot-builder/SKILL.md). Install upstream with npx skills add terminalskills/skills --skill telegram-bot-builder. Copyright stays with the author (Apache-2.0).

Telegram Bot Builder

Overview

Builds production-ready Telegram bots covering the full Bot API surface: commands, inline keyboards, callback queries, conversations with state machines, media handling, group management, payments, and Mini Apps. Supports both long polling (development) and webhooks (production).

Instructions

1. Bot Creation

1. Message @BotFather on Telegram
2. Send /newbot, choose name and username
3. Save the bot token (format: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
4. Configure with /setcommands, /setdescription, /setabouttext

2. Project Scaffolding

Recommended frameworks by language:

Node.js — grammY (recommended):

npm init -y && npm install grammy dotenv

Node.js — Telegraf:

npm install telegraf dotenv

Python — python-telegram-bot:

pip install python-telegram-bot python-dotenv

Standard project structure:

telegram-bot/
├── bot.js                # Entry point, bot initialization
├── handlers/
│   ├── commands.js       # /start, /help, custom commands
│   ├── callbacks.js      # Inline keyboard callback handlers
│   ├── conversations.js  # Multi-step conversation flows
│   └── middleware.js      # Auth, logging, rate limiting
├── keyboards/            # Inline and reply keyboard builders
├── services/             # Business logic
├── .env                  # BOT_TOKEN, WEBHOOK_URL, ADMIN_ID
└── package.json

3. Core Patterns (grammY)

Basic command handler:

bot.command('start', async (ctx) => {
  await ctx.reply('Welcome!', {
    reply_markup: {
      inline_keyboard: [[
        { text: '📊 Dashboard', callback_data: 'dashboard' },
        { text: '⚙️ Settings', callback_data: 'settings' }
      ]]
    }
  });
});

Callback query handler:

bot.callbackQuery('dashboard', async (ctx) => {
  await ctx.answerCallbackQuery();
  await ctx.editMessageText('Here is your dashboard...', {
    reply_markup: backButton
  });
});

Conversation with sessions:

bot.use(session({ initial: () => ({ step: 'idle' }) }));
bot.use(conversations());
bot.use(createConversation('onboarding', onboardingFlow));

async function onboardingFlow(conversation, ctx) {
  await ctx.reply('What is your name?');
  const name = await conversation.wait();
  await ctx.reply('What is your email?');
  const email = await conversation.wait();
  await ctx.reply(`Thanks ${name.message.text}! Registered with ${email.message.text}`);
}

Middleware for auth:

function adminOnly(ctx, next) {
  if (ctx.from?.id !== Number(process.env.ADMIN_ID)) {
    return ctx.reply('⛔ Not authorized');
  }
  return next();
}
bot.command('admin', adminOnly, handleAdmin);

4. Keyboard Types

Inline Keyboard (attached to message):

• Callback buttons (callback_data) — triggers callbackQuery handler
• URL buttons (url) — opens a link
• Web App buttons (web_app) — opens a Mini App
• Switch Inline buttons (switch_inline_query) — triggers inline mode

Reply Keyboard (replaces phone keyboard):

• Custom keyboard with predefined responses
• one_time_keyboard: true to auto-hide after selection
• resize_keyboard: true for compact display

Remove Keyboard:

{ reply_markup: { remove_keyboard: true } }

5. Polling vs Webhooks

Long Polling (development):

bot.start(); // Calls getUpdates in a loop

• No public URL needed
• Slightly higher latency
• Good for development and low-traffic bots

Webhooks (production):

// With express
const app = express();
app.use(express.json());
app.use(`/bot${token}`, webhookCallback(bot, 'express'));
app.listen(3000);

// Set webhook
await bot.api.setWebhook(`https://yourdomain.com/bot${token}`);

• Requires HTTPS public URL
• Lower latency, better for high traffic
• Self-signed certificates supported with certificate parameter

6. Media Handling

// Send photo
await ctx.replyWithPhoto(new InputFile('./image.png'), { caption: 'Check this out' });

// Send document
await ctx.replyWithDocument(new InputFile(buffer, 'report.pdf'));

// Handle received photos
bot.on('message:photo', async (ctx) => {
  const file = await ctx.getFile();
  const url = `https://api.telegram.org/file/bot${token}/${file.file_path}`;
});

7. Bot API Limits

• Messages: 30 messages/sec globally, 1 message/sec per chat in groups
• Inline results: 50 results per query
• File upload: 50 MB max (20 MB for photos)
• File download: 20 MB via getFile
• Message length: 4096 characters
• Caption length: 1024 characters
• Inline keyboard: 100 buttons per message
• Webhook: 40M updates/hour

8. Deployment

• Simple: Railway, Render, Fly.io (webhook mode)
• Serverless: Vercel/AWS Lambda with webhook adapter
• VPS: systemd service with auto-restart
• Docker: Lightweight Node.js container with health checks

Examples

Example 1: Task Management Bot

Input: "Build a Telegram bot for my team to manage tasks. Users should be able to create tasks, assign them, set deadlines, and get reminders."

Output: A grammY bot with:

• /newtask command opening a conversation flow (title → description → assignee → deadline)
• Inline keyboard for task status updates (To Do → In Progress → Done)
• Daily reminder messages for overdue tasks using node-cron
• /mytasks showing personal task list with inline navigation
• SQLite database for persistence via better-sqlite3

Example 2: Content Publishing Bot

Input: "Create a Telegram bot that lets me draft posts, preview them, schedule them to a channel, and track engagement."

Output: A grammY bot with:

• Multi-step drafting flow with text, photos, and formatting preview
• Schedule picker with inline calendar keyboard
• Auto-publishing to target channel via bot.api.sendMessage(channelId, ...)
• Engagement tracking by checking message views via getChat and forwarded counts
• /drafts command listing scheduled posts with edit/delete options

Guidelines

• Always handle errors in callbacks — unhandled errors kill the bot process
• Use ctx.answerCallbackQuery() to dismiss the loading indicator on buttons
• Store bot token in env vars, never hardcode
• Use parse_mode: 'HTML' or 'MarkdownV2' for rich text (MarkdownV2 requires escaping special chars)
• Implement graceful shutdown: bot.stop() on SIGINT/SIGTERM
• For groups: handle my_chat_member updates to track when bot is added/removed
• Set commands list via bot.api.setMyCommands() for autocomplete
• Use ctx.chatAction = 'typing' for long operations
• Rate limit user interactions to prevent abuse
• For conversations: always handle the case where the user sends an unexpected message type