Setting up a persistent notifications tray for Home Assistant

Disclaimer: This tutorial will use Pulsetray, a tool I've developed myself.

Introduction

If you use Home Assistant, you probably send notifications to your phone using the Companion App. It's great for letting you know when a door opens or a camera sees motion, but it has one problem I hated: There's no notifications tray.

While the Companion App notifications are highly customizable, they don't get stored anywhere. Once you dismiss an alert from your phone, it's gone forever.

I wanted a persistent searchable history of notifications, so I built a tool to fix it. This tutorial will show you how to setup an Android app to centralize your Home Assistant notifications, along with categories, rich media and a permanent history. You can even extend this to other platforms you'd like to monitor, like GitHub, UniFi Protect, and more.

Let's dive in!

1. Install and configure Pulsetray

First, we need to set up the app to receive alerts.

1. Download the Pulsetray app from the Play Store and complete the sign up process.
2. Navigate to Settings > API keys > Add API key
3. Enter a name and click on Add key.
4. Copy the generated Token immediately. You will use this token to authorize POST requests from Home Assistant, and this is the only time it'll be visible.

With the app being all set, let's move onto Home Assistant.

2. Setup a rest_command in Home Assistant

Next, we need to prepare Home Assistant to allow it to talk to Pulsetray. We will do this by creating a rest_command in your configuration.yaml file, which allows Home Assistant to send HTTP requests to external APIs.

1. Open your configuration.yaml file (you can use the File Editor add-on).
2. Append the YAML block shown below to the end of the file.
3. Replace YOUR_TOKEN with the API token you copied in the previous step.

rest_command:
  pulsetray:
    url: "https://api.pulsetray.com/v1/notifications"
    method: post
    content_type: "application/json"
    headers:
      Authorization: "Bearer YOUR_TOKEN"
    payload: "{{ json_body | to_json }}"

The payload: "{{ json_body | to_json }}" line allows us to define the specific contents of the notification later when we create our automation.

Save the file and restart your Home Assistant instance to apply the changes.

3. Create the automation

Once Home Assistant reboots, we can set up the actual trigger. For this example, I'll configure an alert that fires when my Samsung fridge door has been left open for more than 30 seconds.

In Home Assistant, go to Settings > Automations & scenes > + Create automation > Create new automation.

The trigger (When)

1. Click on + Add trigger
2. Select Device and choose your specific device (e.g. Fridge)
3. Select the trigger action (e.g. Fridge door opened) and set the duration to 30 seconds.

The action (Then do)

1. Click on +Add action
2. Search for and select RESTful Command: pulsetray
3. Click the three dots in the corner of the action and select Edit in YAML
4. Paste the following YAML code to define your notification payload:

action: rest_command.pulsetray
metadata: {}
data:
  json_body:
    title: Fridge door is open
    body: Fridge door has been open for more than 30 seconds
    androidConfig:
      priority: high

Done! You can now save the automation. To test the action, click the three dots at the top of the automation and select Run actions. You should receive a notification to your phone instantly.

Bonus! Organizing with Categories

Centralizing notifications is great, but a flat list can get messy really quickly. To separate and filter our alerts, we'll use sources and categories.

1. In the Pulsetray app, go to Settings > Sources and categories
2. Click + Add source. Set the code to home-assistant, and the name to Home Assistant. Save it.
3. In the source you've just created, click on + Add category. Set the code to fridge and the name to Fridge. Save it.

Now, go back to your Home Assistant automation and update your YAML action to include the new codes we've created:

action: rest_command.pulsetray
metadata: {}
data:
  json_body:
    title: Fridge door is open
    body: Fridge door has been open for more than 30 seconds
    source: home-assistant
    category: fridge
    androidConfig:
      priority: high

Save the automation, and you're good to go! You'll now be able to filter and separate your notifications at a glance.

Wrapping up

I built this tool to solve a problem I had, and I hope more people find it useful. You can integrate it with any service that supports POST requests or webhooks, like Vercel, GitHub or UniFi Protect.

To find more usages and customization, you can take a look at the docs.

If you have any questions or suggestions please let me know!