From 3728e81fe8622d3904d7fe2eec7711b12ef3ec1f Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Thu, 25 Jan 2024 11:47:06 +0100 Subject: [PATCH] Document `set_conversation_response` script action (#31004) * Document `set_conversation_response` script action * Update scripts.markdown * Apply suggestions from code review * close raw tag * Add backticks --------- Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Co-authored-by: c0ffeeca7 --- source/_docs/scripts.markdown | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/source/_docs/scripts.markdown b/source/_docs/scripts.markdown index a8988e68b8f..98999558da3 100644 --- a/source/_docs/scripts.markdown +++ b/source/_docs/scripts.markdown @@ -914,6 +914,36 @@ script: entity_id: light.ceiling ``` +## Respond to a conversation + +The `set_conversation_response` script action allows returning a custom response +when an automation is triggered by a conversation engine, for example a voice +assistant. The conversation response can be templated. + +{% raw %} + +```yaml +# Example of a templated conversation response resulting in "Testing 123" +- variables: + my_var: "123" +- set_conversation_response: "{{ 'Testing ' + my_var }}": +``` + +{% endraw %} + +The response is handed to the conversation engine when the automation finishes. If +the `set_conversation_response` is executed multiple times, the most recent +response will be handed to the conversation engine. To clear the response, set it +to `None`: + +```yaml +# Example of a clearing a conversation response +set_conversation_response: ~ +``` + +If the automation was not triggered by a conversation engine, the response +will not be used by anything. + [Script integration]: /integrations/script/ [automations]: /docs/automation/action/ [Alexa/Amazon Echo]: /integrations/alexa/