### Sending a Notification (Good Example) Source: https://github.com/home-assistant/companion.home-assistant/blob/master/GEMINI.md This example demonstrates how to send a notification to a mobile device using the Home Assistant Companion App. It details the steps within the Home Assistant interface and provides platform-specific examples for iOS and Android. ```markdown ## Sending a notification to your phone A notification is a message that appears on your phone's lock screen or notification center, similar to text message alerts. ### Steps 1. In Home Assistant, go to [**Developer tools** > **Actions**.](https://my.home-assistant.io/redirect/developer_services/) 2. In the **Action** drop-down,, search for and select `notify.mobile_app_`. :::info Your phone name was set when you first connected the app to Home Assistant and per server. You can find it in the Companion app under **Settings** > **Companion app** > **Server & devices**. ::: ![iOS](/assets/iOS.svg) On iOS, the action might be called `notify.mobile_app_iphone`. ![Android](/assets/android.svg) On Android, it might be called `notify.mobile_app_pixel_7`. 3. In the **Action message** section, enter a message, such as `Hello from Home Assistant!`. 4. Select **Perform action**. 5. Check your phone. You should see a notification appear. ### Troubleshooting If the notification does not appear: - ![iOS](/assets/iOS.svg) Make sure notifications are enabled in iOS **Settings** > **Home Assistant** > **Notifications**. - ![Android](/assets/android.svg) Check that the app has notification permissions in Android **Settings** > **Apps** > **Home Assistant** > **Notifications**. ``` -------------------------------- ### Sending a Notification (Bad Example) Source: https://github.com/home-assistant/companion.home-assistant/blob/master/GEMINI.md This example shows a concise but less helpful way to describe sending notifications, lacking step-by-step guidance and platform specifics. ```markdown ## Notifications Perform the `notify.mobile_app_*` action with a message payload to send notifications. See the HA docs for more info on action calls. ``` -------------------------------- ### Development Commands Source: https://github.com/home-assistant/companion.home-assistant/blob/master/CLAUDE.md Commands for starting the local development server, building the static site, and serving the built site locally. ```bash npm start ``` ```bash npm run build ``` ```bash npm run serve ``` -------------------------------- ### Setup Docusaurus Dependencies (Windows) Source: https://github.com/home-assistant/companion.home-assistant/blob/master/README.md Installs Docusaurus and other necessary dependencies for local documentation development on Windows using Yarn. ```bash yarn ``` -------------------------------- ### Development Commands Source: https://github.com/home-assistant/companion.home-assistant/blob/master/GEMINI.md Commands for starting the local development server, building the static site for production, and serving the built site locally. ```bash npm start ``` ```bash npm run build ``` ```bash npm run serve ``` -------------------------------- ### Setup Docusaurus Dependencies (Bash) Source: https://github.com/home-assistant/companion.home-assistant/blob/master/README.md Installs Docusaurus and other necessary dependencies for local documentation development using a bash script. ```bash $ script/setup ``` -------------------------------- ### Open an Android Application using Intent Scheme Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/actionable.md Starts an action in an installed Android application using an intent scheme URI. This example uses the ZXing scanner. ```yaml - action: "URI" title: "Intent Scheme" uri: "intent://scan/#Intent;scheme=zxing;package=com.google.zxing.client.android;end" ``` -------------------------------- ### Launch App via Intent Scheme Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/integrations/android-webview.md Configure this to launch an app using the Intent scheme, which allows for more specific actions. If the app is not installed, the user will be directed to install it. ```yaml - type: weblink name: Scan url: "intent://scan/#Intent;scheme=zxing;package=com.google.zxing.client.android;end" ``` -------------------------------- ### Intent Extra Type Conversion Examples Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/commands.md Examples demonstrating how to specify different data types for intent extras. Values are converted according to the specified type, so ensure the conversion is possible and meaningful. ```text EXTRA:101:int ``` ```text EXTRA:101;102;103:int[] ``` ```text EXTRA:1;2;3:ArrayList ``` ```text EXTRA:10.1:double ``` ```text EXTRA:10.1;10.2;10.3:double[] ``` ```text EXTRA:10.1:float ``` ```text EXTRA:10.1;10.2;10.3:float[] ``` ```text EXTRA:101:long ``` ```text EXTRA:101;102;103:long[] ``` ```text EXTRA:1:short ``` ```text EXTRA:1;2;3:short[] ``` ```text EXTRA:127:byte ``` ```text EXTRA:127;64:byte[] ``` ```text EXTRA:true:boolean ``` ```text EXTRA:true;true;false:boolean[] ``` ```text EXTRA:a:char ``` ```text EXTRA:a;b;c:char[] ``` ```text EXTRA:abc:String ``` ```text EXTRA:%2C%3A%3B:String.urlencoded ``` ```text EXTRA:%2C%3A%3B:urlencoded ``` ```text EXTRA:a;b;c:String[] ``` ```text EXTRA:colon%3A;semicolon%3B;comma%2C:String[].urlencoded ``` ```text EXTRA:a;b;c:ArrayList ``` ```text EXTRA:colon%3A;semicolon%3B;comma%2C:ArrayList.urlencoded ``` -------------------------------- ### Launch App Command Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/commands.md Use this command to launch any installed application on the device. Requires the 'Draw Over Other Apps' permission. If the app is not installed, the user will be directed to the Play Store. ```yaml automation: - alias: Launch app trigger: ... action: - action: notify.mobile_app_ data: message: "command_launch_app" data: package_name: "com.twitter.android" ``` -------------------------------- ### Run Local Docusaurus Server (Windows) Source: https://github.com/home-assistant/companion.home-assistant/blob/master/README.md Starts a local development server for previewing documentation changes on Windows using Yarn. Access the docs at http://localhost:3000. ```bash yarn start ``` -------------------------------- ### Send a Basic Notification Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/basic.md This is a minimum working example of sending a notification. Ensure you replace `` with your actual device ID. The `message:` field is required. ```yaml automation: - alias: 'Send Notification' trigger: ... action: - action: notify.mobile_app_ data: message: "Notification text" ``` -------------------------------- ### Run Local Docusaurus Server (Bash) Source: https://github.com/home-assistant/companion.home-assistant/blob/master/README.md Starts a local development server for previewing documentation changes using a bash script. Access the docs at http://localhost:3000. ```bash $ script/server ``` -------------------------------- ### Broadcast Intent Example Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/commands.md Use this to broadcast an intent with specific package name, action, and extras. Ensure the intent extras are formatted correctly for the target application. ```yaml intent_package_name: "com.urbandroid.sleep" intent_extras: "MAX_RAW_DATA:0.2;0.2;0.4;0.3;5.4;6.8;1.2:float[]" intent_action: "com.urbandroid.sleep.watch.DATA_UPDATE" ``` -------------------------------- ### Open an Android Application by Package Name Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/actionable.md Launches an Android application using its package name. If the app is not installed, Home Assistant will open to its default page. ```yaml - action: "URI" title: "Open X" # Name of package for application you would like to open uri: "app://com.twitter.android" ``` -------------------------------- ### Configure Internal and External URLs in configuration.yaml Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/troubleshooting/setup.md Add `internal_url` and `external_url` under the `homeassistant:` section in your `configuration.yaml` if the app crashes during setup on Home Assistant 0.110. Replace URL with your Home Assistant instance address. ```yaml homeassistant: ... external_url: URL internal_url: URL ``` -------------------------------- ### External Link Example Source: https://github.com/home-assistant/companion.home-assistant/blob/master/GEMINI.md Use descriptive link text for external links instead of raw URLs for better readability and user experience. ```markdown [Home Assistant installation](https://www.home-assistant.io/installation/) https://www.home-assistant.io/installation/ ``` -------------------------------- ### External Link Example Source: https://github.com/home-assistant/companion.home-assistant/blob/master/CLAUDE.md Use descriptive link text for external links instead of raw URLs. This improves readability and user experience. ```markdown [Home Assistant installation](https://www.home-assistant.io/installation/) ``` -------------------------------- ### Launch App via App Scheme Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/integrations/android-webview.md Use this configuration to launch a specific app using its custom URL scheme. If the app is not installed, it will redirect to the Google Play store. ```yaml - type: weblink name: X url: "app://com.twitter.android" ``` -------------------------------- ### Basic Actionable Notification Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/actionable.md This example shows how to define two actions for a notification: one to trigger an event and another to open a URL. For Android, the 'URI' action requires the 'action' key to be set to 'URI'. ```yaml action: notify.mobile_app_ data: message: "Something happened at home!" data: actions: - action: "ALARM" # The key you are sending for the event title: "Sound Alarm" # The button title - action: "URI" # Must be set to URI if you plan to use a URI title: "Open Url" uri: "https://google.com" # URL to open when action is selected, can also be a lovelace view/dashboard ``` -------------------------------- ### Send Broadcast Intent with Extras Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/commands.md This example demonstrates how to include extras in a broadcast intent to control specific features within an app, such as turning on an alarm in Sleep as Android. Extras are formatted as key:value pairs, separated by commas. ```yaml automation: - alias: Send broadcast intent with extras trigger: ... action: - action: notify.mobile_app_ data: message: "command_broadcast_intent" data: intent_package_name: "com.urbandroid.sleep" intent_extras: "alarm_label:work,alarm_enabled:false" intent_action: "com.urbandroid.sleep.alarmclock.ALARM_STATE_CHANGE" ``` -------------------------------- ### Actionable Notification with iOS Icons Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/actionable.md This example demonstrates how to add icons to notification actions on iOS using SF Symbols. The icon name must be prefixed with 'sfsymbols:'. ```yaml action: - action: notify.mobile_app_ data: message: "Something happened at home!" data: actions: - action: "ALARM" title: "Sound Alarm" icon: "sfsymbols:bell" - action: "SILENCE" title: "Silence Alarm" icon: "sfsymbols:bell.slash" ``` -------------------------------- ### Send Broadcast Intent to Start Sleep Tracking Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/commands.md An example of sending a broadcast intent to the Sleep as Android app to start a sleep tracking event. This requires specific action and package names provided by the app's documentation. ```yaml automation: - alias: Send broadcast intent to start sleep tracking trigger: ... action: - action: notify.mobile_app_ data: message: "command_broadcast_intent" data: intent_package_name: "com.urbandroid.sleep" intent_action: "com.urbandroid.sleep.alarmclock.START_SLEEP_TRACK" ``` -------------------------------- ### Open Webview or Entity Info Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/commands.md Use `command_webview` to navigate the Companion App. Provide a `command` with a URL path to open a specific view/dashboard, or an `entityId:` to open an entity's More Info panel. If no command is given, it opens the homepage. ```yaml automation: - alias: Open android webview trigger: ... action: - action: notify.mobile_app_ data: message: "command_webview" data: command: "/lovelace/settings" ``` -------------------------------- ### Example Notification Received Event Data Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/received.md This is an example of the event data structure for `mobile_app_notification_received`. The event includes the message content and device ID. ```json { "event_type": "mobile_app_notification_received", "data": { "message": "test", "device_id": "DEVICE_ID" }, "origin": "REMOTE", "time_fired": "2020-10-06T05:36:12.864583+00:00", "context": { "id": "ID", "parent_id": null, "user_id": "USER_ID" } } ``` -------------------------------- ### Navigate to a Frontend Page Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/actionable.md Use this to open a specific view within the Home Assistant frontend. Replace `/lovelace/cameras` with your desired view path. ```yaml - action: "URI" title: "Open Cameras" uri: "/lovelace/cameras" ``` -------------------------------- ### Launch Android Activity with Command Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/commands.md Use this command to launch any Android activity. Requires specific permissions and configuration of intent parameters like action, URI, and package name. The `intent_extras` parameter supports additional data, formatted as comma-separated key:value pairs. ```yaml automation: - alias: Navigate trigger: ... action: - action: notify.mobile_app_ data: message: "command_activity" data: intent_package_name: "com.google.android.apps.maps" intent_action: "android.intent.action.VIEW" intent_uri: "google.navigation:q=arbys" ``` ```yaml automation: - alias: Search google maps trigger: ... action: - action: notify.mobile_app_ data: message: "command_activity" data: intent_package_name: "com.google.android.apps.maps" intent_action: "android.intent.action.VIEW" intent_uri: "geo:0,0?q=1600+Amphitheatre+Parkway%2C+CA" ``` -------------------------------- ### Repository Structure Overview Source: https://github.com/home-assistant/companion.home-assistant/blob/master/GEMINI.md Provides a high-level overview of the directory structure for the Home Assistant Companion app project. ```text docs/ ├── getting_started/ # Installation and setup guides ├── core/ # Core features (actions, location, sensors) ├── notifications/ # Push notification documentation ├── integrations/ # Platform integrations (widgets, shortcuts, etc.) ├── apple-watch/ # Apple Watch specific docs ├── wear-os/ # Wear OS specific docs ├── android-auto/ # Android Auto/Automotive docs ├── carplay/ # CarPlay docs ├── meta-quest/ # Meta Quest VR docs ├── troubleshooting/ # FAQs, errors, networking issues └── gallery/ # Screenshots and examples static/ ├── assets/ # Images, icons, screenshots └── img/ # Brand assets and logos sidebars.js # Navigation structure docusaurus.config.js # Site configuration ``` -------------------------------- ### Send Notification to a Group Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/basic.md Send a notification to all devices within a previously defined notification group. This example uses the `ALL_DEVICES` group. ```yaml automation: - alias: "Notify Mobile app group" trigger: ... action: - action: notify.ALL_DEVICES data: message: "Something happened at home!" ``` -------------------------------- ### Send a Deep Link to an Android App Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/actionable.md Sends a specific deep link to an Android application. This example demonstrates making a telephone call. ```yaml - action: "URI" title: "Call Pizza Hut" uri: "deep-link://tel:2125551212" ``` -------------------------------- ### Docusaurus Admonition Syntax Source: https://github.com/home-assistant/companion.home-assistant/blob/master/GEMINI.md Markdown examples for using Docusaurus admonitions to highlight different types of information: notes, info, warnings, and dangers. ```markdown :::note General information or tips. ::: ``` ```markdown :::info Helpful context or background information. ::: ``` ```markdown :::warning Important warnings the user should be aware of. ::: ``` ```markdown :::danger Critical information about potential data loss or security issues. ::: ``` -------------------------------- ### Repository Structure Source: https://github.com/home-assistant/companion.home-assistant/blob/master/CLAUDE.md Overview of the directory structure for the Home Assistant Companion app repository. ```text docs/ ├── getting_started/ # Installation and setup guides ├── core/ # Core features (actions, location, sensors) ├── notifications/ # Push notification documentation ├── integrations/ # Platform integrations (widgets, shortcuts, etc.) ├── apple-watch/ # Apple Watch specific docs ├── wear-os/ # Wear OS specific docs ├── android-auto/ # Android Auto/Automotive docs ├── carplay/ # CarPlay docs ├── meta-quest/ # Meta Quest VR docs ├── troubleshooting/ # FAQs, errors, networking issues └── gallery/ # Screenshots and examples static/ ├── assets/ # Images, icons, screenshots └── img/ # Brand assets and logos sidebars.js # Navigation structure docusaurus.config.js # Site configuration ``` -------------------------------- ### iOS Share Event Data Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/integrations/sharing.md Example event data received on iOS when content is shared to Home Assistant. Includes any text typed by the user and device information. ```json { "event_type": "mobile_app.share", "data": { "entered": "Text that I typed", "sourceDeviceID": "iphone_11_pro_debug", "sourceDeviceName": "iPhone 11 Pro", "sourceDevicePermanentID": "DEVICE_ID", "text": "Home Assistant automations system into multiple areas of iOS ", "url": "https://www.example.com" }, "origin": "REMOTE", "time_fired": "2020-09-25T01:07:48.926946+00:00", "context": { "id": "ID", "parent_id": null, "user_id": "USER_ID" } } ``` -------------------------------- ### Navigate to a specific view Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/integrations/url-handler.md Use this to open a specific view within the Home Assistant app. Specify the server using the `server=` query parameter if you have multiple servers configured. ```url homeassistant://navigate/dashboard-mobile/my-subview ``` ```url homeassistant://navigate/webcams?server=My%20home ``` ```url homeassistant://navigate/webcams?server=default ``` -------------------------------- ### Fire Detected iOS Notification Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/critical.md Configure a critical notification for iOS to alert about a fire. This example uses the 'critical: 1' flag and sets the volume to 100% for maximum audibility. ```yaml automations: - alias: "Fire Detected iOS" trigger: - platform: state entity_id: sensor.smoke_alarm to: "smoke" action: - action: notify.mobile_app_ data: title: "Wake up!" message: "The house is on fire and the cat's stuck in the dryer!" data: push: sound: name: "default" critical: 1 volume: 1.0 ``` -------------------------------- ### Turn Screen On Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/commands.md Use this command to turn on the device screen. This does not disable lock screens. Optionally, use `command: keep_screen_on` to enable the 'Keep screen On' feature. ```yaml automation: - alias: Screen on trigger: ... action: - action: notify.mobile_app_ data: message: "command_screen_on" data: command: "keep_screen_on" ``` -------------------------------- ### Send Broadcast Intent with JSON-formatted Extra Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/commands.md When sending data that contains special characters or delimiters, specify the type as `String.urlencoded`. This example shows how to send a JSON-formatted extra to Gadgetbridge. ```yaml automation: - alias: Send broadcast intent with JSON-formatted extra trigger: ... action: - action: notify.mobile_app_ data: message: "command_broadcast_intent" data: intent_package_name: "nodomain.freeyourgadget.gadgetbridge" intent_extras: "EXTRA_CONFIG_JSON:%7B%22push%22%3A%7B%22set%22%3A%7B%22widgetCustom0._.config.upper_text%22%3A%22Hi%22%7D%7D%7D:String.urlencoded" intent_action: "nodomain.freeyourgadget.gadgetbridge.Q_PUSH_CONFIG" ``` -------------------------------- ### Example Notification Cleared Event Data Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/cleared.md This JSON object represents the data structure of the `mobile_app_notification_cleared` event. It includes details about the notification message, the device ID, and context information. ```json { "event_type": "mobile_app_notification_cleared", "data": { "message": "test", "device_id": "DEVICE_ID" }, "origin": "REMOTE", "time_fired": "2020-10-06T05:36:12.864583+00:00", "context": { "id": "ID", "parent_id": null, "user_id": "USER_ID" } } ``` -------------------------------- ### Set up variables for actionable notifications Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/actionable.md This snippet demonstrates how to set up unique variables for notification actions to prevent multiple script runs from interfering with each other. It includes an `action_open` and `action_close` variable based on the `context.id`. ```yaml # inside a automation actions or script sequence - alias: "Set up variables for the actions" variables: # Including an id in the action allows us to identify this script run # and not accidentally trigger for other notification actions action_open: "{{ 'OPEN_' ~ context.id }}" action_close: "{{ 'CLOSE_' ~ context.id }}" ``` -------------------------------- ### Open More Info Panel for an Entity Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/actionable.md Triggers the More Info panel for a specific Home Assistant entity. Replace `sun.sun` with the entity ID you want to view. ```yaml - action: "URI" title: "View the sun" uri: "entityId:sun.sun" ``` -------------------------------- ### Android Alarm Stream Notification Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/critical.md Forces the notification to play from the alarm stream, making the device ring even if on vibrate or silent mode. This example uses `channel: alarm_stream` to achieve this. ```yaml automations: - alias: "Fire Detected Android alarm stream" trigger: - platform: state entity_id: sensor.smoke_alarm to: "smoke" action: - action: notify.mobile_app_ data: title: "Wake up!" message: "The house is on fire and the cat's stuck in the dryer!" data: ttl: 0 priority: high channel: alarm_stream ``` -------------------------------- ### Turn on light when arriving home after sunset Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/core/location.md This automation triggers when the device tracker's state changes to 'home' and turns on the front door light if it's after sunset. Ensure you replace `` with your actual device ID. ```yaml automation: - alias: "Turn door light on when getting home" trigger: - platform: state entity_id: device_tracker. to: "home" condition: - condition: sun after: sunset action: - action: light.turn_on data: entity_id: light.frontdoor ``` -------------------------------- ### Navigate Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/integrations/url-handler.md Allows updating the frontend page location via a deeplink. You can specify a server using the `?server=` query parameter. ```APIDOC ## Navigate ### Description This allows you to update the frontend page location via a deeplink. ### Endpoint homeassistant://navigate/ ### Query Parameters - **server** (string) - Optional - Specifies the server to navigate to. Defaults to the first available server if not provided or if set to `default`. ### Example `homeassistant://navigate/dashboard-mobile/my-subview` `homeassistant://navigate/webcams?server=My%20home` ``` -------------------------------- ### Android Share Event Data Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/integrations/sharing.md Example event data received on Android when content is shared to Home Assistant. Includes the sharing app's package name and the shared content. ```json { "event_type": "mobile_app.share", "data": { "caller": "android-app://com.android.chrome", "subject": "Webpage Title", "url": "https://www.example.xom", "text": "TEXT", "device_id": "DEVICE_ID" }, "origin": "REMOTE", "time_fired": "2020-09-25T01:06:48.512587+00:00", "context": { "id": "ID", "parent_id": null, "user_id": "USER_ID" } } ``` -------------------------------- ### Dog Barking Critical Notification Source: https://github.com/home-assistant/companion.home-assistant/blob/master/docs/notifications/critical.md Send a critical notification when a dog's bark exceeds a certain decibel level. This example uses the 'interruption-level: critical' syntax to ensure the notification is heard. ```yaml automations: - alias: "Dog barking loudly" trigger: - platform: numeric_state entity_id: sensor.dog_bark_decibel_meter above: "90" action: - action: notify.mobile_app_ data: title: "Snoopy is going to wake the neighbors" message: "The dog is barking and likely to wake the neighbors!" data: push: interruption-level: critical ```