Calendar


The Calendar integrationIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more]
provides calendar entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service.
[Learn more]
, allowing other integrations to integrate calendars into Home Assistant. Calendars are shown on the calendar dashboard and can be used with automations.

This page does not provide instructions on how to create calendar entities. Please see the “Calendar” category on the integrations page to find integration offering calendar entities.

Building block integration

The calendar integration cannot be directly used. You cannot create your own calendar entities using this integration. This integration is a building block for other integrations to use, enabling them to create calendar entities for you.

A calendar entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service.
[Learn more]
has a stateThe state holds the information of interest of an entity, for example, if a light is on or off. Each entity has exactly one state and the state only holds one value at a time. However, entities can store attributes related to that state such as brightness, color, or a unit of measurement.
[Learn more]
and attributes representing the next event (only). A calendar triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run.
[Learn more]
is much more flexible, has fewer limitations, and is recommended for automations instead of using the entity state.

Viewing and managing calendars

Each calendar is represented as its own entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service.
[Learn more]
in Home Assistant and can be viewed and managed on a calendar dashboard. You can find the calendar dashboard in the main sidebar of your Home Assistant instance.

Some calendar integrations allow Home Assistant to manage your calendars directly from Home Assistant. In this case, you can add new events by selecting the Add event button in the lower right corner of the calendar dashboard.

Also see Services below.

Automation

Calendar Triggers enable automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home.
[Learn more]
based on an event’s start or end. Review the Automating Home Assistant getting started guide on automations or the Automation documentation for full details.

Screenshot Trigger

An example of a calendar triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run.
[Learn more]
in YAML:

automation:
  - trigger:
    - platform: calendar
      # Possible values: start, end
      event: start
      # The calendar entity_id
      entity_id: calendar.personal
      # Optional time offset to fire a set time before or after event start/end
      offset: -00:15:00

Calendar triggers should not generally use automation mode single to ensure the trigger can fire when multiple events start at the same time (e.g., use queued or parallel instead). Note that calendars are read once every 15 minutes. When testing, make sure you do not plan events less than 15 minutes away from the current time, or your triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run.
[Learn more]
might not fire.

See Automation Trigger Variables: Calendar for additional trigger data available for conditions or actions.

Automation recipes

Below are a few example ways you can use Calendar triggers.

Services

Some calendar integrationsIntegrations connect and integrate Home Assistant with your devices, services, and more.
[Learn more]
allow Home Assistant to manage your calendars directly using servicesA service carries out one specific task, for example: turn on the light in the living room. A service has targets and data and can be called by actions, a dashboard, or via voice command.
[Learn more]
. The services provided by some calendar entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service.
[Learn more]
are described below or you can read more about Service Calls.

Service calendar.create_event

Add a new calendar event. A calendar target is selected with a Target Selector and the data payload supports the following fields:

Service data attribute Optional Description Example
summary no Acts as the title of the event. Bowling
description yes The description of the event. Birthday bowling
start_date_time yes The date and time the event should start. 2019-03-10 20:00:00
end_date_time yes The date and time the event should end (exclusive). 2019-03-10 23:00:00
start_date yes The date the whole day event should start. 2019-03-10
end_date yes The date the whole day event should end (exclusive). 2019-03-11
in yes Days or weeks that you want to create the event in. “days”: 2
location yes The location of the event. Bowling center

You either use start_date_time and end_date_time, or start_date and end_date, or in.

This is a full example of a serviceA service carries out one specific task, for example: turn on the light in the living room. A service has targets and data and can be called by actions, a dashboard, or via voice command.
[Learn more]
call in YAML:

service: calendar.create_event
target:
  entity_id: calendar.device_automation_schedules
data:
  summary: "Example"
  start_date: "2022-10-01"
  end_date: "2022-10-02"

Home Assistant Calendars do not allow zero duration Calendar events. The following would create a one minute long event starting “now”. This could be used to record an external event in a Calendar.

service: calendar.create_event
target:
  entity_id: calendar.device_automation_schedules
data:
  summary: "Example"
  start_date_time: "{{ now() }}"
  end_date_time: "{{ now() + timedelta(minutes=1) }}"

Service calendar.get_events

This service populates Response Data with calendar events within a date range. It can return events from multiple calendars.

Service data attribute Optional Description Example
start_date_time yes Return active events after this time (exclusive). When not set, defaults to now. 2019-03-10 20:00:00
end_date_time yes Return active events before this time (exclusive). Cannot be used with duration. You must specify either end_date_time or duration. 2019-03-10 23:00:00
duration yes Return active events from start_date_time until the specified duration. Cannot be used with end_date_time. You must specify either duration or end_date_time. days: 2

Use only one of end_date_time or duration.

service: calendar.get_events
target:
  entity_id:
    - calendar.school
    - calendar.work
data:
  duration:
    hours: 24
response_variable: agenda

The response data contains a field for every calendar entity (e.g. calendar.school and calendar.work in this case). Every calendar entity has a field events containing a list of events with these fields:

Response data Description Example
summary The title of the event. Bowling
description The description of the event. Birthday bowling
start The date or date time the event starts. 2019-03-10 20:00:00
end The date or date time the event ends (exclusive). 2019-03-10 23:00:00
location The location of the event. Bowling center

This example uses a template with response data in another service call:

service: notify.nina
data:
  title: Daily agenda for {{ now().date() }}
  message: >-
    Your school calendar for today:
    {% for event in agenda["calendar.school_calendar"]["events"] %}
    {{ event.start}}: {{ event.summary }}<br>
    {% endfor %}
    Your work calendar for today:
    {% for event in agenda["calendar.work_calendar"]["events"] %}
    {{ event.start}}: {{ event.summary }}<br>
    {% endfor %}