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. + +
+Which data fields can be used in a service call depends on the type of notification service that is used. +
+ +{% raw %} + +```yaml +service: notify.gmail_com +data: + target: "gduser1@workspacesamples.dev" + title: "Daily agenda for {{ now().date() }}" + message: >- + Your agenda for today: +

+ {% for event in agenda.events %} + {{ event.start}}: {{ event.summary }}
+ {% endfor %} +

+``` + +{% endraw %} + ### `homeassistant` services There are four `homeassistant` services that aren't tied to any single domain, these are: