telegram-bot-builder

• Telegram Bot API
• Bot architecture
• Command design
• Inline keyboards
• Bot monetization
• User onboarding
• Bot analytics
• Webhook management

Bot Architecture

Structure for maintainable Telegram bots

When to use: When starting a new bot project

```python

Stack Options

| Language | Library | Best For |

|----------|---------|----------|

| Node.js | telegraf | Most projects |

| Node.js | grammY | TypeScript, modern |

| Python | python-telegram-bot | Quick prototypes |

| Python | aiogram | Async, scalable |

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

```python

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

| Pattern | Use Case |

|---------|----------|

| Single column | Simple menus |

| Multi column | Yes/No, pagination |

| Grid | Category selection |

| URL buttons | Links, payments |

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

```javascript

Revenue Models

| Model | Example | Complexity |

|-------|---------|------------|

| Freemium | Free basic, paid premium | Medium |

| Subscription | Monthly access | Medium |

| Per-use | Pay per action | Low |

| Ads | Sponsored messages | Low |

| Affiliate | Product recommendations | Low |

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 };

}

```

```

❌ 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.

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