Reminders & notifications

The Calendar API provides support for reminders and notifications.

  • Reminders are alarms triggered at a specified time before an event starts.
  • Notifications allow users to find out about changes to events in their calendar.

The latter item should not be confused with push notifications which, instead of being delivered to a user, notify another server of changes to a calendar.

For more details about notifications in Google Calendar, go to Modify Google Calendar notifications.

Reminders

A reminder consists of:

  • When to show the reminder, expressed as minutes before the event start time
  • The delivery method to use (see Delivery mechanisms)

Reminders can be specified for whole calendars and for individual events. Users can set default reminders for each of their calendars; these defaults apply to all events within that calendar. However, users can also override these defaults for individual events, replacing them with a different set of reminders.

Default reminders

Reminders are private information, specific to an authenticated user; they're not shared across multiple users. As a result:

  • Default reminders are manipulated through the CalendarList collection, which contains user-specific calendar metadata
  • They're not accessible through the Calendars collection, which contains global metadata shared across all users.

Default reminders are also returned when doing an Events list query.

Overriding default reminders

To override the default reminders when you insert or modify an event, set reminders.useDefault to false and populate reminders.overrides with the new reminder set.

"reminders": {
  "useDefault": false,
  # Overrides can be set if and only if useDefault is false.
  "overrides": [
      {
        "method": "reminderMethod",
        "minutes": "reminderMinutes"
      },
      # ...
  ]
}

To revert to the default set of reminders, perform an update setting reminders.useDefault back to true.

Notifications

Calendar supports the following notification types:

  • Event creation: a new event is added to one of the user's calendars.
  • Event change: the organizer modified an event the user was invited to.
  • Event cancellation: an event is canceled the user was invited to.
  • Attendee response: an attendee to an event created by the user changed their response status.
  • Agenda: a list of all the events in the user’s calendar, sent at the start of the day.

The user can decide what notifications to enable per calendar and the delivery method for each notification type. These settings are not shared with other users. Similar to default reminders, they’re accessible through the CalendarList collection.

To send email notifications to attendees for events that were inserted or updated via the API, set the sendNotifications parameter in the insert/update request to true.

Delivery mechanisms

The delivery methods offered by Google Calendar are:

  • Pop-up. These are supported on mobile platforms and on web clients.
  • Email sent by the server.

The following table shows the supported methods for each reminder or notification type:

Pop-up Email
Reminders Default reminders
Override reminders
Notifications Event creation
Event change
Event cancellation
Attendee response
Agenda