grammY 統合による Telegram Bot 開発の効率化

Telegram Bot を開発していると、メディアのアップロードやレート制限の管理、複雑な Webhook の設定に頭を悩ませることがよくあります。手作業で API を叩くために fetch や FormData を組み上げるのは時間がかかりますし、エラー処理も煩雑になりがちです。

こうした低レイヤーの処理を自前で実装するよりも、定評のあるフレームワークを採用するのが賢い選択です。私たちは Telegram Bot API クライアントを grammY へ一本化しました。これにより、型安全な開発と安定したメッセージ配信が可能になります。

必要なもの

この統合を利用するには、以下の設定項目（Config knobs）が必要です。

• channels.telegram.botToken: Telegram Bot Father から取得したトークン
• channels.telegram.dmPolicy / channels.telegram.groupPolicy: メッセージの処理ポリシー
• channels.telegram.groups: 許可リストやメンションのデフォルト設定
• channels.telegram.allowFrom / channels.telegram.groupAllowFrom: アクセス許可設定
• channels.telegram.mediaMaxMb: 処理するメディアの最大サイズ
• channels.telegram.linkPreview: リンクプレビューの有効化設定
• channels.telegram.proxy: プロキシサーバーの設定（オプション）
• channels.telegram.webhookSecret / channels.telegram.webhookUrl: Webhook 利用時に必要
• channels.telegram.streamMode: 執筆中ステータスのストリーミング（Bot API 9.3+）

クイックスタート

grammY を使った Telegram Gateway のセットアップは非常にシンプルです。5 分ほどで最小構成を構築できます。

1. クライアントの初期化

これまで混在していた fetch ベースの実装は廃止され、grammY が唯一の Telegram クライアントとなります。デフォルトで grammY のスロットラー（Throttler）が有効になっており、レート制限を自動で管理します。

2. Gateway の起動

monitorTelegramProvider を使用して、grammY の Bot インスタンスを構築します。

• Long-poll モード: webhookUrl が未設定の場合、自動的にこのモードで動作します。
• Webhook モード: webhookUrl と webhookSecret を設定すると、webhookCallback を介して Webhook モードが有効になります。

3. セッション管理

セッションは自動的に整理されます。

• ダイレクトチャット（DM）: agent:<agentId>:<mainKey> としてメインセッションに統合されます。
• グループチャット: agent:<agentId>:telegram:group:<chatId> として個別に管理されます。

4. メディアの送信

sendMessage、sendPhoto、sendVideo、sendAudio、sendDocument といったメソッドを通じて、メディアを簡単に配信できます。

トラブルシューティング

開発中に遭遇する可能性のある問題と解決策です。

• Bot API 429 エラー: 大量のメッセージを送信してレート制限に達した場合は、grammY のスロットラープラグインが正しく機能しているか確認してください。
• メディアのテスト: 現在、ステッカーやボイスノートなどの構造化されたメディアテストを拡充中です。
• Webhook のポート: Webhook のリスンポートは現在 8787 に固定されています。Gateway を介さずに配線する場合は注意してください。

---

さらに詳しい設定や、特定のユースケースに合わせたカスタマイズが必要な場合は、AI Setup Assistant で質問してください。

次のステップ

• webhook-set.ts: Webhook の登録と削除の詳細
• webhook.ts: ヘルスチェックと正常なシャットダウンの実装
• monitorTelegramProvider: メンションや許可リストのフィルタリングロジック