Sending Home Assistant Notifications to Discord

October 21, 2024

I’m quite new to home assistant. I set it up as part of getting a robot vacuum going in my place and have yet to really use it for anything. Now I’ve noticed that it tracks when the vacuum starts, if it has an error and when it stops. Valetudo (while being so very awesome) doesn’t notify me that the vacuum is running. It makes sense as that’s not the purpose of Valetudo. It’s quite slick in that it does communicate with MQTT (which is how home assistant knows what’s going on) so I guess you could hook MQTT up to a direct notifier of some sort but I haven’t looked into that and Home Assistant is relatively easy to setup and has the notification stuff on top of all the other amazing things you can do with it. You see what I really want is a notification to hit my phone when the vacuum starts, stops or errors.

Prerequisites

Home Assistant

I chose to setup home assistant core as a docker container. I’m currently running a bunch of docker containers and managing apps through docker is working for me. Not to mention standing up a new VM and figuring out Traefik routing and so on is too much like work. This can be a disadvantage as home assistant has an awesome setup for those who are not so technical when you install HA OS or HA Supervised. Add-ons and ancillary services are easy to setup from the HA interface if you’re using these options (this doesn’t work in a dockerized HA as these add-ons and ancillary services run in a docker manager under the HA supervisor/OS).

To setup home assistant core I’m using a dockerized Home Assistant from tiredofit. There were no gotchas or surprises. It just works with a very basic docker-compose file. I’m not putting it outside my network for now as I don’t have a burning need for it as the only thing it does is run the vacuum right now.

MQTT

In order for Home Assistant and the vacuum (or many other hardware items) to talk to each other you need a message queuing system. I chose Mosquitto as that’s what’s recommended by most of the sites I looked at. In the supervised or HA OS you’d just go and add an add-on, for HA core you have to setup a new docker container to run MQTT. Again, setting up Mosquitto was a follow the directions kinda thing. No surprises or difficulties. As with the HA app I used the dockerized mosquitto from tireofit.

Connecting HA and MQTT

In Home Assistant go to Settings > Devices & Services > Integrations and click on the “+ Add Integration” button bottom right. Choose a type of MQTT and add the necessary IP, port, username and password. Without anything connected nothing will happen… however, if you have the vacuum connected already (see below), the system will automatically find devices connected to that MQTT server and add the devices and their entities.

Valetudo on the Vacuum

The vacuum needs to be setup for this to work as well, in that Valetudo needs to be installed on your robot. The instructions on the Valetudo site are awesomely complete. If you happen to have a Dreame D10s Pro these are my notes.

One of the things to ensure is that once you have Valetudo setup is that you enable the MQTT connection. This is relatively simple, go to your Valetudo site running on your robot. On the menu on the left go to Connectivity. Then open the MQTT Connectivity page and configure the vacuum to log into the MQTT server.

Using the vacuum through Home Assistant

Now that we have a connection between HA and Valetudo life is getting interesting… but you’ll note there are a couple of challenges. Right now the system sees the vacuum but it can’t see the map that the vacuum/valetudo produces and while you can technically control it (setup automations and stuff) it’s not what it could be.

HACS and the Valetudo Map Card

There is an additional add-on like thing you can get to make this work better. This is for the Vacuum and Valetudo and gives you a map rendering (same as the one Valetudo creates for itself) and a couple of quick and dirty controls (start cleaning, where am I) on the vacuum.

This is installed and integrated using a thing called HACS (Home Assistant Community Store). Installing HACS on core is relatively painless. Get into the command-line for the docker container running HA and run the following (per the instructions here).

wget -O - https://get.hacs.xyz | bash -

Complete the installation by restarting home assistant from the home assistant interface (Settings > System > power button in the upper right corner) and following whatever prompts come up.

You’ll now have a HACS item in the menu for Home Assistant. This gives you the option to download and install a bewildering variety of custom code for home assistant. One of which is the Valetudo Map Card.

This is awesome and handy as it reproduces the map as drawn by Valetudo for you in Home Assistant. I understand there are further cool things you can do like capture these map images and send them as part of a notification… I haven’t got that far yet but so far it’s looking petty good.

Notifications:

And now we come to the point of this long winded post. Getting a notification about what’s happening on the device. Now… none of what we’ve done so far will get us a notification without some funky yaml getting written and stuffed into Home Assistant somehow (at this point I don’t even know how to do this without using other folks kind and generous work).

There are so many ways to customize and get Home Assistant to do cool things I can’t keep track… One more trick is Blueprints. These are the above funky yaml written by folks who know what they’re doing and made available to noobs like me. These blueprints can be found all over the place. A kind individual has posted a number of Valetudo blueprints on github including one that does Notifications. Using the link on that page with a running Home Assistant instance will install the necessary blueprint on Home Assistant and make your life much easier.

To configure this blueprint go to Settings > Automations & Scenes > Automations where you can click on the “+ Create Automation” button bottom right. One of your choices will be Valetudo Automation. Now you can configure this to point to the Vacuum (as found by MQTT) and the map and the device states that you’ll be getting notifications about Error and Status Flag (these are all entities found in the dropdown provided).

Notification Destinations

App on phone

Now you can send the notification to as many devices as you have configured which can accept notifications (phones with the app installed etc). If you haven’t got the app for Home Assistant setup on your phone you can do that easily enough. Once you have this configured on your phone (you’ve logged in and allowed the app to send notifications) then you can receive notifications on your phone this way. This works but I’m still quite new and when I click through from the notification I just get to the dashboard with the Valetudo Card on it. I’m guessing there is something I could do here… one is set up an “errors” card/notification/card condition that would show me the error event and the message that comes with it… but I haven’t figured that out yet. Also note, this has the limitation that if you’re not exposing your home assistant to the wide world then the app can’t receive notifications unless it’s on the same network (in the house only).

Discord Integration with Home Assistant

The other option that I care about is sending the notification to Discord. This is handy as it means I can receive the notification on my phone wherever I am as long as I have a network connection. It also means I can share notifications with people on discord as opposed to requiring everyone in the house to have the home assistant client on their phone.

There is discord integration built for bots that works quite well but requires fussing about. It took me many tries before getting the whole thing sorted out. I now have it sorted out only to find that this is a bit like trying to kill a fly with hammer… it’s a way of doing things but it’s not necessarily what I really want… the discord bot could be enabled to send messages to Home Assistant as well, and while it would be cool to figure out how to send a discord message to make something happen in my home it feels like a giant opening/invitation to someone to start messing about and I just don’t need that in my life.

There is a generic webhooks integration in HACS, originally built for the discord webhook integration. I’ve tried it as well and while a webhook is supposed to be simpler and easier (and one way) to setup, there is NO documentation available to make this easy.

Discord Bot Integration

To add the Discord integration to Home assistant go here and click on the “Add Integration to My” and follow the detailed instructions on this page. The most important thing is to ensure that you build the right authorization link, https://discordapp.com/api/oauth2/authorize?client_id=[APPLICATION_ID]&scope=bot&permissions=[PERMISSIONS_INTEGER] and get the right API key into Home Assistant. You’ll know this worked when you can see your “bot” as a member of the server you’re authorizing the bot to… ensure that when using the authorization link you choose the right server. This will ultimately end up as a named “Service” in Home Assistant. This is handy but it’s not a device or an entity that the Valetudo Notification Blueprint can use. So… there’s more fussing about to get this working.

First let’s test it. In home assistant go to Developer Tools > Actions and drop down the list of possible actions (which are provided by Services and other things in Home Assistant) to “Notifications: Send a notification with my_discord_integration” (this name will be the name of your service as you set it up earlier). Add a message and then add a target… this is a channel ID that you want to receive the message on. This channel ID comes out of the discord client itself when you have the developer options enabled. The channel ID is different from the App ID from Discord, if you don’t choose a real channel that is capable (on the authorized discord server) of receiving this message nothing will happen. When you press the perform action and everything is correctly connected your message appears on discord… I have to admit when I got this working I celebrated a little.

In order to make this service something that the Valetudo Notification Blueprint can use you have to create a Notification Group. Now, the new UI’s for Home Assistant are impressive and they do make it significantly easier to use.. However, some things have not made it into the UI yet (or can’t be ’cause it’s too complicated?), group configuration is in the GUI for Home Assistant, BUT it can NOT be used to create a notification group. The way to make a notification group for your carefully constructed discord integration is to hack YAML in the configuration.yaml file. The path to this file is …/homeassistant/config/configuration.yaml

the bit I added looks like this

# notify groups
notify:
  - name: my_discord_notification_group
    platform: group
    services:
      - service: my_discord_integration
        data:
          target: "1234567890123456789" #discord channel ID

Note the target… this is the target you added earlier in the Actions tab when testing. This was the final piece I did not have to get this going. It works a treat now.

Discord Webhook Integration

So, this started out looking quite easy… get into the HACS interface, install the plugin, configure the webhook… but nothing can be that easy it seems. For whatever reason this plugin WEBHOOK SERVICE INTEGRATION (I found this by searching HACS) needs installing manually. There’s a github repository and you can get the files you need (everything under webhook_service in the custom_components directory of the project) and upload them to your install (into the custom_components directory in your ha config directory, ensure ownership and permissions are correctly set). Now restart the Home Assistant instance for it to pickup this integration.

Once Home Assistant has restarted go to Settings > Devices & Services > Integrations and “+ Add Integration”, Webhook Service Integration is now an option. Add this and rename the service to something you can find easily. As above with the discord integration this adds a service that is neither a device nor an entity.

So, out of the box you can setup an automation ( Settings > Automations & Scenes > Automations) for when the vacuum starts and when it docks and then send this to a “Webhook Service Integration: Discord Webhook”. Configure this with a Webhook URL from discord and it will simply work… add a Title and a Description at the least and you’ll have something that will hit discord when the automation fires. The Webhook URL comes from the discord interface (right click on your server in Discord and then open “Integrations”). In Discord you can add and name a webhook to receive messages on. Set an avatar to something you will recognize, on the discord side it’s that easy.

Getting the messages sent by the Valetudo Notification blueprint requires extending the Valetudo Notification blueprint as webhooks aren’t notification entities. In the end I have got it working. The webhook version of the world is much simpler to setup on the discord side and provides a single simple URL to add to configuration on the Home Assistant side.

I will likely revisit this and add additional notes or a new posting about the mods to the blueprint that made this work.

As of the time of publishing this I have added a “started cleaning” message as well to the blueprint.