# Telegram

Source: https://langbot.app/docs/ja/usage/platforms/telegram

LangBot で Telegram AI ボットを構築。GPT・Claude・Gemini・DeepSeek・Dify を Telegram のチャットやグループに接続。

## ボットを作成する

Telegram の公式 [BotFather](https://t.me/BotFather) を開き、`/newbot` を送信します。名前と、末尾が `bot` のユーザー名を設定してください。発行された Token は秘密に保ち、グループやスクリーンショットに含めないでください。

この手順は LangBot 4.11 の新しい Telegram アダプター（内部名 `telegram-omni`）向けです。非推奨の旧アダプターは選択しないでください。

## 設定して有効にする

1. LangBot で利用可能なモデルプロバイダーとモデルを設定し、Pipeline、Agent、またはプラグインプロセッサーを作成します。
2. 「ボット」で新規作成し、Telegram を選択して Token を入力します。
3. `message.received` にメッセージプロセッサーを割り当てます。Pipeline は会話フロー、Agent はイベントとツールによる処理に適しています。プラグインは独立してイベントを購読することもできます。
4. 必要に応じて Markdown とストリーミングを有効にし、ボットを有効化して保存します。割り当ての変更後も保存が必要です。
5. Telegram のプライベートチャットで **Start** を押してテストメッセージを送信します。LangBot の実行記録でも状態と返信ツールの結果を確認してください。

アダプターはロングポーリングを使用するため、LangBot から `api.telegram.org` への接続が必要です。受信用の Webhook を外部公開する必要はありません。同じ Token を複数のポーリングインスタンスで同時に使用しないでください。

### プロセッサーを選ぶ

| 方式       | 設定と確認                                                                                         |
| -------- | --------------------------------------------------------------------------------------------- |
| Pipeline | モデルと起動条件を設定します。グループのメンションやプレフィックスの条件も満たす必要があります。ストリーミング対応プロセッサーでは Telegram のメッセージを段階的に更新できます。 |
| Agent    | モデル、指示、イベントツールを設定します。`event_reply` などの送信ツールを使うよう指示してください。モデルが文章を生成しただけでは Telegram に届きません。     |
| プラグイン    | プロセッサーをインストール・設定し、ボットに割り当てて保存します。独立購読とメインプロセッサーは並行して動くため、同じメッセージに二つの返信が返る場合があります。             |

添付ファイルを扱う場合はプロセッサーの Box を有効にし、サンドボックスツールと添付送信機能を使用します。Box が正常に動作していることを確認してください。外部のファイルシステム MCP と Box は別のファイルシステムです。画像の理解には画像入力に対応したモデルも必要です。

ストリーミング設定を有効にしても、すべてのツール呼び出しが逐次表示になるわけではありません。Agent の `event_reply` は完成したメッセージを送信します。プラグインのストリーミングは実装によります。Telegram の実際の表示と実行ログをそれぞれ確認してください。

## プライベートチャットとグループ

プライベートチャットでは先に **Start** を押します。グループではテスト用グループにボットを追加し、ボット宛てコマンドやボットへの返信など、プロセッサーの起動条件に合わせて送信します。

すべてのグループ利用で **Privacy Mode** を無効にする必要はありません。Telegram は宛先付きコマンド、返信、管理者ボット、通常のグループメッセージで配信条件が異なります。通常のメッセージも受信するには、BotFather でプライバシーモードを変更して必要に応じて再追加するか、用途に応じた管理者権限を付与します。[Telegram の公式説明](https://core.telegram.org/bots/features#privacy-mode)も参照してください。

メンバー状態やリアクションの更新には、その更新種別に対する Telegram の管理者要件を満たす必要があります。必要な権限だけを付与し、受信のためだけに削除・メンバー制限・管理者追加などをすべて有効にしないでください。Telegram の配信条件と LangBot の起動条件の両方が適用されます。

通常のグループをスーパーグループに変更すると ID が変わります。ログの Bot API グループ ID は Telegram Web の URL に含まれる ID とも異なる場合があります。URL から ID を組み立てないでください。

## 画像・ファイル・ストリーミング

画像やファイルはメッセージの添付としてプロセッサーに渡されます。質問を明記した画像と内容を検証できるテキストファイルで確認し、「送信しました」という文章だけでなく、実際に返された添付を確認してください。

ストリーミングの文章は Telegram メッセージを更新して表示し、添付は完了時に別途送信します。生成ファイルは添付出力機能で送信し、サンドボックスのパスだけを返さないようにします。Telegram が写真として処理できない画像は、元の内容を保持するためファイルとして再送信します。

![実際のグループでの検証：Agent が画像を認識し、ファイルを読み取り、ファイルと生成画像を返信します。](https://langbot.app/docs/images/telegram/agent-group-media.jpg)

## その他のイベント

必要なイベントに Agent またはプラグインプロセッサーを割り当てます。Pipeline は主にメッセージフロー用です。非メッセージイベントをすべて通常チャットとして扱わないでください。

| イベント                     | 発生条件・意味                                              |
| ------------------------ | ---------------------------------------------------- |
| `message.received`       | プライベートまたはグループのメッセージ。対応する添付を含みます。                     |
| `message.edited`         | 送信済みメッセージの編集。                                        |
| `message.reaction`       | リアクションの追加・削除。方向は `is_add`、削除した絵文字も `reaction` に残ります。 |
| `group.member_joined`    | メンバーの参加。                                             |
| `group.member_left`      | 退出または削除。`is_kicked` を確認します。                          |
| `group.member_banned`    | ミュートなどの権限制限。グループからの削除とは異なります。                        |
| `bot.invited_to_group`   | ボットの追加。                                              |
| `bot.removed_from_group` | ボットの削除。直前に制限状態だった場合も含みます。                            |
| `bot.muted`              | メッセージ送信権限を失った状態。無期限の場合は `duration: null`。            |
| `bot.unmuted`            | 送信権限の回復。その他の制限が残っていても発生します。                          |
| `platform.specific`      | 権限変更やコールバックなど。`action` と `data` を確認します。              |

まず記録のみ行うプラグインで受信を確認してから、返信や管理操作を追加してください。ミュート・削除されたボットはイベントを受け取れても、元のグループに返信できない場合があります。受信成功と送信権限は別々に確認します。

## トラブルシューティング

- **返信がない**：有効化状態、保存済みの割り当て、Start、プライバシーモード、起動条件、実行記録を順に確認します。
- **返信は届いたが実行は失敗**：実行記録を開いてツールの戻り値を確認します。Telegram に文章があるだけでは処理全体の成功とは判断できません。
- **モデルのエラーやタイムアウト**：プロバイダーとモデルを、Telegram の配信問題とは分けて確認します。
- **パスだけが返る**：Box、ツール権限、実際の添付送信ツール呼び出しを確認します。
- **返信が重複する**：メイン処理と独立購読の重複、複数のポーリングインスタンスを確認します。
- **リアクション・メンバーイベントが来ない**：管理者状態とイベントの割り当てを確認します。実メンバーに影響しない専用グループで試してください。