Skip to main content

Apprise smart home integration, free and open source

Apprise integration for Gladys Assistant

Gladys messages and scene notifications to 100+ services through your Apprise API.

View on GitHubAll integrations

Send the messages of Gladys to Discord, Telegram, Matrix, Slack, ntfy, Pushover, e-mail, SMS and more than 100 other services through your own Apprise API: the messages of your scenes, the answers of Gladys and its system messages, plus notifications with a title and a type from your scenes. Gladys talks to the Apprise API on your local network; Apprise then reaches each service.

Tested against a real Apprise API 2.0.1 (caronc/apprise image), with stored configurations, tags and attachments, but not in a real Gladys installation. If something does not work as described, please say so on the Gladys forum or in the issues.

What you need​

  • Gladys Assistant 5.1.0 or later.
  • An Apprise API that Gladys can reach on your network, for example the caronc/apprise Docker image (port 8000).
  • The services to notify, written as Apprise URLs: tgram://bottoken/chatid for Telegram, discord://webhook_id/webhook_token, mailto://user:[email protected], ntfy://topic… The list of services and their URL syntax is on appriseit.com.

Two ways to tell Gladys where to send:

  1. A stored configuration (recommended): in the web page of the Apprise API, create a configuration under a key (for instance apprise) and give each URL one or more tags: alice, bob, family, ops… Gladys then only knows the key and the tags, never your passwords.
  2. Apprise URLs pasted in Gladys: sent with each notification. Simpler, but the URLs (with their passwords) are stored in Gladys, masked.

Set up​

Install the integration from Integrations → Install from GitHub with the address https://github.com/guim31/gladys-apprise, then fill in its Configuration screen:

  • Apprise API address: the address you open the Apprise API with, port included, for example http://192.168.1.10:8000. An API served under a path behind a reverse proxy (https://example.org/apprise) works too.
  • Key of the stored configuration: apprise by default.
  • Shared tags: the services reached by the scene action and the test. family, ops reaches the services tagged family or ops; family ops (a space) those tagged family and ops; all every service. Left empty: only the services without any tag.
  • Shared Apprise URLs (instead of a configuration): optional. When given, the scene action and the test send to these URLs and ignore the key and the tags.
  • Default notification type: Information, Success, Warning or Failure. Apprise passes it to the services that know it (colour, icon).
  • Format messages as Markdown: on by default. Gladys writes bold text, lists and links in Markdown; Apprise converts them for each service.
  • Behind a reverse proxy (optional): the Apprise API has no login of its own. If you protect it with a reverse proxy, give the user and password of its basic authentication, or an extra header such as X-Api-Key: ….
  • Accept a self-signed certificate: only for an https:// address whose certificate you created yourself.
  • Language of the integration texts: French by default.

Then each person who wants to receive the messages Gladys sends them opens My account (in the integration page) and fills in:

  • Your tags: their tags in the stored configuration, for example alice;
  • or Your Apprise URLs (instead of tags): their own services, masked.

Leaving both empty means "send me nothing".

Finally, use Send a test notification (or the button of the widget): it checks the API, says how many services and which tags the configuration holds, and sends a test notification to the shared destination.

What Gladys sends​

  • Messages to a person: a scene "Send a message", the answers of Gladys, its system messages. They go to the tags or URLs of that person's My account, with the default type, as Markdown.
  • Camera images (scene action "Send a camera image"): sent as an attachment to the services that take one (Telegram, Discord, e-mail…). If the Apprise API refuses attachments (APPRISE_ATTACH_SIZE=0), the text leaves alone with a line saying so.
  • Scene notifications: the action described below.

Dashboard​

The Apprise widget shows whether the API answers, how many notifications went out today and how many failed (and the reason of the last failure), the last notifications sent by scenes with their type, and a Send a test button. The messages Gladys sends to one person are counted but never listed: the dashboard is shared by the household.

Scenes​

Triggers​

  • Apprise API offline: the API stopped answering (two checks 30 seconds apart). Variable: the error.
  • Apprise API back online: the API answers again after being offline.
  • Apprise notification not sent: a message could not be sent. Filters: the reason (Apprise unreachable, configuration to check, a service failed, notification refused) and who sent it (a Gladys message, the Apprise scene action). At most once per reason every 15 minutes, so a scene answering it with another notification cannot loop. Variables: reason, sender, error.

Actions​

Send an Apprise notification:

  • Title: optional.
  • Message: required; scene variables work.
  • Type: Default of the integration, Information, Success, Warning or Failure.
  • Tags: optional; replaces the shared tags for this notification (stored configuration only), for example ops.

Outputs: Notification sent (yes / no) and Error, to continue the scene differently when nothing went out.

Scene ideas​

  • The washing machine is done: "Send an Apprise notification" to family, type Success.
  • A water leak: type Failure, tags family, ops, so it reaches both the family chat and the e-mail of the person on duty.
  • Apprise notification not sent → turn a lamp red, or send the message by another integration.

Troubleshooting​

  • "no Apprise API at this address": the address does not lead to the Apprise API (wrong port, or a path is missing behind the reverse proxy).
  • "no configuration stored under this key in Apprise": check the key in the web page of the Apprise API.
  • "no service of the configuration has these tags": the tags of My account or the shared tags match no URL. Without any tag, only the untagged URLs are reached; use all for every service.
  • "a service did not receive it": Apprise reached the API of the service but it refused or failed (wrong token, expired webhook…). The logs of the Apprise API name the service. When several services are notified, the others did receive it.
  • "access refused": the reverse proxy refused the user, password or header.
  • Debug logs: set the LOG_LEVEL=debug environment variable. The logs never show an Apprise URL, a password or a header value.

Limits​

  • Send only: Apprise carries no message back to Gladys.
  • Gladys waits 5 seconds for a message to be sent. When the Apprise API does not answer within 4 seconds after receiving the whole request, the message counts as sent: Apprise goes on delivering it, its result is not known.
  • Delivery is as reliable as each service: Apprise reports a failure, it does not retry later.
  • The type is a hint: services without colour or icon ignore it.
  • The test notification goes to the shared destination only, not to the My account of each person.
  • Not affiliated with Apprise or its author.

Configuration settings​

These are the settings Apprise asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Connect your Apprise APIsectionNoApprise sends to Discord, Telegram, Matrix, e-mail, SMS and 100+ other services. Run the Apprise API (caronc/apprise) and either store a configuration in it (its web page, a key such as apprise) with a tag per person, or paste Apprise URLs below.
Apprise API addressstringYesThe address you open the Apprise API with, port included.
Key of the stored configurationstringNoThe configuration of the Apprise API that holds your services. Ignored when Apprise URLs are given below.
Shared tagsstringNoServices reached by the scene action and the test. "a, b": a or b; "a b": a and b; all: every service. Empty: the services without a tag.
Shared Apprise URLs (instead of a configuration)secretNoOne per line or separated by commas, e.g. tgram://token/chat_id. They hold passwords: stored masked, never logged.
Default notification typeselectNoApprise gives it to the services that know it (colour, icon).
Format messages as MarkdownbooleanNoGladys writes bold text, lists and links in Markdown: Apprise converts them for each service.
Behind a reverse proxy (optional)sectionNoThe Apprise API has no login of its own. If you protect it with a reverse proxy, give its credentials here.
User (basic authentication)stringNo
Password (basic authentication)secretNo
Extra headersecretNoSent with every request, as Name: value.
Accept a self-signed certificatebooleanNoOnly for an https:// address whose certificate you created yourself.
Language of the integration textsselectNoUsed for the notes added to the messages and the errors of the scene action.

How to install Apprise in Gladys​

  1. In Gladys, open Integrations: Apprise appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-apprise:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-apprise.

Apprise requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Apprise is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on