ContextQMD
Back to Botpress

Hub

integrations/googlecalendar/hub.md

12.30.910.0 KB
Original Source

The Google Calendar Integration allows you to seamlessly interact with Google Calendar within your Botpress bot. This integration provides various actions to manage calendar events, enhancing the functionality of your bot.

Important note

Unfortunately, automatic configuration is temporarily unavailable. We are currently in the process of getting our Google Calendar integration verified by Google. Once this verification is complete, you will be able to use the automatic configuration method to set up the Google Calendar integration with just a few clicks. Until then, you will need to create your own Google Cloud Platform (GCP) Service Account by following the steps outlined in the Manual configuration using a service account section below.

Migrating from version 0.x to 1.x

If you are migrating from version 0.x to 1.x, please note the following changes:

The integration now supports both OAuth and service account authentication methods. If you wish to continue using a service account key, you will need to select Configure manually with a Service Account Key in the configuration dropdown menu and reconfigure the integration. See the Manual configuration using a service account section down below for more information.

When creating or updating calendar events, you can now optionally specify the recurrence and visibility settings for the event. These new fields are also now being returned when listing events.

When creating or updating events, the ISO 8601 date-time format is now fully supported and it is no longer necessary to input dates as RFC 3339 strings.

Migrating from version 1.x to 2.x

If you are migrating from version 1.x to 2.x, please note the following changes:

The integration has been refactored to remove the generic CRUD interface actions and de-duplicate redundant actions. The action names have changed from the previous interface-based naming convention. You will need to update any workflows or code that references the old action names:

  • eventCreate → createEvent
  • eventDelete → deleteEvent
  • eventList → listEvents
  • eventUpdate → updateEvent
  • eventRead has been removed (use listEventsinstead)

Configuration

Automatic configuration with OAuth (recommended)

To set up the Google Calendar integration using OAuth, click the authorization button and follow the on-screen instructions to connect your Botpress chatbot to Google Calendar.

When using this configuration mode, a Botpress-managed Google Calendar application will be used to connect to your Google account. However, actions taken by the bot will be attributed to the user who authorized the connection, rather than the application. For this reason, we do not recommend using personal Google accounts for this integration. You should set up a service account and use this account to authorize the connection.

Once the connection is established, you must specify the identifier of the calendar you want to interact with. This identifier can be found by navigating to the calendar in Google Calendar and opening the settings for that calendar. Once in the settings, you will find the Calendar ID in the Integrate calendar section. This is the value you need to provide in the configuration.

  1. Find your Google Calendar ID for the calendar you want to interact with.
  2. Authorize the Google Calendar integration by clicking the authorization button.
  3. Fill in the Calendar ID field and save the configuration.

Manual configuration using a service account

Creating a Google Cloud Platform project

  1. Go to the Google Cloud Console.
  2. Create a new project by clicking the Select a resource dropdown in the top navigation bar and selecting New Project.
  3. Follow the on-screen instructions to create the new project.

Enabling the Google Calendar API

  1. In the Google Cloud Console, navigate to the APIs & Services section.
  2. Click on Library in the left sidebar.
  3. Search for Google Calendar API and click on the result.
  4. Click the Enable button to enable the Google Calendar API for your project.

Creating a service account

  1. In the Google Cloud Console, navigate to the IAM & Admin section.
  2. Click on Service Accounts in the left sidebar.
  3. Click the Create service account button.
  4. Enter a name for the service account. This should automatically fill the Service account ID field.
  5. Click Done to proceed. There is no need to grant any roles or permissions at this stage.

Downloading the service account credentials file

  1. In the Google Cloud Console, navigate to the IAM & Admin section.
  2. Click on Service Accounts in the left sidebar.
  3. Select the service account you created previously.
  4. Click on the Keys tab.
  5. Click the Add Key button and select JSON.
  6. A JSON file containing the service account credentials will be downloaded to your computer. Save this file in a secure location, as it contains sensitive information. You will need this file to configure the Google Calendar integration in Botpress.

Locating your service account email and private key

  1. Open the downloaded JSON file in a text editor.
  2. Look for the client_email field. This is the email address of the service account you created. Copy the email address, excluding the quotation marks. You will need this email address to share your calendar with the service account and to configure the integration in Botpress.
  3. Look for the private_key field. This is the private key associated with the service account. Copy the private key, excluding the quotation marks. You will need this private key to configure the integration in Botpress.

    This public key begins with -----BEGIN PRIVATE KEY-----\n and ends with \n-----END PRIVATE KEY-----\n. You must copy the entire key: everything that is between the quotation marks.

Sharing your calendar with the service account

  1. Open Google Calendar in your web browser.
  2. Find the calendar you want to access on Botpress.
  3. Click on the three dots next to the calendar name and select Settings and sharing.
  4. In the Shared with section, click on Add people.
  5. Enter the service account email address (found in the downloaded JSON file) and select the appropriate permissions: Make changes to events.

Please note: your organization may have restrictions on sharing calendars with external users. If you are unable to share the calendar with the service account email address, you may need to use a different account or ask your organization's administrator for help.

Locating your calendar ID

  1. Open Google Calendar in your web browser.
  2. Find the calendar you want to access on Botpress.
  3. Click on the three dots next to the calendar name and select Settings and sharing.
  4. In the Integrate calendar section, you will find the Calendar ID. You will need this ID to configure the integration in Botpress.

Configuring the Google Calendar integration in Botpress

  1. Install this integration in your bot with the following configuration:
    • Calendar ID: The ID of the Google Calendar to interact with.
    • Service account private key: The private key from the Google service account. You can get it from the downloaded JSON file.
    • Service account email: The client email from the Google service account. You can get it from the downloaded JSON file.
    • Impersonate email (optional but required for certain features): The email address of the user to impersonate. See the "Using impersonateEmail" section below for details.

Using impersonateEmail

The impersonateEmail field is required for Google Meet creation and attendee invitations. This field must correspond to an email address of a person actually in your Google Workspace.

When to use impersonateEmail:

  • Required for: Creating events with Google Meet links and inviting attendees to events
  • Not required for: Creating simple events without meetings or attendees, reading calendar events. If you set it up without configuring the Domain-Wide Delegation, the integration won't configure properly

How to configure:

  1. The impersonateEmail must be a valid email address of a user in your Google Workspace domain.
  2. The service account must have Domain-Wide Delegation enabled.
  3. The user whose email you're impersonating must exist in your Google Workspace and have appropriate calendar permissions.

Usage

Once the Google Calendar Integration is configured, you can use it to manage calendar events within your Botpress bot. Here are some common use cases:

  • Schedule appointments or events on Google Calendar.
  • Retrieve upcoming events and display them to users.
  • Update or delete events based on user requests.

The integration provides powerful capabilities to enhance your bot's scheduling and event management functionalities.

Configuring event recurrence

When creating or updating a calendar event, you can specify the recurrence settings for the event. The recurrence settings are defined using the RFC 5545 standard, which allows you to define complex recurrence patterns for events. Here are some examples of recurrence rules:

  • Repeat every day at the same time: RRULE:FREQ=DAILY
  • Repeat every day for the next 5 days: RRULE:FREQ=DAILY;COUNT=5
  • Repeat every week on Monday, Wednesday, and Friday: RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR
  • Repeat every month on the 15th: RRULE:FREQ=MONTHLY;BYMONTHDAY=15
  • Repeat every year on January 1st: RRULE:FREQ=YEARLY;BYMONTH=1;BYMONTHDAY=1
  • Repeat on the first Monday of every month: RRULE:FREQ=MONTHLY;BYDAY=1MO
  • Repeat every 2 weeks on Monday: RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=MO
  • Repeat daily until a specific date: RRULE:FREQ=DAILY;UNTIL=20261231T000000Z
  • Repeat every Monday, except for March 25, 2026: RRULE:FREQ=WEEKLY;BYDAY=MO;EXDATE=20260325T000000Z

You can use these recurrence rules to create events with complex repeating patterns. You may also use online RRULE generators to create custom recurrence rules for your events.