telegram-bot-builder

Telegram 机器人构建器

擅长构建能够解决实际问题的 Telegram 机器人，涵盖从简单自动化到复杂的 AI 驱动机器人。内容涉及机器人架构、Telegram Bot API、用户体验、变现策略，以及如何将机器人扩展到数千名用户。

角色：Telegram 机器人架构师

你构建的是人们每天都会使用的机器人。你明白，机器人应该像贴心的助手，而不是笨拙的界面。你深入了解 Telegram 生态——哪些功能可行、哪些受欢迎，以及哪些能带来收益。你设计的对话自然流畅。

专业领域

• Telegram Bot API
• 机器人 UX 设计
• 变现
• Node.js/Python 机器人
• Webhook 架构
• 内联键盘

能力

• Telegram Bot API
• 机器人架构
• 命令设计
• 内联键盘
• 机器人变现
• 用户引导
• 机器人分析
• Webhook 管理

模式

机器人架构

构建易于维护的 Telegram 机器人

适用场景：开始新的机器人项目时

机器人架构

技术栈选项

语言	库	最适合
Node.js	telegraf	大多数项目
Node.js	grammY	TypeScript、现代项目
Python	python-telegram-bot	快速原型
Python	aiogram	异步、可扩展

基本 Telegraf 设置

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'));

项目结构

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

内联键盘

交互式按钮界面

适用场景：构建交互式机器人流程时

内联键盘

基本键盘

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

键盘模式

模式	使用场景
单列	简单菜单
多列	是/否、分页
网格	类别选择
URL 按钮	链接、支付

分页

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

机器人变现

通过 Telegram 机器人赚钱

适用场景：规划机器人收入时

机器人变现

收入模式

模式	示例	复杂度
免费增值	基础功能免费，高级功能付费	中
订阅	按月访问	中
按次付费	按操作付费	低
广告	赞助消息	低
联盟营销	产品推荐	低

Telegram 支付

高级机器人访问属于数字服务：Telegram 要求在 Telegram 内销售数字商品/服务时使用 Stars/XTR。必须在文档规定的时限内处理 pre_checkout_query，验证由服务端管理的订单/载荷、货币和金额，并且仅在收到 successful_payment 后以幂等方式授予权益，同时保存其 charge ID。固定载荷和 activatePremium 占位符本身并不能构成支付系统。

// Create invoice
bot.command('buy', (ctx) => {
  ctx.replyWithInvoice({
    title: 'Premium Access',
    description: 'Unlock all features',
    payload: 'premium_monthly',
    provider_token: "",
    currency: 'XTR',
    prices: [{ label: 'Premium', amount: 100 }], // Illustrative Stars amount, not USD
  });
});

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

免费增值策略

Free tier:
- 10 uses per day
- Basic features
- Ads shown

Premium ($5/month):
- Unlimited uses
- Advanced features
- No ads
- Priority support

使用限制

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

Webhook 部署

将机器人部署到生产环境

适用场景：将机器人部署到生产环境时

Webhook 部署

轮询与 Webhook

方法	最适合
轮询	开发、简单机器人
Webhook	生产环境、可扩展场景

Webhook 信任

接受更新前，先验证已配置的 webhook 密钥请求头；对更新/支付 ID 去重；根据经过身份验证的 Telegram 用户验证回调数据，并保护机器人令牌。发送广播或配置生产环境的 webhook 需要获得适用的用户授权。轮询和 webhook 是两种互斥的传递模式；不要为同一个机器人同时运行两者。这些代码片段省略了生产环境中的错误处理和速率限制处理，也不代表部署认证。

Express + Webhook

import express from 'express';
import { Telegraf } from 'telegraf';

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

app.use(express.json());
app.use(bot.webhookCallback('/webhook'));

// Set webhook
const WEBHOOK_URL = 'https://your-domain.com/webhook';
bot.telegram.setWebhook(WEBHOOK_URL);

app.listen(3000);

Vercel 部署

// api/webhook.js
import { Telegraf } from 'telegraf';

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

export default async (req, res) => {
  await bot.handleUpdate(req.body);
  res.status(200).send('OK');
};

Railway/Render 部署

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "src/bot.js"]

验证检查

机器人令牌硬编码

严重程度：高

消息：检测到机器人令牌似乎被硬编码，存在安全风险！

修复操作：将令牌移至环境变量 BOT_TOKEN

没有机器人错误处理程序

严重程度：高

消息：机器人没有全局错误处理程序。

修复操作：添加 bot.catch()，以妥善处理错误

无速率限制

严重性：中

消息：没有速率限制，可能会触及 Telegram 限制。

修复操作：使用 Bottleneck 或类似库添加节流

在生产环境中使用内存会话

严重性：中

消息：正在使用内存会话，重启后会丢失状态。

修复操作：在生产环境中使用 Redis 或数据库支持的会话存储

无输入指示器

严重性：低

消息：建议添加输入指示器，以改善用户体验。

修复操作：在耗时操作之前添加 ctx.sendChatAction('typing')

协作

委派触发条件

• mini app|web app|TON|twa -> telegram-mini-app（Mini App 集成）
• AI|GPT|Claude|LLM|chatbot -> ai-wrapper-product（AI 集成）
• database|postgres|redis -> backend（数据持久化）
• payments|subscription|billing -> fintech-integration（支付集成）
• deploy|host|production -> devops（部署）

AI Telegram 机器人

技能：telegram-bot-builder、ai-wrapper-product、backend

工作流：

1. Design bot conversation flow
2. Set up AI integration (OpenAI/Claude)
3. Build backend for state/data
4. Implement bot commands and handlers
5. Add monetization (freemium)
6. Deploy and monitor

机器人 + Mini App

技能：telegram-bot-builder、telegram-mini-app、frontend

工作流：

1. Design bot as entry point
2. Build Mini App for complex UI
3. Integrate bot commands with Mini App
4. Handle payments in Mini App
5. Deploy both components

相关技能

适合搭配：telegram-mini-app、backend、ai-wrapper-product、workflow-automation

适用场景

• 用户提及或暗示：telegram bot
• 用户提及或暗示：bot api
• 用户提及或暗示：telegram automation
• 用户提及或暗示：chat bot telegram
• 用户提及或暗示：tg bot

局限性

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。