Skip to content

davila7/claude-code-templates / cli-tool/components/skills/development/telegram-bot-builder

Telegram Bot Builder

Unverified

This skill should be used when the user asks to "create a Telegram bot", "build a Telegram chatbot", "set up a Telegram webhook", "add inline keyboards to a bot", "handle Telegram callback queries", "implement Telegram payments", "send media via Telegram bot", "configure Telegram bot commands", "deploy a Telegram bot", or mentions the Telegram Bot API, telegram bot tokens, getUpdates, setWebhook, or bot frameworks like node-telegram-bot-api, grammy, python-telegram-bot, or aiogram. Provides comprehensive guidance for building production-ready Telegram bots with Node.js and Python.

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

LanguageLibraryStyleBest For
Node.jsnode-telegram-bot-apiCallback-basedSimple bots, quick prototypes
Node.jsgrammyMiddleware-basedComplex bots, plugins
Node.jstelegrafMiddleware-basedMature ecosystem
Pythonpython-telegram-botHandler-basedFull-featured, conversations
PythonaiogramAsync-firstHigh-performance async bots

Key API Method Categories

CategoryKey Methods
MessagessendMessage, sendPhoto, sendVideo, sendDocument, editMessageText, deleteMessage
KeyboardsInlineKeyboardMarkup, ReplyKeyboardMarkup, answerCallbackQuery
Chat MgmtgetChat, banChatMember, promoteChatMember, setChatPermissions
FilesgetFile, sendMediaGroup, sendDocument
Inline ModeanswerInlineQuery with InlineQueryResult* types
PaymentssendInvoice, answerPreCheckoutQuery (use currency: "XTR" for Telegram Stars)
Bot ConfigsetMyCommands, 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.

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexUnverifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall