- {% active_link /docs/configuration/events/ Events %}
-
diff --git a/source/docs/assist/aliases.markdown b/source/docs/assist/aliases.markdown
new file mode 100644
index 00000000000..75dcadce358
--- /dev/null
+++ b/source/docs/assist/aliases.markdown
@@ -0,0 +1,9 @@
+---
+title: "Assist - Entity Aliases"
+---
+
+Assist will use the names of your entities, as well as any aliases you've configured.
+
+
+
+By adding aliases in your native language, you can speak to Home Assistant with the language configured on your [Android watch](/docs/assist/android/) or [Apple device](/docs/assist/apple/).
diff --git a/source/docs/assist/android.markdown b/source/docs/assist/android.markdown
new file mode 100644
index 00000000000..158fe9cb52a
--- /dev/null
+++ b/source/docs/assist/android.markdown
@@ -0,0 +1,30 @@
+---
+title: "Assist on Android."
+---
+
+_The new tile is currently available in the [Android beta](https://play.google.com/apps/testing/io.homeassistant.companion.android) and will be part of the next Android release._
+
+Assist is available on WearOS using the [Home Assistant Companion App](https://companion.home-assistant.io/) and "Assist" tile.
+
+
+ +## Installation + +After [installing the companion app](https://companion.home-assistant.io/docs/getting_started/) and connecting it to your Home Assistant, visit the Android WatchOS app and click "Add tile" inside the Tiles area. Select the "Assist" tile to add it to your watch: + + + + +## Usage + +Swipe left on your watch until the "Assist" button is visible: + + + +After pressing "Assist", wait for "Speak Now" to be displayed: + + + +Speak your command, then press the "play" icon on the right to send the command to Home Assistant: + + diff --git a/source/docs/assist/apple.markdown b/source/docs/assist/apple.markdown new file mode 100644 index 00000000000..b451fbf1dc9 --- /dev/null +++ b/source/docs/assist/apple.markdown @@ -0,0 +1,65 @@ +--- +title: "Assist on Apple devices" +--- + +_The Assist shortcut will be available in the Mac and iOS beta channel today and will be part of the next release for iOS and Mac._ + +Assist is integrated into Apple devices using the [Shortcuts app](https://support.apple.com/guide/shortcuts/welcome/ios) that is available on all Apple devices. Assist can be used in the following ways on Apple devices: + +- Activated by Siri by saying the shortcut name "Hey Siri, Assist" +- Added to your iPhone home screen +- Pinned to your Mac menu bar +- Activated via a keyboard shortcut on your Mac +- Added as an Apple Watch complication + + + +## Installation + +To get started make sure you're running the latest version of the [Home Assistant Companion app](https://apps.apple.com/us/app/home-assistant/id1099568401?itsct=apps_box_badge&itscg=30200) and have updated your Apple devices. Then download the two shortcuts and open them to import them: + +- [Assist shortcut](https://www.icloud.com/shortcuts/4172210db1d74599bf9ae4f9e1e3d6ed) +- [Assist Button shortcut](https://www.icloud.com/shortcuts/73ebb68ca1a24ae1811b7d6971203334) + + + +There are two versions of the shortcut. The normal shortcut works better with Siri while the Button shortcut has the ability to use speech-to-text when triggered outside of Siri and can customize the input language (instead of relying on the OS language) + +[_Last updated: Jan 26, 2022_](#changelog) + +### Adjusting the language + +Shortcuts triggerd via Siri will always use the same language as Siri is set to. The Assist Button shortcut is meant to be manually triggered and can be configured for any language. + +Open the shortcuts app, and edit the Button Assist shortcut. The text in quotes will be shown in the language of your device. + +- Use the arrow to expand the _"Dictate text"_ action options, and select your language +- Use the arrow to expand the _"Assist with `Provided Input`"_ options, and select your language. + + +You can import the button shortcut multiple times to create versions for different languages, when asked if you would like to replace your Shortcut, choose "Keep Both". +
+ +## Multiple servers + +The Assist shortcut works also if you have configured multiple Home Assistant servers. By default it will prompt you to pick the server to sent the command too. This is not very hands-off, and so you can update the shortcut to point at a specific server. You will need to import the shortcuts multiple times, once for each server. + +Open the shortcuts app and edit each Assist shortcut. The text in quotes will be shown in the language of your device. + +- Use the arrow to expand the _"Assist with `Provided Input`"_ action, and select your Home Assistant server. + +## Customizing the Siri experience + +Siri allows activating shortcuts by their name. If you change the name of the "Assist" shortcut, you will also have to refer to it by its new name: "Hey Siri, my new name". Be aware that Siri can get confused and might not work if your shortcut name overlaps with actual Siri commands. + +It is possible to change the text that Siri says when activating the Assist shortcut. Open the shortcuts app and edit each your Assist shortcut. The text in quotes will be shown in the language of your device. + +- Find _"Ask for `Text`"_ and tap on _`How can I assist?`_ and change it to your desired prompt. + +You can also use the share action to [add a Shortcut to your Home Screen](https://support.apple.com/guide/shortcuts/apd735880972/ios) or set an [Accessibility Shortcut](https://support.apple.com/en-gb/HT204390) to run this Shortcut when you triple-click the Side button. + +## Changelog + +### Version 1 - Jan 26, 2022 + +Initial release diff --git a/source/docs/assist/builtin_sentences.markdown b/source/docs/assist/builtin_sentences.markdown new file mode 100644 index 00000000000..41abf4245e7 --- /dev/null +++ b/source/docs/assist/builtin_sentences.markdown @@ -0,0 +1,27 @@ +--- +title: "Assist - Default Sentences" +--- + +Home Assistant comes with built-in sentences [contributed by the community](https://github.com/home-assistant/intents/) for [dozens of languages](https://developers.home-assistant.io/docs/voice/intent-recognition/supported-languages). +These sentences allow you to: + +* **Turn entities on and off** + * *"turn on the living room light"* + * *"turn off ceiling fan"* +* **Open and close covers** + * *"Close the garage door"* + * *"Open kitchen window"* +* **Set the brightness and color of lights** + * *"Change kitchen lights brightness to 50%"* + * *"Set bed light to green"* + +In addition to individual entities, commands can target **areas**: + +* *"turn on all lights in the living room"* +* *"open windows in the kitchen"* +* *"change kitchen brightness to 50%"* +* *"set bedroom lights to green"* + +Entity [aliases](/docs/assist/aliases) are also matched so multiple names can be used, even in different languages. + +You can extend the built-in sentences or [add your own](/docs/assist/custom_sentences) to trigger any action in Home Assistant. diff --git a/source/docs/assist/custom_sentences.markdown b/source/docs/assist/custom_sentences.markdown new file mode 100644 index 00000000000..5c2e5112a92 --- /dev/null +++ b/source/docs/assist/custom_sentences.markdown @@ -0,0 +1,120 @@ +--- +title: "Assist - Custom Sentences" +--- + +You may add your own sentences to the intent recognizer by either extending an [existing intent](https://developers.home-assistant.io/docs/intent_builtin/) or creating a new one. You may also [customize responses](#customizing-responses) for existing intents. + +## In configuration.yaml + +Intents and sentences may be added in the [`conversation`](/integrations/conversation/) config in your `configuration.yaml` file: + +{% raw %} + +```yaml +# Example configuration.yaml +conversation: + intents: + HassTurnOn: + - "activate [the] {name}" +``` + +```yaml +# Example configuration.yaml +conversation: + intents: + HassTurnOn: + - "activate [the] {name}" +``` + +{% endraw %} + +This extends the default English sentences for the `HassTurnOn` intent, allowing you to say "activate the kitchen lights" as well as "turn on the kitchen lights". + +New intents can also be added, with their responses and actions defined using the [`intent_script`](/integrations/intent_script/) integration: + +{% raw %} + +```yaml +# Example configuration.yaml +conversation: + intents: + YearOfVoice: + - "how is the year of voice going" + +intent_script: + YearOfVoice: + speech: + text: "Great! We're at over 40 languages and counting." +``` + +{% endraw %} + +Besides a text response, `intent_script` can trigger any `action` available in Home Assistant, such as calling a service or firing an event. + +## In config directory + +More advanced customization can be done in Home Assistant's `config` directory. YAML files in `config/custom_sentences/en`, for example, will be loaded when English sentences (language code `en`) are requested. + +The following example creates a new `SetVolume` intent that changes the volume on one of two media players: + +{% raw %} + +```yaml +# Example config/custom_sentences/en/media.yaml +language: "en" +intents: + SetVolume: + data: + - sentences: + - "(set|change) {media_player} volume to {volume} [percent]" + - "(set|change) [the] volume for {media_player} to {volume} [percent]" +lists: + media_player: + values: + - in: "living room" + out: "media_player.living_room" + - in: "bedroom" + out: "media_player.bedroom" + volume: + range: + from: 0 + to: 100 +``` + +{% endraw %} + +As mentioned above, you can then use the `intent_script` integration to implement an action and provide a response for `SetVolume`: + +{% raw %} + +```yaml +# Example configuration.yaml +intent_script: + SetVolume: + action: + service: "media_player.volume_set" + data: + entity_id: "{{ media_player }}" + volume_level: "{{ volume / 100.0 }}" + speech: + text: "Volume changed to {{ volume }}" +``` + +{% endraw %} + +## Customizing Responses + +Responses for existing intents can be customized as well in `config/custom_sentences/`: + +{% raw %} + +```yaml +# Example config/custom_sentences/en/responses.yaml +language: "en" +responses: + intents: + HassTurnOn: + default: "I have turned on the {{ slots.name }}" +``` + +{% endraw %} diff --git a/source/docs/assist/index.markdown b/source/docs/assist/index.markdown new file mode 100644 index 00000000000..bfde547ee8c --- /dev/null +++ b/source/docs/assist/index.markdown @@ -0,0 +1,21 @@ +--- +title: Assist - Talking to Home Assistant +--- + + 
+
+Assist is our feature to allow you to control Home Assistant using natural language. It is built on top of an open voice foundation and powered by knowledge provided by our community. You can use the [built-in sentences](/docs/assist/builtin_sentences) to control entities and areas, or [create your own](/docs/assist/custom_sentences).
+
+[List of supported languages.](https://developers.home-assistant.io/docs/voice/intent-recognition/supported-languages)
+
+Assist is available to use on most platforms that can interface with Home Assistant. Look for the Assist icon 
:
+
+- Inside the Home Assistant app in the top-right corner
+- On Android Watch using [Assist tile](/docs/assist/android)
+- On Apple devices via [Siri and Assist shortcuts](/docs/assist/apple)
+
+Did Assist not understand your sentence? [Contribute them.](https://developers.home-assistant.io/docs/voice/intent-recognition/)
+
+_Assist was introduced in Home Assistant 2023.2._
+
+diff --git a/source/images/assist/android_tile.png b/source/images/assist/android_tile.png new file mode 100644 index 00000000000..bcfced7ad91 Binary files /dev/null and b/source/images/assist/android_tile.png differ diff --git a/source/images/assist/android_watch.png b/source/images/assist/android_watch.png new file mode 100644 index 00000000000..ae93b94b8e2 Binary files /dev/null and b/source/images/assist/android_watch.png differ diff --git a/source/images/assist/android_watch_1.png b/source/images/assist/android_watch_1.png new file mode 100644 index 00000000000..9c921883a26 Binary files /dev/null and b/source/images/assist/android_watch_1.png differ diff --git a/source/images/assist/android_watch_2.png b/source/images/assist/android_watch_2.png new file mode 100644 index 00000000000..769bcc4c362 Binary files /dev/null and b/source/images/assist/android_watch_2.png differ diff --git a/source/images/assist/android_watch_3.png b/source/images/assist/android_watch_3.png new file mode 100644 index 00000000000..7614b7ca75b Binary files /dev/null and b/source/images/assist/android_watch_3.png differ diff --git a/source/images/assist/assist-logo.png b/source/images/assist/assist-logo.png new file mode 100644 index 00000000000..b9717beb335 Binary files /dev/null and b/source/images/assist/assist-logo.png differ diff --git a/source/images/assist/ios-expanded-shortcut-action.jpeg b/source/images/assist/ios-expanded-shortcut-action.jpeg new file mode 100644 index 00000000000..be98e8b1ff3 Binary files /dev/null and b/source/images/assist/ios-expanded-shortcut-action.jpeg differ