diff --git a/source/_docs/scripts/service-calls.markdown b/source/_docs/scripts/service-calls.markdown index 04f2e613c3e..c492e9ad3de 100644 --- a/source/_docs/scripts/service-calls.markdown +++ b/source/_docs/scripts/service-calls.markdown @@ -125,6 +125,57 @@ data: > {% endraw %} +### Use templates to handle response data + +Some services may respond with data that can be used in automation. This data is called _service response data_. Service response data +is typically used for data that is dynamic or large and which may not be suited for use in entity state. +Examples of service response data are upcoming calendar events for the next week or detailed driving directions. + +Templates can also be used for handling response data. The service call can specify +a `response_variable`. This is the [variable](/docs/scripts/#variables) +that contains the response data. You can define any name for your `response_variable`. This example calls a service and stores the response in +the variable called `agenda`. + +{% raw %} + +```yaml +service: calendar.list_events +target: + entity_id: calendar.school +data: + duration: + hours: 24 +response_variable: agenda +``` + +{% endraw %} + +You may then use the response data in the variable `agenda` in another action +in the same script. The example below sends a notification using the response +data. + +
+ {% for event in agenda.events %}
+ {{ event.start}}: {{ event.summary }}
+ {% endfor %}
+