Home Assistantmatrix.send_message动作完整指南向 Matrix 房间发送消息、图片与线程回复【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读matrix.send_message是 Home Assistant Matrix 集成提供的一项核心动作action用于向一个或多个 Matrix 房间发送文本消息并支持附带图片、HTML 格式渲染以及在线程中回复。本文以官方动作文档为主体结合仓库中的集成配置文档完整讲解该动作在 UI 与 YAML 两种场景下的用法、全部参数含义、与matrix.react动作配合构建事件驱动自动化以及登录认证与常见故障排查让你能够在通知、自动化与脚本中可靠地使用 Matrix 消息通道。动作概览它能做什么matrix.send_message属于matrix域官方描述为 Sends a message to one or more Matrix rooms。典型用途包括向指定房间发送通知消息附带一张或多张本地图片给出图片路径列表以纯文本或 HTML 子集格式发送消息通过thread_id将回复挂到某个父消息线程根消息之下。该动作与matrix.react向消息发送 emoji 反应互为姊妹动作二者常在聊天机器人场景中配合使用。它们都依赖 Matrix 集成先完成配置账号、homeserver、房间详情见 matrix 集成文档。注意matrix.send_message不支持 action targets。与多数动作不同你不能通过选择区域area、设备device、实体entity或标签label来指定目标房间必须直接填在Target字段中。在 UI 中配置该动作如果偏好可视化配置Home Assistant 会逐步引导完成整个动作的填写无需编写 YAML。操作步骤如下进入设置自动化与场景{% my automations %}。打开一个已有的自动化或脚本或选择创建自动化创建新自动化。若新建的是自动化在When何时部分添加一个触发器。脚本不需要触发器它们由其他逻辑调用时执行。在Then do然后执行部分选择Add action添加动作。搜索并选择Matrix: Send message。填写Message消息内容与Target目标房间可填一个或多个房间。可选地在Data下设置附加选项。点击Save保存。UI 中的选项说明选项说明必填Message要发送的消息内容。是Target接收消息的房间可多个。是Data消息的附加选项详见下文。否在 YAML 中使用在 YAML 中该动作引用名为matrix.send_message。以下是官方给出的完整示例action: matrix.send_message data: message: My cool message target: - #hasstest:matrix.org data: images: - /path/to/picture.jpg format: html thread_id: $-abcdeghij_klmnopqrstuvwxyz123这段配置的效果是向#hasstest:matrix.org房间发送一条附带图片的 HTML 格式消息并把这条消息作为线程回复挂到thread_id指定的父消息之下。YAML 参数表参数类型必填说明messagestring是要发送的消息内容。targetlist是接收消息的房间 ID 或别名列表例如#hasstest:matrix.org。datamap否消息的附加选项images要附带的图片路径列表、formattext或html默认为text、thread_id父消息 ID用于把回复挂在线程下。在 YAML 中使用data下的images、format、thread_id三个子键时注意它们与外层data的层级关系——外层data是动作参数容器内层data才是 Matrix 消息选项。前置条件Matrix 集成配置调用matrix.send_message前必须先启用 Matrix 集成。在configuration.yaml中加入# Example configuration.yaml entry matrix: homeserver: https://matrix.org username: my_matrix_user:matrix.org password: supersecurepassword rooms: - #hasstest:matrix.org commands: - word: my_command name: my_command集成级配置参数参数必填类型默认值说明username是string—Home Assistant 登录 Matrix 使用的完整 Matrix ID必须包含 homeserver 域名如my_matrix_bot:matrix.org。注意在 YAML 中有特殊含义必须用引号包裹。password是string—Matrix 账号密码仅在尚无有效 access token 时使用见下文身份认证。homeserver是string—homeserver 的完整 URL默认 matrix.org 则为https://matrix.org。verify_ssl否stringtrue是否校验 homeserver 的证书。rooms否list空机器人应加入并监听命令的房间列表可用内部 ID如!cURbafjkfsMDVwdRDQ:matrix.org或别名如#matrix:matrix.org。commands否map空机器人监听的命令列表触发后通过事件驱动自动化处理详见下文。其中commands的每个命令条目支持以下子键子键必填说明word否监听的命令词。例如填my_command机器人会处理所有以!my_command开头的消息。expression否监听的 Python 正则表达式机器人处理所有匹配该正则的消息。reaction否监听的表情符号反应机器人处理被该 emoji 反应的消息。name是命令名称作为触发事件matrix_command的name字段值。rooms否该命令生效的房间列表缺省时使用集成级rooms列表中每个房间也必须同时出现在集成级rooms中。警告为避免命令-回复死循环Matrix 集成必须使用独立的机器人账号不要用你日常与机器人对话的个人账号。身份认证密码与访问令牌集成会使用配置中的username和password登录。首次登录成功后homeserver 返回的 access token 会被保存到配置目录中、与configuration.yaml同级的.matrix.conf文件中该文件默认在全新安装时不存在属正常现象。每次重启时集成优先尝试已保存的 token只有当 homeserver 拒绝该 token 时才改用密码登录。由于.matrix.conf以点开头部分备份/复制工具会忽略它——备份、迁移或重建安装时请务必包含此文件以保持会话。不支持密码登录的 homeserver部分 homeserver例如启用 Matrix Authentication Service 且配合外部单点登录、关闭了密码登录的场景不允许密码登录。此时可按以下步骤改用自行创建的访问令牌重要access token 拥有该 Matrix 账号的完整访问权限。一旦泄露任何人可在 token 失效前以该账号身份读写消息。请像保管密码一样保管 token若怀疑泄露应在 homeserver 上结束该会话并重新签发 token。在 homeserver 上为机器人账号创建 access token使用 Matrix Authentication Service 的 homeserver管理员可用mas-cli manage issue-compatibility-token命令签发长期兼容令牌参数只取 Matrix ID 的本地部分如my_matrix_bottoken 只显示一次请立即复制。未启用 MAS 的 Synapse homeserver管理员可用 login as a user 管理 API默认返回的 token 不过期。在配置目录创建或编辑.matrix.conf每个 Matrix ID 对应一个条目{ my_matrix_bot:example.com: YOUR_ACCESS_TOKEN }若文件已存在只修改属于你 Matrix ID 的值其余保持不动并确保 Home Assistant 可读取该文件。保留配置中的password选项必填项但 token 有效期间不会使用它账号若没有密码可填任意文本。完全重启Home Assistant集成只在启动时读取.matrix.conf然后发送一条测试消息验证。事件数据用命令触发自动化当commands中配置的命令被触发时集成会抛出matrix_command事件事件的name字段携带命令名称word 命令data字段是命令参数列表命令词之后的内容按空格拆分expression 命令data字段是匹配正则的 group dictionary。事件还包含room、event_id、thread_parent等字段见下文线程回复。这为matrix.send_message提供了典型的调用场景收到matrix_command事件后用notify.matrix_notify或matrix.send_message回应用户。结合 notify 平台通知、HTML 与图片集成还提供matrix通知平台可向 Matrix 房间直接聊天或群聊均可投递通知。启用方式是在配置好集成后于configuration.yaml中添加notify: - name: NOTIFIER_NAME platform: matrix default_room: ROOM_ID_OR_ALIAS参数必填默认值说明name否notify允许创建多个通知器绑定到notify.NOTIFIER_NAME动作。default_room是—未指定其他目标时所有消息发送到的房间。目标房间必须预先创建。房间 ID 可在房间设置对话框中获取默认形如!randomid:homeserver.tld也可使用#roomname:homeserver.tld形式的别名。由于!和#在 YAML 中是特殊字符房间 ID 或别名必须用引号包裹。根据房间策略通知账号可能需要先被邀请进房间。消息格式Matrix 支持发送 受限 HTML 子集 的消息。在通知的data中指定格式即可支持text默认与htmlactions: - action: notify.matrix_notify data: message: - h1Hello, world!/h1 data: format: html附带图片在通知data中给出图片路径列表即可发送图片actions: - action: notify.matrix_notify data: message: Test with images data: images: - /path/to/picture.jpg重要若图片位于外部文件夹需要在configuration.yaml的homeassistant配置中把该目录加入允许清单homeassistant: allowlist_external_dirs: - /tmp详见 homeassistant 集成的 allowlist_external_dirs。在线程中回复matrix_command事件包含以下与线程相关的字段event_id收到消息的消息 IDthread_parent消息所在线程的根消息 ID。若消息本身不在线程中thread_parent与event_id相同若在线程中则为线程根消息的 ID。要在线程内回复只需在发送时把根消息 ID 传给data.thread_idaction: notify.matrix_notify data: message: Reply message goes here data: thread_id: {{ trigger.event.data.thread_parent }}matrix.send_message动作的data.thread_id参数用法与此完全一致。综合示例聊天机器人send_message react以下来自 matrix 集成文档 的完整配置演示了matrix.send_message所在生态的典型全貌——同时配置集成、notify 平台与三条自动化# The Matrix integration matrix: homeserver: https://matrix.org username: my_matrix_user:matrix.org password: supersecurepassword rooms: - #hasstest:matrix.org - #someothertest:matrix.org commands: - word: testword name: testword rooms: - #someothertest:matrix.org - expression: My name is (?Pname.*) name: introduction - reaction: name: thumbsup notify: - name: matrix_notify platform: matrix default_room: #hasstest:matrix.org automation: - alias: Respond to !testword triggers: - trigger: event event_type: matrix_command event_data: command: testword actions: - action: notify.matrix_notify data: message: It looks like you wrote !testword - alias: Respond to an introduction triggers: - trigger: event event_type: matrix_command event_data: command: introduction actions: - action: notify.matrix_notify data: message: Hello {{trigger.event.data.args[name]}} - alias: Respond to a reaction in a thread triggers: - trigger: event event_type: matrix_command event_data: command: thumbsup actions: - action: notify.matrix_notify data: message: I saw that {{trigger.event.data.args[reaction]}} -- glad you appreciated this! data: thread_id: {{trigger.event.data.thread_parent}} - alias: React to a command triggers: - trigger: event event_type: matrix_command event_data: command: testword actions: - action: matrix.react data: reaction: ✅ room: {{trigger.event.data.room}} message_id: {{trigger.event.data.event_id}}该配置的行为仅在#someothertest:matrix.org房间监听!testword匹配后向#hasstest:matrix.org回复 It looks like you wrote !testword并对原消息加上 ✅ 反应在两个房间监听匹配My name is 任意字符串的消息回复 Hello 字符串 到#hasstest:matrix.org在两个房间监听被 反应的消息并在线程中回复 I saw that -- glad you appreciated this!。其中回复动作使用的notify.matrix_notify通知平台与matrix.send_message动作共享同一套消息能力message、format、images、thread_id。若需要精确指定发送房间而非依赖default_room直接用matrix.send_message动作并填target即可。故障排查消息停止发送症状Login failed, both token and username/password are invalid消息不再投递且在设置系统日志中出现Login failed, both token and username/password are invalid。原因homeserver 拒绝了已保存的 access token同时密码登录也失败。token 失效常见于以下情况在 homeserver 上结束了该账号的会话或设备例如在所有设备上登出.matrix.conf文件被删除homeserver 自动结束了长期不活跃的会话。正常情况下集成会用密码重新登录但对于不允许密码登录的 homeserver集成将保持登出状态直到你提供新的 access token。解决办法若 homeserver 允许密码登录检查configuration.yaml中的username与password然后重启 Home Assistant若不允许密码登录按上文不支持密码登录的 homeserver一节创建新 token 并写入.matrix.conf。相关资源matrix.react 动作文档向 Matrix 房间中的消息发送反应不限于 emoji可以是任意字符串emoji 是典型用法matrix 集成文档集成级配置、认证、事件与通知平台的完整参考文档站点中 homeassistant 集成的 allowlist_external_dirs 说明外部文件目录白名单配置。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考