Telegram Integration — Telegram 集成

Telegram集成概述 按照固定的集成检查清单、策略模型和故障排除流程，安全可靠地在多台机器上设置Telegram。 快速工作流程 确认集成范围：仅限私聊、仅限群聊或两者皆可。 首先配置账户级别的Telegram策略（私聊/群聊策略和允许列表立场）。 在正确的配置范围内添加聊天目标（私聊/群聊）。 对于启用了主题的群聊，捕获chat_id和message_thread_id，并在需要时应用线程规则。 强制执行提及门控和发送者允许列表，如有需要。 重新加载/重启网关并使用真实的Telegram测试消息进行验证。 如果没有回复，按照顺序运行故障排除部分。

集成规则 1）使用正确的配置范围 始终保持策略和目标一致：全局Telegram设置定义默认值。 账户范围的设置定义每个机器人账户可以响应什么。 群聊或主题条目仅在活动账户策略允许时才有效。 如果策略是允许列表，请确保目标聊天在使用的机器人相同的账户范围内被明确允许列出。 2）默认情况下为群聊要求提及门控 对于群聊，除非用例需要环境回复，否则更喜欢requireMention：true。 这减少了意外触发和忙碌群聊中的交叉对话。 3）启用了主题的群聊需要线程感知 对于启用了主题的超级群聊： chat_id标识群聊。 message_thread_id标识主题线程。 如果行为是线程特定的，请配置主题级路由/策略，而不是假设群聊级配置足够。 4）Telegram群聊中的机器人权限 在将机器人添加到启用了主题的群聊时，授予所需的管理员权限以实现可靠的主题行为。 最低推荐权限： 管理主题 发送消息（和相关的基本消息权限） 没有主题管理能力，主题线程中的行为可能不一致。 5）多账户机器人 如果配置了多个Telegram机器人账户： 验证消息路由落在预期的账户上。 在账户范围的策略中为每个账户复制所需的允许列表条目。 避免假设全局群聊条目会自动授权所有账户。

ID发现（无密钥） 获取chat_id 使用以下方法之一： 在发送机器人可以观察到的消息后，使用Telegram getUpdates流程。 Telegram消息链接转换（/c//... => -100用于超级群聊）。 获取message_thread_id 对于启用了主题的群聊，从更新有效载荷或消息链接/线程元数据中提取主题/线程ID。

验证检查清单 在任何更改后，以此顺序验证： 机器人账户令牌解析并且账户处于活动状态。 目标聊天在正确的账户范围内存在。 策略（允许列表与全部）与预期行为匹配。 requireMention与测试消息格式匹配。 发送者由allowFrom规则（全局/账户/群聊/主题，如使用）许可。 网关重新加载/重启完成。 新的Telegram测试消息确认了端到端回复。

故障排除：“收到消息但无机器人回复” 严格按照以下顺序进行： 检查日志以获取跳过原因（不允许、缺少提及、策略不匹配）。 确认目标群聊在活动的Telegram账户下被允许列出。 确认发送者允许列表规则包括发送者在有效的策略层。 确认测试消息中满足提及要求。 对于主题群聊，验证主题/线程ID处理和主题权限。 检查Telegram API轮询冲突（409 getUpdates冲突），表明多个机器人实例正在轮询同一个令牌。 在重新加载/重启后重新测试，并仅检查新日志（避免过时的结论）。

安全默认值 私聊策略：除非明确需要开放接收，否则为允许列表。 群聊策略：允许列表+需要提及。 在最小的实际范围内缩小发送者允许列表。 更喜欢账户范围的群聊授权用于多机器人设置。 保持每个机器人令牌的一个活动轮询器/网钩路径，以防止更新冲突。

新机器的重用模式 在迁移或登记新主机时： 应用基线Telegram策略模板。 注册机器人账户（s）。 添加私聊/群聊目标，具有明确的账户范围。 应用提及和allowFrom约束。 使用一个私聊和一个群聊/主题测试进行验证。 捕获最终已知的良好配置片段以备将来重用。