ntfy

The ntfy integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows publishing push notifications on ntfy.sh or other ntfy services.

About ntfy

ntfy is a simple HTTP-based pub-sub notification service that allows you to send notifications to phones or desktops. The official ntfy 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.

How you can use this integration

The ntfy integration can be used to send push notifications from automations and scripts in real-time to your mobile devices and desktops.

Prerequisites

  1. Service URL

    To set up the ntfy integration, you need the URL of the ntfy service you wish to use.

    • Use https://ntfy.sh for the official ntfy service.
    • Provide the URL of an alternative public ntfy service or your self-hosted instance (for example, https://your-ntfy-instance.com).
  2. Authentication

    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.

  3. Adding a topic

    To set up topics for notifications, select the three-dot menu next to the entry of the previously configured ntfy service, then click Add topic.

    You can now choose one of the following options:

    • 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.
    • Select Generate topic name to allow the integration to generate a random topic name automatically.

    Repeat these steps for each topic you want to add.

Note

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.

Configuration

To add the ntfy integration to your Home Assistant instance, use this My button:

Manual configuration steps

If the above My button doesn’t work, you can also perform the following steps manually:

Configuration parameters

Service parameters

Service URL

Address of the ntfy service. Defaults to https://ntfy.sh.

Username (optional)

Username required to authenticate with protected ntfy topics.

Password (optional)

Password corresponding to the provided username for authentication.

Topic parameters

Topic

Name of the topic.

Display name (optional)

An alternative name to display instead of the topic name. This helps identify topics with complex or hard-to-read names more easily.

Notifiers

The ntfy integration will add a deviceA device is a model representing a physical or logical unit that contains entities. with an associated notify entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] for each configured topic. To publish notifications, you can use the notify.send_message actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more]. To use notifications, please see the getting started with automation page.

Example YAML configuration
action: notify.send_message
data:
  message: "Reminder: Have you considered frogs?"
  entity_id: notify.mytopic

Removing the integration

This integration can be removed by following these steps:

To remove an integration instance from Home Assistant

  1. Go to Settings > Devices & services and select the integration card.
  2. From the list of devices, select the integration instance you want to remove.
  3. Next to the entry, select the three-dot menu. Then, select Delete.