Calendar events

Description

A calendar event is a key element within the calendar system, defined as an object associated with a specific date or time range. Each calendar event is uniquely identified by a distinct ID. Beyond the basic start and end date-times, a calendar event encompasses a variety of information, including a summary, detailed description, location, current status, participants, and even attachments.

This rich set of data allows for a comprehensive representation of a calendar event, ensuring that all necessary details are captured and easily accessible. Events are integral to the functionality of the Calendar object, providing a structured yet flexible way to manage time-sensitive activities within the system.

Schema

Name	Type	Description
attachments	Array<Attachment>	An array of objects, each with uri (string) and mimeType (string).
attendees	Array<Attendee>	An array of objects representing the attendees.
comments	Array<String>	An array of strings, allowing additional comments on the event.
description	String	A detailed description of the event.
interval	Interval	A date-time interval, inclusive at the start and exclusive at the end.
locations	Array<Location>	A collection of event locations.
status	Enum	Can be one of CONFIRMED, TENTATIVE, or CANCELLED.
summary	String	The title of the event.
tags	Object<string,string>	An arbitrary key/value collection, useful for API users to store additional metadata.

Attachment

Name	Type	Description
url	String	The URL of the attachment
mimeType	String	A valid mime type for the attachment

Location

Name	Type	Description
text	String	A generic string with a valid location for the event. An address, a link to a conference or a maps URL.

Attendee

Schema

Name	Type	Description
id	String	The id of the attendee.
status	NEEDS_ACTION | DECLINED | TENTATIVE | ACCEPTED	The response status of the attendee.
email	String	The attendee's email address, if available.
displayName	String	The attendee's name, if available.
comment	String	Any response comment from the attendee.
invitation	Invitation	An object that represents an invitation to the event.

Description

The attendee object is a key component in event management, representing each individual invited to an event. Identified uniquely by a UUID, this object encompasses essential information about the invitee, including fields like email and displayName for identification and communication purposes.

An important attribute of the attendee object is the status field. This field plays a crucial role in tracking the attendee's response and engagement with the event invitation. The status can be one of the following:

• NEEDS_ACTION: This status indicates that the attendee has not yet responded to the invitation. It represents a state of awaiting reply, where no action has been taken by the guest regarding their participation in the event.
• DECLINED: If the attendee chooses not to participate in the event, their status is updated to DECLINED. This clearly communicates their decision to the event organizers, allowing for adjustments in planning and logistics.
• TENTATIVE: When an attendee is uncertain about their ability to attend the event but still considers it a possibility, their status is marked as TENTATIVE. This state reflects a non-committal yet open response, indicating potential attendance.
• ACCEPTED: This status is assigned when the attendee confirms their intention to attend the event. An ACCEPTED status assists in finalizing the attendee list and making necessary arrangements to accommodate the confirmed guests.

The status field is dynamic and can be updated to reflect changes in the attendee's decision. It can be modified manually through an HTTP request, which provides flexibility in managing attendee responses. Additionally, the status may automatically update in response to actions taken through the event's invitation system, such as RSVP responses.

Webhooks

When the calendar event object is changed the system will notify all registered webhooks with the CalendarEventChangedWebhook. This webhook has the following fields:

CalendarEventChangedWebhook

Name	Type	Description
type	CalendarEventChangedWebhook	The type discriminator which allows to recognize the webhook type.
new	CalendarEvent	The value of the updated calendar event
semanticDiff	Array< CalendarEventAttendeeReplyChange | CalendarEventScheduled | >	A nested array of objects explaining what happened with the event.

CalendarEventAttendeeReplyChange

This object represents that one attendee has replied to an invitation therefore the event status has changed.

Name	Type	Description
type	CalendarEventAttendeeReplyChange	The type discriminator which allows to recognize the webhook type.
attendee	Attendee	Detailed data of the attendee.

CalendarEventScheduled

This object represents that the event time has being updated.

Name	Type	Description
type	CalendarEventScheduled	The type discriminator which allows to recognize the webhook type.
interval	Interval	The new interval for the event.