Home Assistant Telegram Bot send_chat_action 动作详解在 Telegram 聊天中显示正在输入状态【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.iotelegram_bot.send_chat_action是 Home Assistant Telegram bot 集成提供的一个服务动作用于在 Telegram 聊天窗口中展示诸如正在输入typing之类的状态提示。当机器人的回复需要一段时间才能生成时先发送该状态可以让对方知道消息马上就来Telegram 会在 5 秒后或回复实际到达时自动清除该状态。本文完整覆盖该动作的 UI 配置步骤、YAML 写法与全部参数选项并结合 Telegram bot 集成的整体架构说明其定位与适用场景。动作的行为与适用场景该动作对应 Telegram Bot API 中的 chat action 机制调用后目标聊天窗口会短暂显示机器人正在输入、正在上传照片等占位状态而不是真正发送一条消息。它不占用消息列表也不触发消息事件本质是一种交互反馈信号。典型使用场景包括自动化执行耗时任务如生成报表、等待外部 API前先向用户提示正在处理中多步骤脚本在两个消息之间的衔接处提示机器人仍在工作中避免用户误以为流程卡死。需要注意的是状态展示的持续时间是有限的根据 动作文档 的说明Telegram 会在5 秒后或回复消息到达时清除该状态。如果需要更长时间的进行中反馈可以配合集成提供的send_message_draft草稿消息动作分阶段更新进展参见 Telegram bot 集成文档 中的Multi-step automation that reports progress using draft messages示例。通过用户界面使用如果你偏好可视化地搭建自动化和脚本Home Assistant 界面会引导你逐步完成配置。整体流程为进入SettingsAutomations scenes打开一个已有的自动化或脚本或选择Create automationCreate new automation若新建自动化先在When区域添加触发条件Triggers。脚本不需要触发条件它在被其他流程调用时运行在Then do区域点击Add action在搜索框中搜索并选择Telegram bot: Send chat action选择要展示的Chat action状态选择发送目标然后点击Save。界面操作不需要任何 YAML 知识保存后该动作会写入自动化/脚本的actions序列中与直接手写 YAML 的效果完全一致。发送目标的三种确定方式该动作不使用标准的 target 机制而是通过以下三种方式之一决定发送位置选择一到多个Notify target实体。每个 notify 实体在集成配置时已经绑定了一个特定的 Telegram bot 和一个聊天提供Config entry ID同时给出一到多个Chat ID如果你只配置了一个 bot且以上两者都不提供则默认发送到该 bot 的第一个允许聊天first allowed chat。这里的允许聊天来自 Telegram bot 集成的聊天 ID 白名单机制聊天 ID 需要在集成的子条目Subentries中预先 allowlist 之后机器人才有权向该聊天发送内容详见 Telegram bot 集成文档的 Allowlisting 章节。界面中的选项选项说明Notify target一个或多个 Telegram notify 实体用于接收该 chat action。每个实体指向特定的 bot 与聊天Chat action要展示的状态。取值为typing、upload_photo、record_video、upload_video、record_voice、upload_voice、upload_document、choose_sticker、find_location、record_video_note、upload_video_note之一Message thread ID将 chat action 发送到论坛型超级群forum supergroup中特定的话题/线程Config entry ID指定使用哪个 Telegram bot。配置了多个 bot 时必填Chat ID一个或多个已授权allowlisted的聊天 ID。默认为 bot 的第一个允许聊天通过 YAML 使用在 YAML 中该动作的完整名称为telegram_bot.send_chat_action。最小可运行示例如下继承自动作文档action: | action: telegram_bot.send_chat_action data: chat_action: typing将其放入自动化或脚本的actions序列中即可。下面给出一个更完整的实战示例在机器人回复延迟较大的自动化开头先提示正在输入再执行耗时步骤最后发送结果消息目标通过 notify 实体指定actions: - action: telegram_bot.send_chat_action data: chat_action: typing target: entity_id: notify.telegram_bot_chat # 耗时操作... - action: telegram_bot.send_message data: message: 处理完成 target: entity_id: notify.telegram_bot_chatYAML 中的选项字段类型必填说明entity_idstring / list否一个或多个 Telegram notify 实体用于接收该 chat action。每个实体指向特定的 bot 与聊天chat_actionstring否要展示的状态typing、upload_photo、record_video、upload_video、record_voice、upload_voice、upload_document、choose_sticker、find_location、record_video_note、upload_video_notemessage_thread_idinteger否将 chat action 发送到论坛型超级群中特定的话题/线程config_entry_idstring否指定使用哪个 Telegram bot。配置了多个 bot 时必填chat_idinteger / list否一个或多个已授权的聊天 ID。默认为 bot 的第一个允许聊天注意 YAML 与界面的字段对应关系界面中的Notify target对应 YAML 的entity_id字段界面中的Chat ID复数概念对应 YAML 的chat_id字段两者均可传入列表以同时覆盖多个目标。在集成生态中的位置从 Telegram bot 集成文档 的 front matter 可知该集成的ha_domain为telegram_bot属于 Cloud Push 类型的服务集成ha_integration_type: service提供notify、event、diagnostics三类平台并支持配置流config flow。集成按Broadcast、Polling、Webhooks三种平台模式工作分别对应仅发送、长轮询收发和Webhook 推送三种网络拓扑。send_chat_action作为其中的一个发送类动作不依赖接收能力因此在三种平台模式下均可使用。同一 domain 下还存在一系列配套发送动作send_chat_action常与它们组合使用例如send_message发送文本消息是 chat action 之后最常见的正式回复动作send_message_draft发送/更新草稿消息适合长时间任务的分阶段进展汇报因为 chat action 只有 5 秒可见窗口send_photo、send_document发送文件类消息可与upload_photo、upload_document等状态搭配提示edit_message、delete_message对已发送消息做后续操作。验证动作是否生效无需编写 YAML 即可快速验证打开SettingsToolsActionsDeveloper Tools 中的 Actions 页面搜索telegram_bot.send_chat_action填入chat_action等字段后点击Perform action即可在实际的 Telegram 聊天实体上观察效果。验证时请确认目标聊天 ID 已加入集成的 allowlist未授权的聊天不会收到任何内容配置了多个 bot 时务必提供config_entry_id否则可能路由到错误的 bot状态提示是瞬时的约 5 秒验证时应在点击执行后立即查看聊天窗口。参考本动作的权威文档source/_actions/telegram_bot.send_chat_action.markdown所属集成文档source/_integrations/telegram_bot.markdown站点侧渲染选项表格的 Liquid 标签实现plugins/options_ui.rb、plugins/options_yaml.rb【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考