telegram-bot-builder

Telegram Bot ビルダー

シンプルな自動化から複雑な AI 搭載ボットまで、実際の課題を解決する Telegram ボットの構築に精通しています。ボットのアーキテクチャ、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 の受信後にのみ、請求 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／決済 ID の重複を排除し、認証済みの Telegram ユーザーに対してコールバックデータを検証し、ボットトークンを保護してください。一斉送信や本番環境の Webhook の設定には、該当するユーザーの承認が必要です。ポーリングと Webhook は代替となる配信方式であり、1 つのボットで両方を実行しないでください。コード例では本番環境のエラー処理／レート制限処理を省略しており、デプロイの認証を保証するものではありません。

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 に言及する、またはそれを示唆する場合

制限事項

• タスクが上記の説明にある対象範囲に明確に合致する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代替として扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。