Assist and AI Agents¶

Supernotify can give tools to Assist, so a conversation agent can send notifications, snooze them, and explain what happened to them. It works by voice or from the chat icon in the app.

The same tools are offered to AI agents connected through Home Assistant's Model Context Protocol Server, as long as the server exposes the Assist API.

A more limited set of interactions, without the flexibility of AI understanding, is available for the basic non-AI Assist agent, using a set of fixed sentence structures, see Built-in Agent Sentences for more info.

Even if you only ever type to the agent in a chat window, the place in Home Assistant where you manage them is called Voice Assistants.

Switching On¶

Nothing is offered until you switch it on. In Settings > Devices & services > Supernotify > Configure, choose Assist and AI agents. There are three switches:

What You Can Ask¶

Ask in your own words - there's no need to name the tools.

The agent is told the names of your deliveries, scenarios and recipients, including any alias, so it can match "the family chat" to a delivery. Good aliases help it choose well.

Sending¶

The agent can give a message, title and priority, pick recipients by name, and choose deliveries and scenarios. If it doesn't choose deliveries, Supernotify picks them as it would for an automation, from the priority, scenarios and who is home. Any priority can be used, including critical.

Some fields of supernotify.notify are not offered, so an agent can only reach people and devices you have already configured:

• custom_target, since it takes any e-mail address, phone number or chat id. Send to those through Recipients or notify entities instead.
• actions, custom mobile push actions.
• Media URLs and camera snapshots.

Snoozing¶

The agent can snooze for a number of minutes, silence until undone, unsnooze one snooze, or clear_all snoozes. A snooze can cover everything, non-critical notifications only, or one delivery, transport, priority or camera.

If the agent doesn't name who the snooze is for, it applies to the person asking, if Supernotify can match their Home Assistant user to a recipient. Otherwise it applies to everyone. See Snoozing for how snoozes work.

Explaining¶

supernotify__recent_notifications lists recent notifications with, for each delivery, whether it sent, was skipped or failed, and why. It also shows what selected each delivery, and who was home at the time, since that decides some deliveries.

Turn on the file archive to get a history. Without it, only the most recent notification since Home Assistant started is known.

Dry Run¶

supernotify__dry_run works out which deliveries a notification would use right now, and who it would reach, without sending anything. It makes the same checks as a real notification, including snoozes, priorities, conditions and who is home, except the duplicate check. E-mail addresses and phone numbers are partly masked.

Help from the Documentation¶

supernotify__help looks up this documentation site, including the recipes and configuration examples, and gives the agent the best matching pages to answer from, with links. It fetches the documentation from supernotify.rhizomatics.org.uk the first time it's used, then at most once a day. The documentation is for the latest release, and in English, though the agent can answer in your language.

Tuning the Agent Character¶

Additional prompts to use before conversations can be set in the Voice Assistants configuration, see Creating a Voice Assistant Personality.

Built-in Agent Sentences¶

Home Assistant's built-in Conversation agent doesn't use an AI model, so it can't use the tools above, but it can understand fixed sentences. Switch on Built-in agent sentences and it understands these, by voice or in the chat:

"Tell", "notify" and "message" all work for notifying, as do "that" and "saying" before the message. A recipient can be named by their full name, alias, or just their first name when no one else shares it - if two do, the agent asks which one you mean. Snoozes and silences are for the person asking, when Supernotify can match their Home Assistant user to a recipient, otherwise for everyone.

Times¶

A snooze lasts until the next time the clock shows the time asked for, today or tomorrow. Only these forms of time are understood:

The reply says am or pm, so if the guess at morning or afternoon was wrong, ask again with am or pm. Anything else, like quarter to four, half three (which means 2:30 in some places) or teatime, isn't understood, and the agent asks for a time like 15:30 or 3:30pm instead.

Italian¶

The same commands can be given in Italian, whatever the language of the assistant, and the answer comes back in Italian:

Times use the 24 hour clock, as 15, 15:30 or 15.30. "Avvisa", "avverti", "informa", "dì a" and "scrivi a" all work for notifying, and "posticipa", "sospendi", "silenzia" or "metti in pausa" for snoozing.

Other Languages¶

The sentences are in English and Italian for now - if you'd like them in your language, please suggest wording on GitHub issues. They live in SENTENCES and RESPONSES in sentences.py, one entry per language.

This functionality is also available to scripts and automations from the conversation.process action.

FAQ¶

Can I ask Alexa about notifications?¶

Not directly. Home Assistant's Alexa integrations let Alexa control devices, or let Home Assistant speak through an Echo, but neither passes what you say to Assist. There are two ways round it:

• A custom Alexa skill that hands speech to Assist, such as HomeAssistantAssist. Everything said after the skill's name goes to Home Assistant's conversation API, so all the sentences above work, and Alexa reads back the answer - "Alexa, ask smart home to snooze my notifications until 3". It needs an Alexa developer account, and Home Assistant reachable from outside, for example with Nabu Casa. The skill calls Home Assistant with one long-lived token, so "my notifications" means that token's user - snoozes are for everyone unless that user is also a recipient.
• An Alexa Routine that runs a script. Make a script for each fixed command, which passes one of the sentences above to the conversation.process action, and expose it to Alexa, where it shows up as a scene a Routine can run. There's no skill to build, but only fixed phrases work - no times, names or messages - and Alexa just says "OK" rather than Supernotify's answer. The snooze is for everyone, since the script isn't run as anyone who is a recipient.

alias: Snooze notifications for an hour
sequence:
  - action: conversation.process
    data:
      agent_id: conversation.home_assistant
      text: Snooze notifications for an hour

Further Reading¶

• AI Agents for the Smart Home - 2024 vision paper from Home Assistant team
• Home Assistant MCP - Official integrations