Telegram Bot Builder

Comprehensive guidance for building Telegram bots using the Bot API (v9.4). Covers both Node.js and Python ecosystems with production-ready patterns for authentication, messaging, keyboards, media handling, payments, inline mode, webhooks, and deployment.

When to Use This Skill

Use this skill when:

• Building a new Telegram bot from scratch
• Integrating Telegram messaging into an existing application
• Setting up webhooks or long polling for bot updates
• Creating interactive menus with inline keyboards and callback queries
• Handling media (photos, videos, documents, stickers)
• Implementing Telegram Payments or Telegram Stars
• Building inline mode functionality
• Managing groups, channels, or forum topics via bot
• Deploying bots to production (Docker, PM2, serverless)

Core Concepts

Authentication

Every bot has a unique token obtained from @BotFather. Token format: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.

All API calls go to: https://api.telegram.org/bot<TOKEN>/METHOD_NAME

# .env file
BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Store the token in environment variables. Never commit it to source code.

Receiving Updates: Polling vs Webhook

Long Polling (getUpdates) - Simpler, no HTTPS required, ideal for development:

// Node.js with node-telegram-bot-api
const bot = new TelegramBot(process.env.BOT_TOKEN, { polling: true });

# Python with python-telegram-bot
app = Application.builder().token(os.getenv("BOT_TOKEN")).build()
app.run_polling()

Webhook (setWebhook) - Better for production, lower latency, requires HTTPS (ports 443, 80, 88, or 8443):

bot.setWebHook('https://yourdomain.com/webhook', { secret_token: SECRET });

Choose polling for development and small bots. Choose webhooks for production deployments handling high traffic.

Message Types & Formatting

Send text with sendMessage. Supported parse modes:

• HTML: <b>bold</b>, <i>italic</i>, <code>code</code>, <pre>block</pre>, <a href="url">link</a>, <tg-spoiler>spoiler</tg-spoiler>
• MarkdownV2: *bold*, _italic_, `code`, ```block```, [link](url), ||spoiler||. Requires escaping: _*[]()~>#+-=|{}.!

Prefer HTML for easier escaping. Use MarkdownV2 when simpler formatting suffices.

Keyboards & Interactive Elements

Inline Keyboard - Buttons attached to messages:

bot.sendMessage(chatId, 'Choose:', {
  reply_markup: {
    inline_keyboard: [
      [{ text: 'Option A', callback_data: 'a' }, { text: 'Option B', callback_data: 'b' }],
      [{ text: 'Visit Site', url: 'https://example.com' }]
    ]
  }
});

Reply Keyboard - Custom keyboard below input field:

bot.sendMessage(chatId, 'Choose:', {
  reply_markup: {
    keyboard: [[{ text: '📊 Stats' }, { text: '⚙️ Settings' }]],
    resize_keyboard: true,
    one_time_keyboard: true
  }
});

Handle inline button presses with callback_query. The callback_data field is limited to 64 bytes. Always call answerCallbackQuery to dismiss the loading indicator.

Sending Media

// Photo (file_id, URL, or upload)
bot.sendPhoto(chatId, 'https://example.com/photo.jpg', { caption: 'A photo' });

// Document
bot.sendDocument(chatId, fs.createReadStream('./file.pdf'), { caption: 'Report' });

// Album (2-10 items)
bot.sendMediaGroup(chatId, [
  { type: 'photo', media: 'https://example.com/1.jpg', caption: 'First' },
  { type: 'photo', media: 'https://example.com/2.jpg' }
]);

Three ways to specify files: file_id (reuse previously uploaded), HTTP URL (Telegram downloads it), or multipart upload. File limits: 50MB upload, 20MB download via Bot API.

Conversation State

For multi-step interactions (registration, forms, wizards), maintain conversation state per chat:

• Node.js: Use a Map or Redis to track { step, data } per chatId
• Python: Use ConversationHandler from python-telegram-bot (built-in state machine)

See reference/patterns_and_examples.md for complete conversation flow implementations.

Error Handling

Handle common error scenarios:

• 429 Too Many Requests: Read retry_after from response, wait, then retry
• 403 Forbidden: Bot was blocked by user or removed from chat
• 400 Bad Request: Invalid parameters (check description field)
• 409 Conflict: Another bot instance using same token with polling

Rate limits: ~30 messages/second to different chats, ~20 messages/minute to same group. Implement exponential backoff for retries.

Bot Commands

Register commands visible in the Telegram menu:

bot.setMyCommands([
  { command: 'start', description: 'Start the bot' },
  { command: 'help', description: 'Show help' },
  { command: 'settings', description: 'Bot settings' }
]);

Commands can be scoped to specific chats, users, or languages using BotCommandScope.

Common Patterns

Quick Start (Node.js)

mkdir my-bot && cd my-bot
npm init -y
npm install node-telegram-bot-api dotenv
echo "BOT_TOKEN=your_token_here" > .env

Quick Start (Python)

mkdir my-bot && cd my-bot
pip install python-telegram-bot python-dotenv
echo "BOT_TOKEN=your_token_here" > .env

Popular Libraries

Language	Library	Style	Best For
Node.js	node-telegram-bot-api	Callback-based	Simple bots, quick prototypes
Node.js	grammy	Middleware-based	Complex bots, plugins
Node.js	telegraf	Middleware-based	Mature ecosystem
Python	python-telegram-bot	Handler-based	Full-featured, conversations
Python	aiogram	Async-first	High-performance async bots

Key API Method Categories

Category	Key Methods
Messages	sendMessage, sendPhoto, sendVideo, sendDocument, editMessageText, deleteMessage
Keyboards	InlineKeyboardMarkup, ReplyKeyboardMarkup, answerCallbackQuery
Chat Mgmt	getChat, banChatMember, promoteChatMember, setChatPermissions
Files	getFile, sendMediaGroup, sendDocument
Inline Mode	answerInlineQuery with InlineQueryResult* types
Payments	sendInvoice, answerPreCheckoutQuery (use currency: "XTR" for Telegram Stars)
Bot Config	setMyCommands, setMyDescription, setWebhook

Deployment Options

• PM2: pm2 start bot.js --name telegram-bot - Process manager with auto-restart
• Docker: Containerized deployment with docker-compose
• Serverless: Webhook handler as Vercel/AWS Lambda function
• VPS: Direct deployment with systemd service

See reference/patterns_and_examples.md for Docker, PM2, and serverless deployment configurations.

Security Checklist

• Store BOT_TOKEN in environment variables
• Validate X-Telegram-Bot-Api-Secret-Token on webhook endpoints
• Verify user IDs for admin commands
• Implement per-user rate limiting
• Sanitize user input before database storage
• Use HTTPS for all webhook endpoints
• Restrict allowed_updates to only needed types

Reference Files

For detailed API documentation and implementation patterns, consult:

• reference/api_methods.md - Complete list of 100+ Bot API methods organized by category (messaging, chat management, stickers, payments, inline mode, games, forum topics, gifts, passport, and more)
• reference/api_types.md - Complete list of 200+ Bot API types with all fields (Update, Message, Chat, User, keyboards, media types, payment types, chat members, reactions, and more)
• reference/patterns_and_examples.md - Production-ready implementation patterns for Node.js and Python including: inline keyboards, webhooks, media handling, conversation state management, database integration, admin panels, multi-language support, Docker/PM2/serverless deployment, Telegram Stars payments, and inline mode

When building a bot, start with SKILL.md for core concepts, then load the appropriate reference file for detailed API information or implementation patterns as needed.