Home Assistant Telegram bot 集成leave_chat 动作完整解析——让机器人自动退出群组与频道【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本篇技术指南聚焦 Home Assistanttelegram_bot集成的leave_chat动作如何在自动化或脚本中让 Telegram 机器人主动退出指定的群组或频道。读完本文你将掌握该动作的 UI 与 YAML 两种配置方式、三种目标定位机制Notify 实体 / 配置条目 ID 聊天 ID / 默认首个聊天的全部参数细节并能将其嵌入实际场景的自动化流程中。leave_chat的官方定义见 动作文档移除 Telegram 机器人所在的会话Remove a Telegram bot from a chat即让机器人离开一个群组group或频道channel。它与发送、编辑、删除消息等消息类动作不同操作对象是机器人与会话的关系本身属于会话管理类操作。适用前提Telegram bot 集成与聊天白名单leave_chat动作依附于 Telegram bot 集成 运行理解以下前提有助于正确使用该动作平台选择该集成提供三种平台——Broadcast仅发送消息、Polling长轮询接收消息超时 10 秒与Webhooks要求实例暴露到公网。leave_chat这类管理动作依赖机器人与 Telegram 的正常通信Broadcast平台同样可以发起它本质上是机器人主动调用 Telegram API但接收类事件不可用。聊天 ID 白名单Allowlist集成要求每个可收发消息的聊天 ID 必须通过配置条目的子条目Subentries预先加入白名单——在设置 设备与服务中选择 Telegram bot 集成点击三点菜单选择Add allowed chat ID并填入 Chat ID。leave_chat的Chat ID参数描述明确写着要退出的**已预授权pre-authorized**聊天 ID也就是说该聊天必须在白名单内机器人才能对其执行此动作。Chat ID 的获取方式按官方集成文档可向 Telegram 的id_bot发送任意消息从回复中读取 ID 字段值用户 ID 为正数群组/频道 ID 为负数。在用户界面中使用 leave_chat文档给出的 UI 操作路径在 动作页面 中定义为 6 步向导如下进入设置 自动化与场景Settings Automations scenes。打开已有的自动化或脚本或选择Create automationCreate new automation。如果是新建自动化需要在When区域添加触发器脚本不需要触发器它们在被其他流程调用时运行。在Then do区域选择Add action。在搜索框中搜索并选择Telegram bot: Leave chat。选择要退出的会话然后选择Save。目标定位机制该动作不使用标准 target这是leave_chat最值得注意的设计点它不使用 Home Assistant 的标准 target 机制而是通过以下三种方式之一指定要退出的会话方式说明适用场景Notify target实体选择一个指向机器人 目标会话的 Telegram notify 实体会话已加入白名单、notify 实体已自动生成时最方便Config entry IDChat ID显式提供机器人配置条目 ID 与聊天 ID配置了多个机器人时必须指定也适合以模板变量传入动态 Chat ID都不提供默认系统默认使用该机器人允许的第一个聊天仅适用于只有一个机器人的简单部署这种设计的含义是当实例中只有一个 bot 配置条目、且只白名单了一个聊天时可以只写动作名而省略全部参数一旦存在多 bot 或多白名单聊天显式定位就变为必需否则默认规则可能退错群。UI 中的选项Options in the UI选项说明Notify target一个或多个指向待退出机器人 会话的 Telegram notify 实体Config entry ID指定使用哪个 Telegram bot配置了多个 bot 时必填Chat ID要退出的已预授权聊天 ID缺省时默认为该 bot 允许的第一个聊天该页面使用的 UI 选项区块由站点插件 options_ui 渲染器 实现它以config-vars basic的 DOM 结构输出每项的标签与描述并对标注了required的字段显示 Required / Optional 徽标——这解释了为何 UI 选项中只有 Config entry ID 在文档语义上被强调多 bot 时必填。在 YAML 中使用 leave_chat在 YAML 中该动作的调用名为telegram_bot.leave_chat。文档给出的最小可运行示例action: | action: telegram_bot.leave_chat data: chat_id: 123456789放入自动化中的完整形态actions序列写法actions: - action: telegram_bot.leave_chat data: chat_id: 123456789 # 注意群组/频道的真实 ID 通常为负数此处为占位示例YAML 中的选项Options in YAML字段类型必填说明entity_idstring或list否一个或多个指向待退出机器人 会话的 Telegram notify 实体config_entry_idstring否指定使用哪个 Telegram bot配置多个 bot 时必填chat_idinteger否要退出的已预授权聊天 ID缺省为 bot 允许的第一个聊天注意 UI 与 YAML 的参数名差异UI 中的Notify target对应 YAML 的entity_id字段Config entry ID对应config_entry_idChat ID对应chat_id。多 bot 场景下推荐显式定位的写法actions: - action: telegram_bot.leave_chat data: config_entry_id: 6f5d... # 目标 bot 的配置条目 ID chat_id: -1001234567890 # 要退出的群组群组 ID 为负数结合事件流的实战用法leave_chat很少孤立使用其典型场景是响应式管理机器人在某个群组完成阶段性任务后自动退群避免长期占用群成员列表。从 Telegram bot 集成文档 的事件机制看机器人收发的每条消息都会写入event.bot_update_event事件实体含chat_id、command、text等属性因此可以构建用户发送指令 → 机器人确认 → 退出当前会话的闭环alias: 指令到达后让机器人退出当前群 triggers: - trigger: state entity_id: - event.bot_update_event # 替换为你的 Telegram bot 事件实体 conditions: - condition: state entity_id: event.bot_update_event attribute: event_type state: telegram_command - condition: state entity_id: event.bot_update_event attribute: command state: /leave actions: - action: telegram_bot.send_message data: message: 任务完成我将退出本群。 chat_id: {{ trigger.to_state.attributes.chat_id }} - action: telegram_bot.leave_chat data: chat_id: {{ trigger.to_state.attributes.chat_id }}这个示例复用了集成文档中事件属性自动化telegram_command事件 command属性判断的标准模式再衔接leave_chatchat_id直接取自触发事件的属性无需硬编码。验证与排查不写 YAML 直接测试打开设置 工具 操作ActionsSettings Tools Actions搜索leave_chat填入字段后选择Perform action即可在实际会话上验证效果——这是文档给出的官方调试入口也是验证目标定位方式是否正确notify 实体是否真的指向预期群组的最快手段。退出失败的常见原因chat_id未加入该 bot 的白名单子条目集成文档明确要求必须先 allowlist 才能对该聊天操作多 bot 部署下缺少config_entry_id默认规则把动作发给了另一个 bot误把用户名当作 Chat ID——Chat ID 是纯数字用户为正、群/频道为负需按集成文档中向id_bot发消息的方法获取。与其他动作的边界leave_chat是会话级操作如果只想让机器人闭嘴而非退群应使用 send_chat_action 或 send_message 等消息类动作或 delete_message 清理已发消息。参考文件动作原始文档source/_actions/telegram_bot.leave_chat.markdownTelegram bot 集成总览平台、白名单、事件、示例自动化source/_integrations/telegram_bot.markdown该页面渲染所用的 UI 选项块插件plugins/options_ui.rb同域相关动作telegram_bot.send_message、telegram_bot.delete_message、telegram_bot.send_chat_action【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考