diff --git a/en/usage/platforms/telegram.mdx b/en/usage/platforms/telegram.mdx index c256884e6..74f8cd1b9 100644 --- a/en/usage/platforms/telegram.mdx +++ b/en/usage/platforms/telegram.mdx @@ -4,30 +4,77 @@ description: "Build a Telegram AI bot with LangBot. Connect GPT, Claude, Gemini, icon: "/images/platforms/telegram.svg" --- -## Create Bot +## Create a bot -Go to the [Telegram Bot Creation Page](https://t.me/botfather), follow the prompts, and create a bot. +Open the official [BotFather](https://t.me/BotFather) in Telegram, send `/newbot`, and choose a name and a username ending in `bot`. Keep the returned Token private; do not include it in group messages or screenshots. -![Telegram Bot Creation](/images/zh/deploy/bots/telegram/telegram_01.png) +This guide covers the new Telegram adapter in LangBot 4.11 (internal name `telegram-omni`). Do not select the deprecated legacy adapter. -![Telegram Bot Creation](/images/zh/deploy/bots/telegram/telegram_02.png) +## Configure and enable -After creation, BotFather will return an API Token, please keep it safe. Next, turn off `Privacy Mode` to use it in group chats. +1. Configure a working model provider and model in LangBot, then create a Pipeline, Agent, or plugin processor. +2. Create a bot under **Bots**, select Telegram, and enter the Token. +3. Bind a message processor to `message.received`. A Pipeline runs a conversation flow; an Agent handles events with tools. Plugin processors can also subscribe independently. +4. Enable Markdown and streaming as needed, enable the bot, and save. Save again after changing processor bindings. +5. Open the bot's private chat in Telegram, click **Start**, and send a test message. Check the processor's run status and reply tool result in LangBot as well. -![Telegram Bot API Token](/images/zh/deploy/bots/telegram/telegram_03.png) +The adapter uses long polling and requires outbound access to `api.telegram.org`. An inbound Webhook is not required to receive messages. Only one polling instance should use a Token; do not enable the same bot in another LangBot instance simultaneously. -## Connect to LangBot +### Choose a processor -Open the LangBot Webui page, create a new bot +| Type | Configuration and checks | +| --- | --- | +| Pipeline | Set the model and trigger rules. Group mentions or prefixes must still match the rules. With streaming enabled, a streaming-capable processor can progressively update the Telegram message. | +| Agent | Configure the model, instructions, and event tools. Instruct it to use `event_reply` or another sending tool; model text alone does not prove delivery to Telegram. | +| Plugin processor | Install and configure the plugin processor, bind it to the bot, and save. Independent subscriptions can run alongside the main processor, so one message can produce two replies. | -![Connect to LangBot](/images/zh/deploy/bots/telegram/connect_to_langbot.png) +For attachment tasks, enable Box for the processor and use its sandbox tools and attachment delivery capabilities. Box must be ready. An external filesystem MCP server does not share Box's filesystem. Image understanding also requires a vision-capable model. -After filling in, start LangBot. If configured successfully, the log will show `[02-02 16:48:15.263] manager.py (68) - [INFO] : Initializing platform adapter 1: telegram`, keep LangBot running. +The bot's streaming toggle does not make every tool call stream tokens. An Agent's `event_reply` sends a complete message; plugin streaming depends on its implementation. Verify actual Telegram updates and processor logs separately. -## Use Bot +## Private chats and groups -Now you can use the bot normally in groups or private messages. +Click **Start** in a private chat first. For groups, add the bot to a test group and follow the processor's trigger rules, for example with a command addressed to the bot or a reply to its message. -![Telegram Bot Usage](/images/zh/deploy/bots/telegram/telegram_04.png) +Disabling **Privacy Mode** is not mandatory for every group scenario. Telegram delivers different messages for directed commands, replies, administrator bots, and ordinary group traffic. To receive ordinary group messages, adjust privacy mode in BotFather and re-add the bot when Telegram requires it, or grant administrator status where appropriate. See [Telegram's privacy mode documentation](https://core.telegram.org/bots/features#privacy-mode). -![Telegram Bot Usage](/images/zh/deploy/bots/telegram/telegram_05.png) +Member-status and reaction updates must satisfy Telegram's administrator requirements for those update types. Grant only the permissions the feature needs; do not enable deletion, bans, or adding administrators merely to receive events. Telegram delivery rules and LangBot trigger rules both apply. + +Upgrading a basic group to a supergroup changes its ID. The Bot API group ID in event logs can also differ from the Telegram Web URL; do not construct a group ID from that URL. + +## Images, files, and streaming + +Images and files arrive as message attachments. Test with a clearly captioned image and a text file whose content can be checked. Verify the actual returned image or file rather than a textual claim that it was sent. + +Streaming text progressively updates a Telegram message; attachments are sent separately at completion. Generated files must use the processor's attachment output mechanism, not just return a sandbox path. Images Telegram cannot process as photos are retried as documents to preserve their original bytes. + +![Real group acceptance: the Agent identifies an image, reads a file, and returns a file and a generated image.](/images/telegram/agent-group-media.jpg) + +## Other events + +Bind an Agent or plugin processor to the required events. Pipelines primarily handle message flows; do not treat every non-message event as ordinary chat. + +| Event | Trigger and meaning | +| --- | --- | +| `message.received` | A private or group message, including supported attachments. | +| `message.edited` | An existing message is edited. | +| `message.reaction` | A user adds or removes a reaction. `is_add` identifies the direction; `reaction` retains the removed emoji. | +| `group.member_joined` | A member joins. | +| `group.member_left` | A member leaves or is removed; inspect `is_kicked`. | +| `group.member_banned` | A member is restricted, such as being muted; this does not mean they were removed. | +| `bot.invited_to_group` | The bot is added to a group. | +| `bot.removed_from_group` | The bot is removed, including when previously restricted. | +| `bot.muted` | The bot loses permission to send messages. An indefinite restriction has `duration: null`. | +| `bot.unmuted` | Sending permission is restored, even if other restrictions remain. | +| `platform.specific` | Other platform events, such as permission changes or callbacks. Inspect `action` and `data`. | + +Start with a logging-only plugin processor to confirm delivery before adding replies or moderation actions. A muted or removed bot may receive the event while no longer being able to reply in that group. Evaluate reception and sending permission separately. + +## Troubleshooting + +- **No reply:** check enabled state, saved bindings, private-chat Start, group privacy mode, and trigger rules, then inspect the processor run. +- **Delivered message but failed run:** expand the run and inspect tool results. A visible Telegram message alone does not prove the entire task succeeded. +- **Model errors or timeouts:** check the provider and model separately from Telegram delivery. +- **Only a file path is returned:** check Box, tool permissions, and whether the attachment sending tool actually ran. +- **Duplicate replies:** check overlapping main/independent subscriptions and multiple polling instances. +- **Missing reactions or member events:** check administrator status and event bindings. Test in a dedicated group without affecting real members. diff --git a/images/telegram/agent-group-media.jpg b/images/telegram/agent-group-media.jpg new file mode 100644 index 000000000..17caecdae Binary files /dev/null and b/images/telegram/agent-group-media.jpg differ diff --git a/ja/usage/platforms/telegram.mdx b/ja/usage/platforms/telegram.mdx index 35b6380be..07d62fb0f 100644 --- a/ja/usage/platforms/telegram.mdx +++ b/ja/usage/platforms/telegram.mdx @@ -4,30 +4,77 @@ description: "LangBot で Telegram AI ボットを構築。GPT・Claude・Gemini icon: "/images/platforms/telegram.svg" --- -## ボットの作成 +## ボットを作成する -[Telegram Bot Creation Page](https://t.me/botfather)にアクセスし、プロンプトに従ってボットを作成します。 +Telegram の公式 [BotFather](https://t.me/BotFather) を開き、`/newbot` を送信します。名前と、末尾が `bot` のユーザー名を設定してください。発行された Token は秘密に保ち、グループやスクリーンショットに含めないでください。 -![Telegram Bot Creation](/images/zh/deploy/bots/telegram/telegram_01.png) +この手順は LangBot 4.11 の新しい Telegram アダプター（内部名 `telegram-omni`）向けです。非推奨の旧アダプターは選択しないでください。 -![Telegram Bot Creation](/images/zh/deploy/bots/telegram/telegram_02.png) +## 設定して有効にする -作成後、BotFather は API Token を返しますので、安全に保管してください。次に、グループチャットで使用するために「Privacy Mode」をオフにします。 +1. LangBot で利用可能なモデルプロバイダーとモデルを設定し、Pipeline、Agent、またはプラグインプロセッサーを作成します。 +2. 「ボット」で新規作成し、Telegram を選択して Token を入力します。 +3. `message.received` にメッセージプロセッサーを割り当てます。Pipeline は会話フロー、Agent はイベントとツールによる処理に適しています。プラグインは独立してイベントを購読することもできます。 +4. 必要に応じて Markdown とストリーミングを有効にし、ボットを有効化して保存します。割り当ての変更後も保存が必要です。 +5. Telegram のプライベートチャットで **Start** を押してテストメッセージを送信します。LangBot の実行記録でも状態と返信ツールの結果を確認してください。 -![Telegram Bot API Token](/images/zh/deploy/bots/telegram/telegram_03.png) +アダプターはロングポーリングを使用するため、LangBot から `api.telegram.org` への接続が必要です。受信用の Webhook を外部公開する必要はありません。同じ Token を複数のポーリングインスタンスで同時に使用しないでください。 -## LangBot に接続 +### プロセッサーを選ぶ -LangBot Webui ページを開き、新しいボットを作成します +| 方式 | 設定と確認 | +| --- | --- | +| Pipeline | モデルと起動条件を設定します。グループのメンションやプレフィックスの条件も満たす必要があります。ストリーミング対応プロセッサーでは Telegram のメッセージを段階的に更新できます。 | +| Agent | モデル、指示、イベントツールを設定します。`event_reply` などの送信ツールを使うよう指示してください。モデルが文章を生成しただけでは Telegram に届きません。 | +| プラグイン | プロセッサーをインストール・設定し、ボットに割り当てて保存します。独立購読とメインプロセッサーは並行して動くため、同じメッセージに二つの返信が返る場合があります。 | -![Connect to LangBot](/images/zh/deploy/bots/telegram/connect_to_langbot.png) +添付ファイルを扱う場合はプロセッサーの Box を有効にし、サンドボックスツールと添付送信機能を使用します。Box が正常に動作していることを確認してください。外部のファイルシステム MCP と Box は別のファイルシステムです。画像の理解には画像入力に対応したモデルも必要です。 -入力後、LangBot を起動します。設定が成功した場合、ログに `[02-02 16:48:15.263] manager.py (68) - [INFO] : Initializing platform adapter 1: telegram` と表示されます。LangBot を実行し続けてください。 +ストリーミング設定を有効にしても、すべてのツール呼び出しが逐次表示になるわけではありません。Agent の `event_reply` は完成したメッセージを送信します。プラグインのストリーミングは実装によります。Telegram の実際の表示と実行ログをそれぞれ確認してください。 -## ボットの使用 +## プライベートチャットとグループ -グループまたはプライベートメッセージでボットを通常どおり使用できるようになりました。 +プライベートチャットでは先に **Start** を押します。グループではテスト用グループにボットを追加し、ボット宛てコマンドやボットへの返信など、プロセッサーの起動条件に合わせて送信します。 -![Telegram Bot Usage](/images/zh/deploy/bots/telegram/telegram_04.png) +すべてのグループ利用で **Privacy Mode** を無効にする必要はありません。Telegram は宛先付きコマンド、返信、管理者ボット、通常のグループメッセージで配信条件が異なります。通常のメッセージも受信するには、BotFather でプライバシーモードを変更して必要に応じて再追加するか、用途に応じた管理者権限を付与します。[Telegram の公式説明](https://core.telegram.org/bots/features#privacy-mode)も参照してください。 -![Telegram Bot Usage](/images/zh/deploy/bots/telegram/telegram_05.png) +メンバー状態やリアクションの更新には、その更新種別に対する Telegram の管理者要件を満たす必要があります。必要な権限だけを付与し、受信のためだけに削除・メンバー制限・管理者追加などをすべて有効にしないでください。Telegram の配信条件と LangBot の起動条件の両方が適用されます。 + +通常のグループをスーパーグループに変更すると ID が変わります。ログの Bot API グループ ID は Telegram Web の URL に含まれる ID とも異なる場合があります。URL から ID を組み立てないでください。 + +## 画像・ファイル・ストリーミング + +画像やファイルはメッセージの添付としてプロセッサーに渡されます。質問を明記した画像と内容を検証できるテキストファイルで確認し、「送信しました」という文章だけでなく、実際に返された添付を確認してください。 + +ストリーミングの文章は Telegram メッセージを更新して表示し、添付は完了時に別途送信します。生成ファイルは添付出力機能で送信し、サンドボックスのパスだけを返さないようにします。Telegram が写真として処理できない画像は、元の内容を保持するためファイルとして再送信します。 + +![実際のグループでの検証：Agent が画像を認識し、ファイルを読み取り、ファイルと生成画像を返信します。](/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、ツール権限、実際の添付送信ツール呼び出しを確認します。 +- **返信が重複する**：メイン処理と独立購読の重複、複数のポーリングインスタンスを確認します。 +- **リアクション・メンバーイベントが来ない**：管理者状態とイベントの割り当てを確認します。実メンバーに影響しない専用グループで試してください。 diff --git a/zh/usage/platforms/telegram.mdx b/zh/usage/platforms/telegram.mdx index dfb1b538b..7ab48d32c 100644 --- a/zh/usage/platforms/telegram.mdx +++ b/zh/usage/platforms/telegram.mdx @@ -6,28 +6,75 @@ icon: "/images/platforms/telegram.svg" ## 创建机器人 -前往 [Telegram 机器人创建页面](https://t.me/botfather)，按照提示操作，创建一个机器人。 +在 Telegram 打开官方 [BotFather](https://t.me/BotFather)，发送 `/newbot`，依次设置名称和以 `bot` 结尾的用户名。保存 BotFather 返回的 Token，不要把它发到群里或放入截图。 -![Telegram 机器人创建](/images/zh/deploy/bots/telegram/telegram_01.png) +本文适用于 LangBot 4.11 的新版 Telegram 适配器（内部名称 `telegram-omni`）。不要选择标记为过时的旧版适配器。 -![Telegram 机器人创建](/images/zh/deploy/bots/telegram/telegram_02.png) +## 配置并启用 -创建完成后，BotFather 会返回一个 API Token，请妥善保存。接下来关闭`Privacy Mode`，以便在群聊中使用。 +1. 在 LangBot 配置可用的模型供应商和模型，再创建 Pipeline、Agent 或插件处理器。 +2. 在「机器人」中新建机器人，选择 Telegram，填写 Token。 +3. 为 `message.received` 配置消息处理器。Pipeline 适合现有对话流程；Agent 通过事件与工具处理任务。插件处理器也可以独立订阅事件。 +4. 根据需要打开 Markdown 和流式回复，启用机器人并保存。修改处理器绑定后也要保存。 +5. 在 Telegram 私聊机器人，点击 **Start**，发送一条测试消息；同时在 LangBot 的处理器运行记录中检查状态和回复工具结果。 -![Telegram 机器人 API Token](/images/zh/deploy/bots/telegram/telegram_03.png) +适配器通过长轮询连接 Telegram，需要 LangBot 所在环境能访问 `api.telegram.org`。不需要为收消息额外暴露入站 Webhook。一个 Token 只应由一个轮询实例使用；不要同时在另一套 LangBot 中启用同一个机器人。 -## 对接 LangBot +### 选择处理器 -打开 LangBot Webui 页面，创建一个新机器人 +| 方式 | 配置与检查 | +| --- | --- | +| Pipeline | 配置模型和触发条件。群聊的 @、前缀等触发条件仍需满足；开启流式回复后，支持流式的处理器可逐步更新 Telegram 消息。 | +| Agent | 配置模型、指令及事件工具。要求 Agent 使用 `event_reply` 等工具回复；模型生成了文本不等于消息已发送到 Telegram。 | +| 插件处理器 | 安装并创建相应插件处理器，将它绑定到机器人并保存。独立订阅可与主处理器并行，因此同一条消息可能产生两份回复。 | -![对接 LangBot](/images/zh/deploy/bots/telegram/connect_to_langbot.png) +需要读写附件时，为相应处理器启用 Box，并使用其沙盒工具和附件发送能力。Box 必须处于可用状态。外部文件系统 MCP 与 Box 不是同一个文件系统。图片理解还需要支持视觉的模型。 -填写完成后启动 LangBot，若成功配置，日志中会出现`[02-02 16:48:15.263] manager.py (68) - [INFO] : 初始化平台适配器 1: telegram`的字样，保持 LangBot 运行。 +机器人上的流式开关不会把所有工具调用都变成逐字输出。Agent 的一次 `event_reply` 是一次完整发送；插件是否流式取决于插件实现。请分别核对 Telegram 中的实际更新和处理器日志，不能只看开关。 -## 使用机器人 +## 私聊与群聊 -现在在群里或者私聊机器人都可以正常使用了。 +私聊应先点击 **Start**。群聊则先把机器人加入测试群，再按处理器触发规则发送消息，例如发给机器人的命令或回复机器人的消息。 -![Telegram 机器人使用](/images/zh/deploy/bots/telegram/telegram_04.png) +不必为了所有群聊场景都关闭 **Privacy Mode**。隐私模式会影响 Telegram 向机器人投递哪些消息；定向命令、回复和管理员身份的行为与普通群消息不同。如果需要接收群内普通消息，可以在 BotFather 中调整隐私模式，按 Telegram 的提示重新添加机器人，或按需要授予管理员身份。详见 [Telegram 官方隐私模式说明](https://core.telegram.org/bots/features#privacy-mode)。 -![Telegram 机器人使用](/images/zh/deploy/bots/telegram/telegram_05.png) +接收成员状态、表情等更新时，需要满足 Telegram 对相应更新的管理员要求。只授予实际功能需要的权限；不要为了接收事件直接打开删除消息、封禁成员、添加管理员等全部权限。Telegram 侧投递规则和 LangBot 处理器触发条件需要同时满足。 + +普通群升级为超级群后，群 ID 会改变。事件日志中的 Bot API 群 ID 与 Telegram Web 地址栏中的 ID 也不一定相同，不要直接从网页地址拼接群 ID。 + +## 图片、文件与流式回复 + +图片和文件可以作为消息附件进入处理器。测试时发送带有明确问题的图片、内容可校验的文本文件，并检查真实返回的图片或文件，而不仅是“已发送”的文本。 + +流式文本在 Telegram 中通过持续更新消息展示；附件在结束时单独发送。生成文件必须使用处理器提供的附件输出机制，不能只返回沙盒路径。Telegram 无法作为照片处理的图片会尝试以文件发送，便于保留原始内容。 + +![真实群聊验收：Agent 识别图片、读取文件并返回文件和生成的图片。](/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、模型工具权限，以及是否真正调用了附件发送工具。 +- **重复回复**：检查主处理器与独立订阅是否同时处理同一事件，以及是否有多个轮询实例。 +- **收不到表情或成员事件**：检查机器人管理员身份和事件绑定；先在专用测试群操作，避免影响真实成员。