|
| 1 | +--- |
| 2 | +title: ntfy |
| 3 | +description: Instructions on how to integrate ntfy with Home Assistant. |
| 4 | +ha_category: |
| 5 | + - Notifications |
| 6 | +ha_iot_class: Cloud Push |
| 7 | +ha_release: 2025.5 |
| 8 | +ha_config_flow: true |
| 9 | +ha_codeowners: |
| 10 | + - '@tr4nt0r' |
| 11 | +ha_domain: ntfy |
| 12 | +ha_integration_type: integration |
| 13 | +ha_platforms: |
| 14 | + - notify |
| 15 | +--- |
| 16 | + |
| 17 | +The **ntfy** {% term integration %} allows publishing push notifications on [ntfy.sh](https://ntfy.sh/) or other ntfy services. |
| 18 | + |
| 19 | +## About ntfy |
| 20 | + |
| 21 | +**ntfy** is a simple HTTP-based pub-sub notification service that allows you to send notifications to phones or desktops. The official [ntfy](https://ntfy.sh/) service also provides additional features, such as notifications via email or phone calls using text-to-speech to read messages aloud. Since ntfy is 100% open-source, you can choose to use alternative public ntfy services or even host your own instance. |
| 22 | + |
| 23 | +## How you can use this integration |
| 24 | + |
| 25 | +The ntfy integration can be used to send push notifications from automations and scripts in real-time to your mobile devices and desktops. |
| 26 | + |
| 27 | +## Prerequisites |
| 28 | + |
| 29 | +1. **Service URL** |
| 30 | + |
| 31 | + To set up the **ntfy** integration, you need the URL of the ntfy service you wish to use. |
| 32 | + |
| 33 | + - Use `https://ntfy.sh` for the official ntfy service. |
| 34 | + - Provide the URL of an alternative public ntfy service or your self-hosted instance (for example, `https://your-ntfy-instance.com`). |
| 35 | + |
| 36 | +2. **Authentication** |
| 37 | + |
| 38 | + Depending on whether the server is configured to support access control, some topics may be read/write protected so that only users with the correct credentials can subscribe or publish to them. To publish/subscribe to protected topics, you can provide a username and password. |
| 39 | + |
| 40 | +3. **Adding a topic** |
| 41 | + |
| 42 | + To set up topics for notifications, select the three-dot {% icon "mdi:dots-vertical" %} menu next to the entry of the previously configured ntfy service, then click **{% icon "mdi:plus" %} Add topic**. |
| 43 | + |
| 44 | + You can now choose one of the following options: |
| 45 | + |
| 46 | + - Select **Enter topic** to add a new topic. Use an **existing topic name** by retrieving it from the ntfy app or the ntfy service's website. Simply copy and paste the topic name into the configuration. |
| 47 | + - Select **Generate topic name** to allow the integration to generate a **random topic name** automatically. |
| 48 | + |
| 49 | + Repeat these steps for each topic you want to add. |
| 50 | + |
| 51 | +{% note %} |
| 52 | + |
| 53 | +Topics may not be password-protected, so choose a name that's not easy to guess. If you are sending sensitive information, consider reserving the topic and restricting access to it. |
| 54 | + |
| 55 | +{% endnote %} |
| 56 | + |
| 57 | +{% include integrations/config_flow.md %} |
| 58 | + |
| 59 | +## Configuration parameters |
| 60 | + |
| 61 | +### Service parameters |
| 62 | + |
| 63 | +{% configuration_basic %} |
| 64 | +"Service URL": |
| 65 | + description: "Address of the ntfy service. Defaults to `https://ntfy.sh`." |
| 66 | +"Username (optional)": |
| 67 | + description: "Username required to authenticate with protected ntfy topics." |
| 68 | +"Password (optional)": |
| 69 | + description: "Password corresponding to the provided username for authentication." |
| 70 | +{% endconfiguration_basic %} |
| 71 | + |
| 72 | +### Topic parameters |
| 73 | + |
| 74 | +{% configuration_basic %} |
| 75 | +"Topic": |
| 76 | + description: "Name of the topic." |
| 77 | +"Display name (optional)": |
| 78 | + description: "An alternative name to display instead of the topic name. This helps identify topics with complex or hard-to-read names more easily." |
| 79 | +{% endconfiguration_basic %} |
| 80 | + |
| 81 | +## Notifiers |
| 82 | + |
| 83 | +The **ntfy** integration will add a {% term device %} with an associated notify {% term entity %} for each configured topic. To publish notifications, you can use the `notify.send_message` {% term action %}. To use notifications, please see the [getting started with automation page](/getting-started/automation/). |
| 84 | + |
| 85 | +{% details "Example YAML configuration" %} |
| 86 | + |
| 87 | +{% raw %} |
| 88 | + |
| 89 | +```yaml |
| 90 | +action: notify.send_message |
| 91 | +data: |
| 92 | + message: "Reminder: Have you considered frogs?" |
| 93 | + entity_id: notify.mytopic |
| 94 | +``` |
| 95 | +
|
| 96 | +{% endraw %} |
| 97 | +
|
| 98 | +{% enddetails %} |
| 99 | +
|
| 100 | +## Removing the integration |
| 101 | +
|
| 102 | +This integration can be removed by following these steps: |
| 103 | +
|
| 104 | +{% include integrations/remove_device_service.md %} |
0 commit comments