> ## Documentation Index
> Fetch the complete documentation index at: https://botpress.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Calendar

> Add a bot to Google Calendar using the official integration.

{/* vale on */}

[Open in Hub](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01KMZAJAKBEZKGH0ZPQJBR1VAE)
*v2.0.9*

The official Google Calendar integration allows your bot to access your Google Calendar data and manage events.

## Setup

> [tab] Basic configuration
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> > * A [Google account](https://www.google.com/url?sa=t\&source=web\&rct=j\&opi=89978449\&url=https://accounts.google.ca/\&ved=2ahUKEwjT06jO35CSAxWy5MkDHcRzEJIQFnoECAwQAQ\&usg=AOvVaw2kpHPlQsXrFmVVEu4DOt-N)
>
> **Step 1**
>
> In Botpress Studio, select **Explore Hub** in the upper-right corner.
>
> **Step 2**
>
> Search for the **Google Calendar** integration, then select **Install Integration**.
>
> **Step 3**
>
> In the **Configuration** menu, select **Authorize Google Calendar**.
>
> **Step 4**
>
> Follow the instructions to connect Botpress to your Google account.

> [tab] Manual configuration
>
> For more advanced use cases, you can manually configure the integration.
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> > * A [Google account](https://accounts.google.com/signup)
> > * Access to [Google Cloud Console](https://console.developers.google.com/)
>
> ### Step 1: Create a Google Cloud project
>
> **Step 1**
>
> Go to the [Google Cloud Console](https://console.developers.google.com/) and sign in with your Google account.
>
> **Step 2**
>
> Go to **Select a project**, then select **New Project**.
>
> **Step 3**
>
> Enter your project details:
>
> * **Project name**: Choose a descriptive name for your project.
> * **Organization**: Select your organization (if applicable).
> * **Location**: Choose the appropriate location.
>
> **Step 4**
>
> Select **Create** and wait for the project to be created.
>
> **Step 5**
>
> Verify you're in the correct project by checking the project name next to the Google logo.
>
> ### Step 2: Enable the Google Calendar API
>
> **Step 1**
>
> In the Google Cloud Console, open the left sidebar and go to **API & Services > Credentials**.
>
> **Step 2**
>
> Select **+ Create Credentials > API Key** to create an API key. Copy and store it somewhere.
>
> **Step 3**
>
> Go to **Library**, search for "Google Calendar API", and select **Enable**.
>
> ### Step 3: Create a service account
>
> **Step 1**
>
> Open the left sidebar again and go to **API & Services > Credentials**.
>
> **Step 2**
>
> Select **+ Create Credentials > Service Account**.
>
> **Step 3**
>
> Enter a **Service account name**. The Service Account ID will be automatically generated.
>
> **Step 4**
>
> The remaining fields are optional. Select **Done** to create the service account.
>
> **Step 5**
>
> Select your newly created service account, then go to the **Keys** tab.
>
> **Step 6**
>
> Select **Add Key > Create new key**, choose **JSON** as the key type, then select **Create**.
>
> A JSON file will be downloaded to your machine. Keep this file secure—you'll need it to configure the integration.
>
> > [!NOTE]
> >
> > The downloaded JSON file contains sensitive credentials. Store it securely and never share it publicly. The file structure looks like this:
> >
> > ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > {
> >   "type": "service_account",
> >   "project_id": "your-project-id",
> >   "private_key_id": "...",
> >   "private_key": "...",
> >   "client_email": "your-service-account@your-project.iam.gserviceaccount.com",
> >   "client_id": "...",
> >   "auth_uri": "...",
> >   "token_uri": "...",
> >   "auth_provider_x509_cert_url": "...",
> >   "client_x509_cert_url": "...",
> >   "universe_domain": "googleapis.com"
> > }
> > ```
>
> ### Step 4: Enable domain-wide delegation (Google Workspace only)
>
> > [!WARNING]
> >
> > Domain-wide delegation is **required** if you want your bot to:
> >
> > * Create Google Meet links for events
> > * Send invitations to attendees
> > * Act on behalf of users in your organization
> >
> > Without domain-wide delegation, the service account can only manage its own calendar and cannot invite attendees or create Meet links.
> >
> > **This feature is only available for Google Workspace accounts.** Personal `@gmail.com` accounts do not support domain-wide delegation.
>
> Follow Google's official guide to [delegate domain-wide authority to your service account](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority).
>
> When configuring the OAuth scopes in the Google Admin Console, paste in the following scopes (comma-separated):
>
> ```
> https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/calendar.events
> ```
>
> ### Step 5: Configure OAuth consent screen (if not already configured)
>
> **Step 1**
>
> Open the left sidebar again and go to **API & Services > OAuth consent screen**.
>
> **Step 2**
>
> Select **Get started**.
>
> **Step 3**
>
> Configure the OAuth consent screen. Under **App Information**:
>
> * **App name**: Enter a name for your application.
> * **User support email**: Select your email address.
>
> Then, select **Next**.
>
> **Step 4**
>
> Under **Audience**, select **Internal**. Then, select **Next**.
>
> **Step 5**
>
> Under **Contact Information**, enter a contact email address. Then, select **Next**.
>
> **Step 6**
>
> Agree to the Google API policy, then select **Create**.
>
> ### Step 6: Create OAuth client
>
> **Step 1**
>
> Select **Create OAuth client**.
>
> **Step 2**
>
> Select an **Application type** and enter a name. Then select **Create**.
>
> ### Step 7: Configure scopes
>
> **Step 1**
>
> Go to **Data Access** in the left sidebar, then select **Add or remove scopes**.
>
> **Step 2**
>
> Add the following scopes:
>
> * `https://www.googleapis.com/auth/calendar`
> * `https://www.googleapis.com/auth/calendar.events`
>
> **Step 3**
>
> Select **Update**.
>
> ### Step 8: Grant calendar access to the service account
>
> **Step 1**
>
> Open [Google Calendar](https://calendar.google.com) and select the settings icon in the upper-right corner. Then, select **Settings**.
>
> **Step 2**
>
> In the left sidebar, select the calendar you want to share with your bot.
>
> **Step 3**
>
> Go to **Shared with** > **+ Add people and groups**.
>
> **Step 4**
>
> Enter the `client_email` from your downloaded JSON file (for example, `your-service-account@your-project.iam.gserviceaccount.com`).
>
> **Step 5**
>
> Set the permission to **Make changes to events** so the bot can manage calendar events.
>
> ### Step 9: Configure the integration in Botpress
>
> **Step 1**
>
> In Botpress Studio, select **Explore Hub** in the upper-right corner.
>
> **Step 2**
>
> Search for the **Google Calendar** integration, then select **Install Integration**.
>
> **Step 3**
>
> In the **Configuration** menu, select the drop-down and choose **Configure manually**.
>
> Fill in the integration's configuration fields:
>
> > [accordion] Calendar ID
> >
> > 1. In Google Calendar, go to **Settings** and select your calendar.
> > 2. Scroll to **Integrate calendar** to find your Calendar ID.
> > 3. Copy the Calendar ID and paste it into the **Calendar ID** field in Botpress.
>
> > [accordion] Client Email
> >
> > Open the JSON file you downloaded in [Step 3](#step-3-create-a-service-account) and copy the `client_email` value.
>
> > [accordion] Private Key
> >
> > Open the JSON file you downloaded in [Step 3](#step-3-create-a-service-account) and copy the entire `private_key` value, including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` markers.
>
> > [accordion] Impersonate Email (Google Workspace only)
> >
> > Enter the email address of a user in your Google Workspace that the service account will impersonate.
> >
> > This field is **required** for:
> >
> > * Creating Google Meet links
> > * Sending attendee invitations
> >
> > The email must belong to an actual user in your Google Workspace domain. Without this field configured, Meet creation and attendee invitations will not work.
> >
> > > [!NOTE]
> > >
> > > This field only applies if you have configured [domain-wide delegation](#step-4-enable-domain-wide-delegation-google-workspace-only). Personal @gmail.com accounts do not support impersonation.
>
> When you've filled in all the fields, select **Save Configuration**.
>
> > [!TIP]
> >
> > You've successfully configured the Google Calendar integration!

***

## Limitations

Different Google account types have different capabilities when using this integration.

| Feature | Google Workspace | Personal (`@gmail.com`) |
| - | :-: | :-: |
| Create, read, update, delete events | Yes | Yes |
| Create Google Meet links | Yes | No |
| Invite attendees | Yes ([requires domain-wide delegation](#step-4%3A-enable-domain-wide-delegation-google-workspace-only)) | No |

***

## Cards

{/* vale off */}

Here's a reference for all [Cards](https://botpress.com/docs/studio/concepts/cards/introduction.md) available with the integration:

### Check Availability

Checks calendar availability and returns free time slots for the specified date range.

**input** `object`

**timeMin** `string` *required*

Start of the time range to check (ISO 8601 format, e.g., "2025-11-05T09:00:00-04:00").

**timeMax** `string` *required*

End of the time range to check (ISO 8601 format, e.g., "2025-11-05T17:00:00-04:00").

**slotDurationMinutes** `number` (default: 45)

Duration of each time slot in minutes. Defaults to 45 minutes.

**timezone** `string` (default: America/Toronto)

Timezone for formatting output (e.g., "America/Toronto"). Defaults to America/Toronto.

**output** `object`

**freeSlots** `array` *required*

Array of available time slots in ISO format.

**array item properties**

**start** `string` *required*

ISO 8601 formatted start time of the free slot.

**end** `string` *required*

ISO 8601 formatted end time of the free slot.

**formattedFreeSlots** `array` *required*

Array of human-readable formatted free slots (e.g., "9:00 AM – 9:45 AM").

**busySlots** `array` *required*

Array of busy time slots in ISO format.

**array item properties**

**start** `string` *required*

ISO 8601 formatted start time of the busy slot.

**end** `string` *required*

ISO 8601 formatted end time of the busy slot.

### Create Event

Creates a new event in the calendar.

**input** `object`

The definition of the new event.

**summary** `string` *required*

Title of the event.

**description** `string`

Description of the event. Can contain HTML. Optional.

**location** `string`

Geographic location of the event as free-form text. Optional. (e.g., "Meeting Room").

**startDateTime** `string` *required*

The start date and time in RFC3339 format (e.g., "2023-12-31T10:00:00.000Z").

**endDateTime** `string` *required*

The end date and time in RFC3339 format (e.g., "2023-12-31T12:00:00.000Z").

**colorId** `string`

The color ID of the event. Optional.

**guestsCanInviteOthers** `boolean` (default: true)

Whether attendees other than the organizer can invite others to the event. Optional. The default is True.

**guestsCanSeeOtherGuests** `boolean` (default: true)

Whether attendees other than the organizer can see who the event's attendees are. Optional. The default is True.

**recurrence** `array`

List of RRULE, EXRULE, RDATE and EXDATE lines for a recurring event, as specified in RFC5545. This field is omitted for single events or instances of recurring events.

**status** `enum\<string\>` (default: confirmed)

Status of the event. Optional. The default value is "confirmed".

Available options: `confirmed`, `tentative`, `cancelled`

**visibility** `enum\<string\>` (default: default)

Visibility of the event. Optional. The default value is "default".

Available options: `default`, `public`, `private`, `confidential`

**enableGoogleMeet** `boolean` (default: false)

Whether to enable Google Meet for the event. Optional. The default value is false.

**sendNotifications** `boolean` (default: true)

Whether to send notifications to attendees. Optional. The default value is true.

**attendees** `array`

List of attendees for the event. Email invitations will be sent automatically.

**array item properties**

**email** `string (email)` *required*

The email address of the attendee.

**displayName** `string`

The name of the attendee. Optional.

**optional** `boolean` (default: false)

Whether this is an optional attendee. Optional. The default is False.

**output** `object`

The data of the new event.

**id** `string` *required*

Opaque identifier of the event.

**summary** `string` *required*

Title of the event.

**description** `string`

Description of the event. Can contain HTML. Optional.

**location** `string`

Geographic location of the event as free-form text. Optional. (e.g., "Meeting Room").

**startDateTime** `string` *required*

The start date and time in RFC3339 format (e.g., "2023-12-31T10:00:00.000Z").

**endDateTime** `string` *required*

The end date and time in RFC3339 format (e.g., "2023-12-31T12:00:00.000Z").

**colorId** `string`

The color ID of the event. Optional.

**eventType** `enum\<string\>` *required*

Specific type of the event. This cannot be modified after the event is created.

Available options: `default`, `birthday`, `focusTime`, `fromGmail`, `outOfOffice`, `workingLocation`

**guestsCanInviteOthers** `boolean` (default: true)

Whether attendees other than the organizer can invite others to the event. Optional. The default is True.

**guestsCanSeeOtherGuests** `boolean` (default: true)

Whether attendees other than the organizer can see who the event's attendees are. Optional. The default is True.

**htmlLink** `string` *required*

URL of the event page in the Google Calendar Web UI.

**recurrence** `array`

List of RRULE, EXRULE, RDATE and EXDATE lines for a recurring event, as specified in RFC5545. This field is omitted for single events or instances of recurring events.

**status** `enum\<string\>` (default: confirmed)

Status of the event. Optional. The default value is "confirmed".

Available options: `confirmed`, `tentative`, `cancelled`

**visibility** `enum\<string\>` (default: default)

Visibility of the event. Optional. The default value is "default".

Available options: `default`, `public`, `private`, `confidential`

**enableGoogleMeet** `boolean` (default: false)

Whether to enable Google Meet for the event. Optional. The default value is false.

**sendNotifications** `boolean` (default: true)

Whether to send notifications to attendees. Optional. The default value is true.

**attendees** `array`

List of attendees for the event. Email invitations will be sent automatically.

**array item properties**

**email** `string` *required*

The email address of the attendee.

**displayName** `string`

The name of the attendee. Optional.

**optional** `boolean` (default: false)

Whether this is an optional attendee. Optional. The default is False.

**responseStatus** `enum\<string\>`

The attendee's response status. Read-only when creating events.

Available options: `needsAction`, `declined`, `tentative`, `accepted`

**conferenceLink** `string`

The Google Meet link for the event. This is automatically generated when enableGoogleMeet is true.

### Delete Event

Deletes an event from the calendar.

**input** `object`

**eventId** `string` *required*

The ID of the calendar event to delete.

**output** `object`

This Card has no output.

### List Events

Retrieves events from the calendar.

**input** `object`

**count** `number` (default: 100)

The maximum number of events to return. Defaults to 100.

**pageToken** `string`

Token specifying which result page to return.

**timeMin** `string`

Only return events occurring on or after this date. Must be in RFC3339 format. Defaults to now if not specified.

**output** `object`

**events** `array` *required*

The list of calendar events.

**array item properties**

**id** `string` *required*

Opaque identifier of the event.

**summary** `string` *required*

Title of the event.

**description** `string`

Description of the event. Can contain HTML. Optional.

**location** `string`

Geographic location of the event as free-form text. Optional. (e.g., "Meeting Room").

**startDateTime** `string` *required*

The start date and time in RFC3339 format (e.g., "2023-12-31T10:00:00.000Z").

**endDateTime** `string` *required*

The end date and time in RFC3339 format (e.g., "2023-12-31T12:00:00.000Z").

**colorId** `string`

The color ID of the event. Optional.

**eventType** `enum\<string\>` *required*

Specific type of the event. This cannot be modified after the event is created.

Available options: `default`, `birthday`, `focusTime`, `fromGmail`, `outOfOffice`, `workingLocation`

**guestsCanInviteOthers** `boolean` (default: true)

Whether attendees other than the organizer can invite others to the event. Optional. The default is True.

**guestsCanSeeOtherGuests** `boolean` (default: true)

Whether attendees other than the organizer can see who the event's attendees are. Optional. The default is True.

**htmlLink** `string` *required*

URL of the event page in the Google Calendar Web UI.

**recurrence** `array`

List of RRULE, EXRULE, RDATE and EXDATE lines for a recurring event, as specified in RFC5545. This field is omitted for single events or instances of recurring events.

**status** `enum\<string\>` (default: confirmed)

Status of the event. Optional. The default value is "confirmed".

Available options: `confirmed`, `tentative`, `cancelled`

**visibility** `enum\<string\>` (default: default)

Visibility of the event. Optional. The default value is "default".

Available options: `default`, `public`, `private`, `confidential`

**enableGoogleMeet** `boolean` (default: false)

Whether to enable Google Meet for the event. Optional. The default value is false.

**sendNotifications** `boolean` (default: true)

Whether to send notifications to attendees. Optional. The default value is true.

**attendees** `array`

List of attendees for the event. Email invitations will be sent automatically.

**array item properties**

**email** `string` *required*

The email address of the attendee.

**displayName** `string`

The name of the attendee. Optional.

**optional** `boolean` (default: false)

Whether this is an optional attendee. Optional. The default is False.

**responseStatus** `enum\<string\>`

The attendee's response status. Read-only when creating events.

Available options: `needsAction`, `declined`, `tentative`, `accepted`

**conferenceLink** `string`

The Google Meet link for the event. This is automatically generated when enableGoogleMeet is true.

**nextPageToken** `string`

Token used to access the next page of this result. Omitted if no further results are available.

### Update Event

Updates an existing event in the calendar. Omitted properties are left unchanged.

**input** `object`

**id** `string` *required*

The ID of the calendar event to update.

**summary** `string` *required*

Title of the event.

**description** `string`

Description of the event. Can contain HTML. Optional.

**location** `string`

Geographic location of the event as free-form text. Optional. (e.g., "Meeting Room").

**startDateTime** `string` *required*

The start date and time in RFC3339 format (e.g., "2023-12-31T10:00:00.000Z").

**endDateTime** `string` *required*

The end date and time in RFC3339 format (e.g., "2023-12-31T12:00:00.000Z").

**colorId** `string`

The color ID of the event. Optional.

**guestsCanInviteOthers** `boolean` (default: true)

Whether attendees other than the organizer can invite others to the event. Optional. The default is True.

**guestsCanSeeOtherGuests** `boolean` (default: true)

Whether attendees other than the organizer can see who the event's attendees are. Optional. The default is True.

**recurrence** `array`

List of RRULE, EXRULE, RDATE and EXDATE lines for a recurring event, as specified in RFC5545. This field is omitted for single events or instances of recurring events.

**status** `enum\<string\>` (default: confirmed)

Status of the event. Optional. The default value is "confirmed".

Available options: `confirmed`, `tentative`, `cancelled`

**visibility** `enum\<string\>` (default: default)

Visibility of the event. Optional. The default value is "default".

Available options: `default`, `public`, `private`, `confidential`

**enableGoogleMeet** `boolean` (default: false)

Whether to enable Google Meet for the event. Optional. The default value is false.

**sendNotifications** `boolean` (default: true)

Whether to send notifications to attendees. Optional. The default value is true.

**attendees** `array`

List of attendees for the event.

**array item properties**

**email** `string (email)` *required*

The email address of the attendee.

**displayName** `string`

The name of the attendee. Optional.

**optional** `boolean` (default: false)

Whether this is an optional attendee. Optional. The default is False.

**output** `object`

The data of the event.

**id** `string` *required*

Opaque identifier of the event.

**summary** `string` *required*

Title of the event.

**description** `string`

Description of the event. Can contain HTML. Optional.

**location** `string`

Geographic location of the event as free-form text. Optional. (e.g., "Meeting Room").

**startDateTime** `string` *required*

The start date and time in RFC3339 format (e.g., "2023-12-31T10:00:00.000Z").

**endDateTime** `string` *required*

The end date and time in RFC3339 format (e.g., "2023-12-31T12:00:00.000Z").

**colorId** `string`

The color ID of the event. Optional.

**eventType** `enum\<string\>` *required*

Specific type of the event. This cannot be modified after the event is created.

Available options: `default`, `birthday`, `focusTime`, `fromGmail`, `outOfOffice`, `workingLocation`

**guestsCanInviteOthers** `boolean` (default: true)

Whether attendees other than the organizer can invite others to the event. Optional. The default is True.

**guestsCanSeeOtherGuests** `boolean` (default: true)

Whether attendees other than the organizer can see who the event's attendees are. Optional. The default is True.

**htmlLink** `string` *required*

URL of the event page in the Google Calendar Web UI.

**recurrence** `array`

List of RRULE, EXRULE, RDATE and EXDATE lines for a recurring event, as specified in RFC5545. This field is omitted for single events or instances of recurring events.

**status** `enum\<string\>` (default: confirmed)

Status of the event. Optional. The default value is "confirmed".

Available options: `confirmed`, `tentative`, `cancelled`

**visibility** `enum\<string\>` (default: default)

Visibility of the event. Optional. The default value is "default".

Available options: `default`, `public`, `private`, `confidential`

**enableGoogleMeet** `boolean` (default: false)

Whether to enable Google Meet for the event. Optional. The default value is false.

**sendNotifications** `boolean` (default: true)

Whether to send notifications to attendees. Optional. The default value is true.

**attendees** `array`

List of attendees for the event. Email invitations will be sent automatically.

**array item properties**

**email** `string` *required*

The email address of the attendee.

**displayName** `string`

The name of the attendee. Optional.

**optional** `boolean` (default: false)

Whether this is an optional attendee. Optional. The default is False.

**responseStatus** `enum\<string\>`

The attendee's response status. Read-only when creating events.

Available options: `needsAction`, `declined`, `tentative`, `accepted`

**conferenceLink** `string`

The Google Meet link for the event. This is automatically generated when enableGoogleMeet is true.

***

## Triggers

{/* vale off */}

Here's a reference for all [Triggers](https://botpress.com/docs/studio/concepts/triggers.md) available with the integration:

> [!TIP]
>
> You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.

### Event Created

**payload** `object`

**item** `string` *required*

### Event Deleted

**payload** `object`

**id** `string` *required*

### Event Updated

**payload** `object`

**item** `string` *required*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.