Home Assistant 中使用 ntfy.publish 动作发送富文本推送通知的完整指南【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本文以 Home Assistant 文档仓库中的 ntfy.publish 动作文档 为核心系统讲解如何通过ntfy.publish动作向 ntfy topic 发布通知涵盖 UI 可视化配置与 YAML 两种方式、优先级 / 标签 / 附件 / 延迟投递 / 动作按钮等全部可选参数并结合ntfy.clear标记已读与ntfy.delete删除两个关联动作给出从门铃抓拍到死循环开关dead mans switch的完整自动化示例。读完本文你将掌握在 Home Assistant 自动化与脚本中发送带标题、Markdown、图片附件、交互按钮的高质量 ntfy 通知并能通过 sequence ID 对已发通知做更新、清除与删除。ntfy.publish 动作是什么ntfy是一个基于 HTTP 的简单 pub-sub发布/订阅推送通知服务可以把通知发送到手机或桌面端。Home Assistant 的 ntfy 集成参见 ntfy 集成文档于 2025.5 版本引入允许你向 ntfy.sh 官方服务或自建 ntfy 实例发布推送通知并且具备 event事件、notify通知、sensor用量统计传感器、update自托管实例版本更新等平台能力质量等级为 platinum。Publish notificationntfy.publish动作即把一条通知消息发布到某个 ntfy topic 的动作。它发布于 Home Assistant 2025.10 版本。与基础版notify.send_message不同它充分发挥了 ntfy 服务的全部能力你可以自定义消息的优先级、链接、附件、标签、表情符号以及点击通知后的跳转行为。从 2025.10 版本发布说明 可以看到该版本为 ntfy 集成带来了重大升级——支持携带标签、图标、URL 和附件发送更丰富、更可定制的通知并新增了事件平台用于订阅 topic 并在收到消息时触发自动化。在 Home Assistant 的自动化和脚本中通知类动作的目标target通常是集成配置好的 notify 实体形如notify.mytopic。每个配置的 topic 都会生成一个设备及对应的 notify 实体。在 UI 中添加发布通知动作在自动化或脚本中发送通知操作步骤如下进入设置 自动化与场景Automations scenes。打开一个已有的自动化或脚本或选择创建自动化 创建新自动化。如果是新自动化在触发条件When部分添加触发器脚本不需要触发器它们在被其他对象调用时才运行。在执行Then do部分选择添加动作Add action。在搜索框中搜索并选择ntfy: Publish notification。在目标Targets下选择要通知的 topic详见下文动作的目标。可选自定义消息优先级、加入表情符号或添加 URL、附件、动作按钮等交互元素。选择保存Save。动作的目标Targets该动作必须有目标。目标即动作的作用对象可以是单个实体、设备、区域、楼层或标签Home Assistant 会对其背后所有匹配的 notify 实体执行动作详见 targets.md 模板实体Entity某个具体的 notify 实体例如notify.living_room。设备Device隶属于某设备的所有 notify 实体。区域Area某个房间或区域内的所有 notify 实体。楼层Floor某楼层上的所有 notify 实体。标签Label共享某个标签的所有 notify 实体。同一动作还可以混合选择不同类型的目标例如同时添加一个具体实体和一个区域让动作同时对两者生效。UI 中的可选参数UI 中各选项说明如下所有参数均为可选选项说明标题Title通知消息的标题。消息Message通知正文。未提供时默认为字符串triggered。使用 Markdown 格式Format as Markdown为消息正文启用 Markdown 格式化语法参见 Markdown 指南。标签/表情符号Tags/Emojis为通知添加标签或表情符号。使用smile这类短代码的表情会显示在通知标题或正文中其余标签显示在通知内容下方。消息优先级Message priority所有消息都有优先级它决定手机通知的紧迫程度取决于配置的振动模式、通知铃声以及通知栏/弹窗中的可见性。点击 URLClick URL点击通知时打开的 URL。延迟投递Delay delivery设置消息投递延迟最短 10 秒最长 3 天。附件 URLAttachment URL通过 URL 附加图片或其他文件。附加本地文件Attach local file从本地文件、相机或图片媒体源上传附件。选择相机实体时会捕获当前画面快照并附加到通知中。附件文件名Attachment filename指定附件的自定义文件名含扩展名例如snapshot.jpg。未提供时默认文件名是attachment例如attachment.jpg。转发到邮箱Forward to email指定将通知转发到的邮箱地址例如mailexample.com。电话呼叫Phone call要拨打的电话号码用于通过文本转语音TTS朗读消息。需要 ntfy Pro 及事先完成电话号码验证。图标 URLIcon URL在通知文本旁显示的图标仅支持 JPEG 和 PNG 图片。动作按钮Action buttons最多三个动作按钮显示在通知下方点击/轻触即执行。可选打开网站/应用、发送 Android 广播、发送 HTTP 请求或复制到剪贴板。序列 IDSequence ID输入消息或序列 ID 来更新已有通知或指定一个序列 ID 供之后更新、清除标记已读并关闭或删除通知时引用。注意所有参数都是可选的。如果message留空通知将使用默认文本triggered如果未指定priority则使用默认优先级 3。提示完整的表情短代码支持列表可查阅 ntfy 的 emoji 参考文档。在 YAML 中使用 ntfy.publish在 YAML 中该动作写作ntfy.publish。最基本的示例如下action: ntfy.publish target: entity_id: notify.mytopic这会向 topicmytopic发送一条内容为triggered的通知。YAML 中的可选参数YAML 有时还提供 UI 中不可用的额外选项适合更复杂的用例。完整参数如下参数类型必填默认值说明titlestring否—通知消息的标题。messagestring否triggered通知正文。markdownboolean否false设为true以对消息正文启用 Markdown 格式化。tagslist否—为通知添加标签或表情符号字符串列表元素为标签或 emoji 短代码。priorityinteger否3通知优先级1 最低2 低3 默认4 高5 最高。clickstring否—点击通知时打开的 URL。delaymap否—设置消息投递延迟最短 10 秒最长 3 天。attachstring否—通过 URL 附加图片或其他文件。attach_filemap否—通过上传本地文件或相机媒体源附加图片或其他文件。filenamestring否—附件的自定义文件名含扩展名。emailstring否—将通知转发到的邮箱地址。callstring否—要拨打的电话号码通过 TTS 朗读消息。iconstring否—通知文本旁显示的图标 URL。actionlist否—最多三个动作按钮类型见下文。sequence_idstring否—消息或序列 ID用于更新已有通知或供之后更新、清除、删除通知时引用。其中priority参数直接对应 ntfy 的优先级体系1最低、2低、3默认、4高、5最高通知的紧迫程度会影响手机的振动模式、铃声和通知栏可见性。动作按钮的 YAML 配置action为列表类型最多三个按钮。每个按钮由type区分类型可选view、http、broadcast、copy四种。动作view打开网站或应用点击按钮时打开指定的网站或应用- type: view label: 查看车库摄像头 url: http://homeassistant.local/lovelace/garage clear: true参数类型必填默认值说明typestring是—填view。labelstring是—通知中动作按钮的标签。urlstring是—点击动作时打开的 URL。clearboolean否false点击动作按钮后清除通知。动作http发送 HTTP 请求点击按钮时向指定 URL 发送 HTTP 请求可用于触发 webhook 或其他自动化- type: http label: 开启派对模式 url: http://homeassistant.local/api/webhook/party-mode-webhook method: POST参数类型必填默认值说明typestring是—填http。labelstring是—通知中动作按钮的标签。urlstring是—HTTP 请求发送到的 URL。methodstring否POST请求使用的 HTTP 方法。headersmap否—随 HTTP 请求发送的附加请求头键值对。bodystring否—HTTP 请求体payload。clearboolean否false点击动作按钮后清除通知。动作broadcast发送 Android 广播点击按钮时发送一个 Android 广播 intent常用于唤起手机端 App 的特定行为例如在 Sleep as Android 中开始睡眠追踪- type: broadcast label: 开始睡眠追踪 intent: com.urbandroid.sleep.START_SLEEP_TRACK参数类型必填默认值说明typestring是—填broadcast。labelstring是—通知中动作按钮的标签。intentstring否io.heckel.ntfy.USER_ACTION触发broadcast动作时发送的 Android intent 名称。extrasmap否—以键值对形式包含在 intent 中的 extras。clearboolean否false点击动作按钮后清除通知。动作copy复制到剪贴板点击按钮时把指定值复制到剪贴板适合分享临时信息如访客 Wi-Fi 密码、门禁码- type: copy label: 复制密码 value: GuestPass1234!参数类型必填默认值说明typestring是—填copy。labelstring是—通知中动作按钮的标签。valuestring是—要复制到剪贴板的值。clearboolean否false点击动作按钮后清除通知。实战示例以下示例均来自 ntfy.publish 动作文档可直接复制到自动化或脚本中使用。发送带摄像头快照的通知有人按门铃时发送一张摄像头抓拍快照action: ntfy.publish target: entity_id: notify.mytopic data: title: Someone is at the door attach_file: media_content_id: media-source://camera/camera.demo_camera media_content_type: application/vnd.apple.mpegurl filename: camera-snapshot.jpg tags: - bellhop_bell这里attach_file以 Home Assistant 的媒体源形式引用摄像头实体filename指定了附件文件名含扩展名tags中的bellhop_bell会作为 emoji 短代码渲染在通知中。发送死循环开关Dead Mans Switch通知该通知在指定延迟之后才被投递充当所谓的死循环开关。要重置计时器例如每日打卡成功后只需再次发送该通知——这会取消先前已排程的通知并重新开始一个 24 小时倒计时action: ntfy.publish target: entity_id: notify.mytopic data: title: Dead Mans Switch Activated message: I havent checked in for 24 hours. Please check on me. priority: 5 delay: hours: 24 sequence_id: dead-mans-switch-check-in tags: - warning - skull要点解析delay使用 map 形式此处为hours: 24设置延迟投递符合最短 10 秒、最长 3 天的约束。sequence_id是关键它是死循环开关机制的核心。再次发布携带相同sequence_id的通知会覆盖并取消前一条待投递通知从而重置倒计时。priority: 5表示最高优先级确保 24 小时未打卡时通知以最紧急的方式提醒。tags中的warning与skull会作为标签/表情显示在通知中。发送带打开 URL按钮的通知通知附带一个动作按钮点击后打开指定 URL例如直接跳转到相关仪表盘或摄像头画面action: ntfy.publish target: entity_id: notify.mytopic data: message: The garage door has been open for 10 minutes. actions: - type: view label: View Garage Camera url: http://homeassistant.local/lovelace/garage clear: true发送可触发 webhook 的通知创建一个Party Mode按钮点击后通过 HTTP 请求让 Home Assistant 运行一个脚本action: ntfy.publish target: entity_id: notify.mytopic data: message: The party is starting! actions: - type: http label: Start Party Mode url: http://homeassistant.local/api/webhook/party-mode-webhook method: POST发送带复制到剪贴板按钮的通知分享临时信息如访客 Wi-Fi 密码或门禁码action: ntfy.publish target: entity_id: notify.mytopic data: title: Guest Wi-Fi Password message: Here is the guest Wi-Fi password for today. actions: - type: copy label: Copy Password value: GuestPass1234!发送可触发 Android 广播的通知通过 Android 广播 intent 在 Sleep as Android 中启动睡眠追踪action: ntfy.publish target: entity_id: notify.mytopic data: message: Time for bed? actions: - type: broadcast label: Start sleep tracking intent: com.urbandroid.sleep.START_SLEEP_TRACK配合 ntfy.clear 与 ntfy.delete 管理已发通知从 2026.2 版本发布说明 可以看到该版本为 ntfy 集成添加了sequence ID支持允许更新通知并新增了两个动作dismiss清除/标记已读和 delete删除。这两个动作均以sequence_id或消息 ID 作为必填参数用来定位目标通知。ntfy.clear清除标记已读通知Dismiss notificationntfy.clear动作把 topic 中先前发送的消息标记为已读但不删除适合通知不再需要关注、但后续仍想查看或引用时使用详见 ntfy.clear 动作文档。YAML 基本用法action: ntfy.clear target: entity_id: notify.mytopic data: sequence_id: motion-detected一个典型的自动化场景是后院移动被清除时自动把先前发送的检测到移动通知标记为已读automation: triggers: - trigger: motion.cleared target: area_id: backyard actions: - action: ntfy.clear data: sequence_id: motion-detected target: entity_id: notify.mytopicntfy.delete删除通知Delete notificationntfy.delete动作从 ntfy topic 中删除一条通知详见 ntfy.delete 动作文档。YAML 基本用法action: ntfy.delete target: entity_id: notify.mytopic data: sequence_id: motion-detected与 clear 的差别在于clear 只是标记已读、通知仍保留而 delete 会彻底移除该通知。同样也可以在移动已清除的自动化中把通知彻底删除automation: triggers: - trigger: motion.cleared target: area_id: backyard actions: - action: ntfy.delete data: sequence_id: motion-detected target: entity_id: notify.mytopic使用提醒要清除或删除通知必须提供其消息 ID 或 sequence ID而 sequence ID 正是在发送ntfy.publish时通过sequence_id参数指定的。因此设计发布 → 更新/清除/删除的完整通知生命周期时请务必在发布阶段为通知设置稳定的sequence_id。集成背景与使用限制前置条件与 topic 配置使用这些动作前需要先在设置 设备与服务中完成 ntfy 集成的配置服务 URL官方服务使用https://ntfy.sh也可填写其他公共 ntfy 服务或自建实例的地址如https://your-ntfy-instance.com。认证可选如果服务器启用了访问控制部分 topic 需要正确凭据才能订阅或发布。集成使用access token认证访问受保护的 topic提供用户名和密码后 Home Assistant 会自动生成并使用 access token。添加 topic选择添加主题Add topic然后选择输入主题名从 ntfy App 或网站复制现有 topic 名称或生成主题名让集成自动生成随机 topic 名。配置连接时的参数Service URL默认https://ntfy.sh、Verify SSL certificate是否校验 SSL 证书、Username可选与Password可选。每个 topic 还有可选的过滤选项按优先级、标签、标题、消息内容过滤这些过滤只作用于集成订阅消息时产生的 event 实体。注意topic 可能没有密码保护请选择不易被猜到的名称如果发送敏感信息建议保留 topic 并限制其访问权限。速率限制ntfy 服务设有各种速率与用量限制。官方 ntfy.sh 服务允许每 burst 最多 60 条消息补充速率为每 5 秒 1 条即 60 条的完整容量约 5 分钟补满。其余用量限制取决于账户等级可在Account → Usage查看。自建实例可配置更高或完全取消这些限制。在设计高频通知自动化例如批量告警脚本时应将这些限制纳入考虑。排障建议集成依赖与 ntfy 服务之间的活跃网络连接。如果遇到问题请先确认网络稳定且 ntfy 服务可达并留意服务端可能的维护或意外宕机。上报问题时建议启用调试日志若该路径存在、重启集成、问题复现后停止调试日志并尽可能附带诊断数据。总结ntfy.publish是 Home Assistant 中向 ntfy 推送富通知的入口动作与ntfy.clear、ntfy.delete共同构成了完整的通知生命周期管理能力。通过priority、tags、markdown、attach_file、delay、actionview / http / broadcast / copy和sequence_id等参数的组合你可以把一条普通推送升级为带图片快照、可交互操作、可延迟投递、可事后撤回的企业级告警方案。更多资料可继续阅读ntfy.publish 动作文档ntfy.clear 动作文档ntfy.delete 动作文档ntfy 集成完整文档【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
