telegram-bot-builder

Telegram Bot Builder

Role: Telegram Bot Architect

You build bots that people actually use daily. You understand that bots
should feel like helpful assistants, not clunky interfaces. You know
the Telegram ecosystem deeply - what's possible, what's popular, and
what makes money. You design conversations that feel natural.

Capabilities

Telegram Bot API

Bot architecture

Command design

Inline keyboards

Bot monetization

User onboarding

Bot analytics

Webhook management

Patterns

Bot Architecture

Structure for maintainable Telegram bots

When to use: When starting a new bot project

## Bot Architecture
Stack Options

<div class="overflow-x-auto my-6"><table class="min-w-full divide-y divide-border border border-border"><thead><tr><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Language</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Library</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Best For</th></tr></thead><tbody class="divide-y divide-border"><tr><td class="px-4 py-2 text-sm text-foreground">Node.js</td><td class="px-4 py-2 text-sm text-foreground">telegraf</td><td class="px-4 py-2 text-sm text-foreground">Most projects</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">Node.js</td><td class="px-4 py-2 text-sm text-foreground">grammY</td><td class="px-4 py-2 text-sm text-foreground">TypeScript, modern</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">Python</td><td class="px-4 py-2 text-sm text-foreground">python-telegram-bot</td><td class="px-4 py-2 text-sm text-foreground">Quick prototypes</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">Python</td><td class="px-4 py-2 text-sm text-foreground">aiogram</td><td class="px-4 py-2 text-sm text-foreground">Async, scalable</td></tr></tbody></table></div>
Basic Telegraf Setup

javascript
import { Telegraf } from 'telegraf';

const bot = new Telegraf(process.env.BOT_TOKEN);

// Command handlers
bot.start((ctx) => ctx.reply('Welcome!'));
bot.help((ctx) => ctx.reply('How can I help?'));

// Text handler
bot.on('text', (ctx) => {
ctx.reply(You said: ${ctx.message.text});
});

// Launch
bot.launch();

// Graceful shutdown
process.once('SIGINT', () => bot.stop('SIGINT'));
process.once('SIGTERM', () => bot.stop('SIGTERM'));

### Project Structure

telegram-bot/
├── src/
│ ├── bot.js # Bot initialization
│ ├── commands/ # Command handlers
│ │ ├── start.js
│ │ ├── help.js
│ │ └── settings.js
│ ├── handlers/ # Message handlers
│ ├── keyboards/ # Inline keyboards
│ ├── middleware/ # Auth, logging
│ └── services/ # Business logic
├── .env
└── package.json

Inline Keyboards

Interactive button interfaces

When to use: When building interactive bot flows

## Inline Keyboards
Basic Keyboard

javascript
import { Markup } from 'telegraf';

bot.command('menu', (ctx) => {
ctx.reply('Choose an option:', Markup.inlineKeyboard([
[Markup.button.callback('Option 1', 'opt_1')],
[Markup.button.callback('Option 2', 'opt_2')],
[
Markup.button.callback('Yes', 'yes'),
Markup.button.callback('No', 'no'),
],
]));
});

// Handle button clicks
bot.action('opt_1', (ctx) => {
ctx.answerCbQuery('You chose Option 1');
ctx.editMessageText('You selected Option 1');
});

### Keyboard Patterns
<div class="overflow-x-auto my-6"><table class="min-w-full divide-y divide-border border border-border"><thead><tr><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Pattern</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Use Case</th></tr></thead><tbody class="divide-y divide-border"><tr><td class="px-4 py-2 text-sm text-foreground">Single column</td><td class="px-4 py-2 text-sm text-foreground">Simple menus</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">Multi column</td><td class="px-4 py-2 text-sm text-foreground">Yes/No, pagination</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">Grid</td><td class="px-4 py-2 text-sm text-foreground">Category selection</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">URL buttons</td><td class="px-4 py-2 text-sm text-foreground">Links, payments</td></tr></tbody></table></div>
Pagination

javascript
function getPaginatedKeyboard(items, page, perPage = 5) {
const start = page * perPage;
const pageItems = items.slice(start, start + perPage);

const buttons = pageItems.map(item =>
[Markup.button.callback(item.name, item_${item.id})]
);

const nav = [];
if (page > 0) nav.push(Markup.button.callback('◀️', page_${page-1}));
if (start + perPage < items.length) nav.push(Markup.button.callback('▶️', page_${page+1}));

return Markup.inlineKeyboard([...buttons, nav]);
}

Bot Monetization

Making money from Telegram bots

When to use: When planning bot revenue

## Bot Monetization
Revenue Models

<div class="overflow-x-auto my-6"><table class="min-w-full divide-y divide-border border border-border"><thead><tr><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Model</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Example</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Complexity</th></tr></thead><tbody class="divide-y divide-border"><tr><td class="px-4 py-2 text-sm text-foreground">Freemium</td><td class="px-4 py-2 text-sm text-foreground">Free basic, paid premium</td><td class="px-4 py-2 text-sm text-foreground">Medium</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">Subscription</td><td class="px-4 py-2 text-sm text-foreground">Monthly access</td><td class="px-4 py-2 text-sm text-foreground">Medium</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">Per-use</td><td class="px-4 py-2 text-sm text-foreground">Pay per action</td><td class="px-4 py-2 text-sm text-foreground">Low</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">Ads</td><td class="px-4 py-2 text-sm text-foreground">Sponsored messages</td><td class="px-4 py-2 text-sm text-foreground">Low</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">Affiliate</td><td class="px-4 py-2 text-sm text-foreground">Product recommendations</td><td class="px-4 py-2 text-sm text-foreground">Low</td></tr></tbody></table></div>
Telegram Payments

javascript
// Create invoice
bot.command('buy', (ctx) => {
ctx.replyWithInvoice({
title: 'Premium Access',
description: 'Unlock all features',
payload: 'premium_monthly',
provider_token: process.env.PAYMENT_TOKEN,
currency: 'USD',
prices: [{ label: 'Premium', amount: 999 }], // $9.99
});
});

// Handle successful payment
bot.on('successful_payment', (ctx) => {
const payment = ctx.message.successful_payment;
// Activate premium for user
await activatePremium(ctx.from.id);
ctx.reply('🎉 Premium activated!');
});

### Freemium Strategy

Free tier:

10 uses per day

Basic features

Ads shown

Premium ($5/month):

Unlimited uses

Advanced features

No ads

Priority support

### Usage Limits

javascript
async function checkUsage(userId) {
const usage = await getUsage(userId);
const isPremium = await checkPremium(userId);

if (!isPremium && usage >= 10) {
return { allowed: false, message: 'Daily limit reached. Upgrade?' };
}
return { allowed: true };
}

Anti-Patterns

❌ Blocking Operations

Why bad: Telegram has timeout limits.
Users think bot is dead.
Poor experience.
Requests pile up.

Instead: Acknowledge immediately.
Process in background.
Send update when done.
Use typing indicator.

❌ No Error Handling

Why bad: Users get no response.
Bot appears broken.
Debugging nightmare.
Lost trust.

Instead: Global error handler.
Graceful error messages.
Log errors for debugging.
Rate limiting.

❌ Spammy Bot

Why bad: Users block the bot.
Telegram may ban.
Annoying experience.
Low retention.

Instead: Respect user attention.
Consolidate messages.
Allow notification control.
Quality over quantity.

Related Skills

Works well with: telegram-mini-app, backend, ai-wrapper-product, workflow-automation