企业官网建设流程全解析

Home Assistant telegram_bot.send_message 动作详解：从自动化与脚本发送 Telegram 文本消息

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

本文基于 Home Assistant 官方用户文档站（home-assistant.io）中的动作参考页 telegram_bot.send_message，完整解析telegram_bot.send_message这个自动化动作：它如何通过已配置的 Telegram bot 向一个或多个聊天发送文本消息，支持标题、Markdown/HTML 排版、自定义键盘与行内按钮，并能通过response_variable拿到chat_id与message_id用于后续编辑或删除消息。读完后你可以直接照抄本文的 YAML 配置，在自己的 Home Assistant 中跑通“发送—跟踪—编辑—删除”的完整消息链路。

动作概览

telegram_bot.send_message属于telegram_bot域（domain），其描述为“Sends a text message through a Telegram bot to one or more chats.”（通过 Telegram bot 向一个或多个聊天发送文本消息）。该动作的使用前提是 Home Assistant 中已配置 Telegram bot 集成：

• 该集成提供三种平台（platform）：只发不收的Broadcast、长轮询收发消息的Polling（10 秒超时）、以及需要公网可达的Webhooks；
• 发送目标必须是已加入白名单（allowlist）的 chat ID：用户 chat ID 为正数，群组 chat ID 为负数。白名单通过在集成条目的子条目（subentry）中Add allowed chat ID添加；
• 每个已配置的 chat ID 都会生成一个 notify 实体（如notify.telegram_bot_chat），本动作正是通过这些实体或直接指定config_entry_id+chat_id来定位发送目标。

在 UI 中使用该动作

Home Assistant 允许完全通过可视化界面完成配置，无需编写 YAML：

1. 打开Settings > Automations & scenes（设置 > 自动化与场景）。
2. 打开一个现有自动化或脚本，或选择Create automation > Create new automation。
3. 如果是新建自动化，先在When部分添加触发器；脚本不需要触发器，它由其他实体调用时执行。
4. 在Then do部分选择Add action（添加动作）。
5. 在搜索框中搜索并选择Telegram bot: Send message。
6. 填写Message（消息正文，必填），可选填写Title（标题）和其他选项。
7. 选择消息发送到哪里（见下文的三种定向方式）。
8. 在Response variable字段中填写一个变量名（如garage_message），用于保存本次动作的响应数据。
9. 选择Save保存。

三种定向方式（本动作不使用标准 target）

该动作不采用标准 target 语法，而是通过以下三种方式之一指定发送位置：

• 选择一个或多个Notify target实体。每个 notify 实体已经指向某个特定 Telegram bot 和 chat；
• 提供Config entry ID（机器人配置条目）并配合一个或多个Chat ID；
• 如果只配置了一个 bot 且前两者都未提供，则默认发送到该 bot 的第一个允许聊天（first allowed chat）。

UI 选项说明

在 YAML 中使用该动作

在 YAML 中，动作名写作telegram_bot.send_message。一个最小可用示例（车库门长时间开启的提醒场景）：

action: | action: telegram_bot.send_message data: title: Your garage door friend message: The garage door has been open for 10 minutes. response_variable: garage_message

response_variable: garage_message会把发送结果写入变量garage_message，后续步骤可直接引用（见响应数据一节）。

YAML 选项完整参考

实战 YAML 示例

以下示例取自 Telegram bot 集成文档 的官方样例，可直接复制到自动化的actions段落。

1. 发送带 Markdown 排版的消息

actions: - action: telegram_bot.send_message data: title: Example Message message: 'Message with *BOLD*, _ITALIC_ and `MONOSPACE` Text'

2. 带 message_tag 的消息（配合telegram_sent事件识别）

actions: - action: telegram_bot.send_message data: title: Example Message message: "Message with tag" message_tag: "example_tag"

发送后触发的telegram_sent事件会带上该标签，便于在日志或后续自动化中定位这条具体消息。

3. 发送带 HTML 链接且禁用预览的消息

actions: - action: telegram_bot.send_message data: message: >- <a href="https://www.home-assistant.io/">HA site</a> parse_mode: html disable_web_page_preview: true

4. 发送到群组中的指定话题（forum supergroup）

actions: - action: telegram_bot.send_message data: message: "Message to a topic" message_thread_id: 123

5. 发送后延迟 5 秒自动改写（利用 response_variable）

这是send_message与 edit_message 动作协作的典型模式：发送结果存入变量response，随后用response.chats[0].chat_id/message_id定位刚发出的消息：

actions: - action: telegram_bot.send_message data: message: testing response_variable: response - delay: seconds: 5 - action: telegram_bot.edit_message data: message: done testing chat_id: "{{ response.chats[0].chat_id }}" message_id: "{{ response.chats[0].message_id }}"

6. 发送后遍历多个聊天批量删除（利用 chats 列表）

由于本动作支持向多个聊天发送，chats是一个列表，可用repeat.for_each逐条删除（delete_message 动作）：

alias: telegram send message and delete actions: - action: telegram_bot.send_message data: message: testing response_variable: response - delay: seconds: 5 - repeat: sequence: - action: telegram_bot.delete_message data: message_id: "{{ repeat.item.message_id }}" chat_id: "{{ repeat.item.chat_id }}" for_each: "{{ response.chats }}"

响应数据（response_variable）

消息成功发送后，动作返回一个chats列表，列表中的每一项对应一条已送达的消息：

• chat_id：消息发送到的聊天；
• message_id：已发送消息的 ID，后续编辑或删除消息时使用；
• entity_id：实际发送该消息的 notify 实体。

响应示例：

chats: - chat_id: 1234567890 message_id: 100 entity_id: notify.telegram_bot_chat

这个message_id同时会被写入集成提供的telegram_sent事件属性中，因此你还有第二条获取路径：监听事件实体（如event.bot_update_event）的状态变更，从trigger.to_state.attributes中读取chat_id与message_id并存入input_number等实体，供其他动作使用（该模式的完整自动化样例见 Telegram bot 集成文档 的 “Sample automation to receive chat_id and message_id identifiers of sent messages” 一节）。

与相关能力、事件的衔接

从官方文档结构看，send_message是整个 Telegram bot 动作族的核心，常与以下动作、事件组合使用（各动作文档均位于本仓库source/_actions/目录）：

• 接收方向：集成提供事件实体，telegram_text、telegram_command、telegram_callback、telegram_attachment等事件用于在自动化中响应用户输入；行内键盘按钮的回调通过telegram_callback事件捕获，再用 telegram_bot.answer_callback_query 应答。
• 消息生命周期：发出后可用 telegram_bot.edit_message、telegram_bot.delete_message、telegram_bot.edit_replymarkup 修改内容或按钮；多步任务中可用 telegram_bot.send_message_draft 先发送草稿占位、逐步刷新进度。
• 通用 notify 通道：若只把 bot 当作普通通知器，也可用通用的 notify.send_message 动作指向notify.telegram_bot_chat实体；但send_message专有参数（parse_mode、inline_keyboard、message_tag等）只有在telegram_bot.send_message上才能完整使用。

常见错误与排查

根据 Telegram bot 集成文档 的 Troubleshooting 章节，使用本动作时最常见的报错是markdownv2模式下的Error sending message: Can't parse entities——当message中包含用户输入且语法不是合法 Markdown 时，Telegram 会拒绝解析。解决方式有三种：

• 改用plain_text模式（通过集成选项或动作的parse_mode参数指定）；
• 对message中的特殊字符加反斜杠转义；
• 按 Telegram 的 formatting options 规范整理消息文本。

另外一个前提性限制：Webhooks 平台要求 Home Assistant 公网可达且证书必须由公开 CA 签发，不支持自签名证书；如果所有非telegram_sent事件都收不到更新，官方建议先临时切到Polling平台验证连通性，再排查防火墙与 webhook URL 可达性。

小结

telegram_bot.send_message的价值在于“一条动作打通收发闭环”：发送侧提供标题、四种 parse mode、自定义/行内键盘、静默、回复与话题线程等完整控制面；返回侧通过response_variable的chats列表交出chat_id和message_id，让你能可靠地把“发出去的消息”与后续的编辑、删除、回调应答动作串联起来。配置时牢记三件事：chat ID 必须先在集成中白名单化、多 bot 时必须显式给config_entry_id、含用户输入的消息优先考虑plain_text或转义处理。

参考文档（本仓库内路径）

• source/_actions/telegram_bot.send_message.markdown（本文主体来源）
• source/_integrations/telegram_bot.markdown（集成平台、白名单、事件与完整示例）
• source/_actions/telegram_bot.edit_message.markdown
• source/_actions/telegram_bot.delete_message.markdown
• source/_actions/telegram_bot.answer_callback_query.markdown
• source/_actions/telegram_bot.send_message_draft.markdown
• source/_actions/notify.send_message.markdown

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io