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

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、长轮询收发消息的Polling10 秒超时、以及需要公网可达的Webhooks发送目标必须是已加入白名单allowlist的 chat ID用户 chat ID 为正数群组 chat ID 为负数。白名单通过在集成条目的子条目subentry中Add allowed chat ID添加每个已配置的 chat ID 都会生成一个 notify 实体如notify.telegram_bot_chat本动作正是通过这些实体或直接指定config_entry_idchat_id来定位发送目标。在 UI 中使用该动作Home Assistant 允许完全通过可视化界面完成配置无需编写 YAML打开Settings Automations scenes设置 自动化与场景。打开一个现有自动化或脚本或选择Create automation Create new automation。如果是新建自动化先在When部分添加触发器脚本不需要触发器它由其他实体调用时执行。在Then do部分选择Add action添加动作。在搜索框中搜索并选择Telegram bot: Send message。填写Message消息正文必填可选填写Title标题和其他选项。选择消息发送到哪里见下文的三种定向方式。在Response variable字段中填写一个变量名如garage_message用于保存本次动作的响应数据。选择Save保存。三种定向方式本动作不使用标准 target该动作不采用标准 target 语法而是通过以下三种方式之一指定发送位置选择一个或多个Notify target实体。每个 notify 实体已经指向某个特定 Telegram bot 和 chat提供Config entry ID机器人配置条目并配合一个或多个Chat ID如果只配置了一个 bot 且前两者都未提供则默认发送到该 bot 的第一个允许聊天first allowed chat。UI 选项说明选项说明Notify target一个或多个 Telegram notify 实体用于指定发送对象。每个实体指向特定 bot 和 chatTitle可选标题显示在消息正文上方Message消息正文必填Parse mode消息文本的排版解析方式取值为html、markdown、markdownv2或plain_textDisable notification静默发送接收方会收到无提示音的通知Disable web page preview禁用消息中链接的网页预览卡片Keyboard以行rows为单位定义自定义键盘命令传入空列表可清除之前设置的键盘Inline keyboard消息下方的行内按钮行每个按钮绑定回调数据callback data或外部 URLMessage tag消息发送后附加到telegram_sent事件上的标签便于事后识别这条消息Reply to message ID给定某条消息的 ID将本消息标记为对它的回复Message thread ID在论坛型超级群组forum supergroup中把消息发送到指定话题/线程Config entry ID使用哪个 Telegram bot配置了多个 bot 时必填Chat ID一个或多个已授权 chat ID默认使用 bot 的第一个允许聊天在 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_messageresponse_variable: garage_message会把发送结果写入变量garage_message后续步骤可直接引用见响应数据一节。YAML 选项完整参考字段类型必填默认值说明entity_idstring, list否-一个或多个 Telegram notify 实体每个实体指向特定 bot 和 chattitlestring否-可选标题显示在消息正文上方messagestring是-消息正文parse_modestring否-排版解析方式html、markdown、markdownv2或plain_text不指定时使用集成选项中的默认 Parse modedisable_notificationboolean否false静默发送接收方收到无提示音的通知disable_web_page_previewboolean否false禁用消息中链接的网页预览keyboardlist否-自定义键盘的命令行传空列表可清除之前设置的键盘inline_keyboardlist否-行内按钮行每个按钮绑定回调数据或外部 URLmessage_tagstring否-发送后附加到telegram_sent事件的标签便于事后识别reply_to_message_idinteger否-给定消息 ID将本消息标记为对它的回复message_thread_idinteger否-将消息发送到论坛超级群组中的指定话题/线程config_entry_idstring否-使用哪个 Telegram bot多个 bot 时必填chat_idinteger, list否-一个或多个已授权 chat ID默认 bot 的第一个允许聊天实战 YAML 示例以下示例取自 Telegram bot 集成文档 的官方样例可直接复制到自动化的actions段落。1. 发送带 Markdown 排版的消息actions: - action: telegram_bot.send_message data: title: Example Message message: Message with *BOLD*, _ITALIC_ and MONOSPACE Text2. 带 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 hrefhttps://www.home-assistant.io/HA site/a parse_mode: html disable_web_page_preview: true4. 发送到群组中的指定话题forum supergroupactions: - action: telegram_bot.send_message data: message: Message to a topic message_thread_id: 1235. 发送后延迟 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: Cant 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.markdownsource/_actions/telegram_bot.delete_message.markdownsource/_actions/telegram_bot.answer_callback_query.markdownsource/_actions/telegram_bot.send_message_draft.markdownsource/_actions/notify.send_message.markdown【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考