mobile_app component has a notify platform built in that allows for a generic way to send push notifications to your users without requiring installation of an external custom component.
Enabling push notifications
To enable the notify platform for your application, you must set two keys in the
app_data object during the initial registration or later update of an existing registration.
|string||A push notification token unique to your users device. For example, this could be a APNS token or a FCM Instance ID/token.|
|string||The URL on your server that push notifications will be HTTP POSTed to.|
You should advise the user to restart Home Assistant after you set these keys in order for them to see the notify target. It will have the format
Deploying a server component
The notify platform doesn't concern itself with how to notify your users. It simply forwards a notification to your external server where you should actually handle the request. This approach allows you to maintain full control over your push notification infrastructure.
See the next section of this document for an example server implementation of a push notification forwarder that uses Firebase Cloud Functions and Firebase Cloud Messaging.
Your server should accept a HTTP POST payload like this:
It should respond with a 201 status code assuming the notification was queued for delivery successfully.
If an error occurs you should return a description of what went wrong with a status code other than 201 or 429. An error response must be a JSON object and can contain one of the following keys:
|string||If provided, it will be appended to a preset error message. For example, if |
|string||If provided, it will be output directly to the logs at the warning log level.|
No matter what key you use, you should try to be as descriptive as possible about what went wrong and, if possible, how the user can fix it.
The notify platform also supports exposing rate limits to users. Home Assistant suggests you implement a conservative rate limit to keep your costs low and also so that users don't overload themselves with too many notifications. For reference, Home Assistant Companion has a maximum sendable notifications per 24 hours of 150 notifications. The rate limit resets for all users at midnight, UTC. You of course are free to use whatever configuration for your own rate limiting.
If you choose to implement rate limiting, your successful server response should look like the following:
|integer||The number of successful push notifications the user has sent during the rate limit period.|
|integer||The number of failed push notifications the user has sent during the rate limit period.|
|integer||The maximum number of push notifications the user can send during the users rate limit period.|
|ISO8601 timestamp||The timestamp that the users rate limit period expires at. Must be provided in the UTC timezone.|
The rate limits will be output to the log at the warning log level after every notification is successfully sent. Home Assistant will also output the exact time remaining until the rate limit period resets.
Once the user hits their maximum amount of notifications sent in the rate limit period, you should start responding with a 429 status code until the rate limit period expires. The response object can optionally contain a key,
message which will be output to the Home Assistant log instead of the standard error message.
The notify platform does not itself implement any kind of rate limit protections. Users will be able to keep sending you notifications, so you should reject them with a 429 status code as early in your logic as possible.
Example server implementation
The below code is a Firebase Cloud Function that forwards notifications to Firebase Cloud Messaging. To deploy this, you should create a new Firestore database named
rateLimits. Then, you can deploy the following code.
Also, ensure that you have properly configured your project with the correct authentication keys for APNS and FCM.