Documentation Bookings and calendars Google Calendar

Bookings integration

Google Calendar

Google Calendar integration overview
  • CategoryBookings
  • AuthOAuth
  • Scopes1

Overview

Google Calendar connects on /integrations in the dashboard. Click the GoogleCalendar card and the 'Connect Google Calender' modal opens with a single Connect action that starts a Google OAuth 2.0 flow. On consent, Google redirects back to MessageMind, the refresh token is stored against the connecting person, and the dedicated settings page at /ai-home/integrations/google-calendar opens for host-calendar selection and per-account options. Once connected the AI can read live availability on the chosen calendar and create events when a booking is confirmed in a conversation. Live change notifications arrive from Google as push notifications to the MessageMind webhook endpoints (POST /v1/webhooks/google-calendar for the original sync engine and POST /v1/webhooks/google-calendar-v2 for the v2 engine under features/messageMindCalendar/v2/googleSync), which keep the one-way display mirror of Google events inside the MessageMind calendar grid in step.

What MessageMind can do with it

  • Read the connected Google account's calendar list so the host can pick which calendar the AI books on.
  • Check live availability on the chosen calendar across a date window, honouring busy events and ignoring cancelled or free-marked ones.
  • Create a Google Calendar event when the AI confirms a booking in chat, with an optional attendee invite and an optional Google Meet link.
  • Mirror upcoming and recent Google events into the MessageMind calendar grid for display (one-way, best-effort), refreshed by push notifications from Google.
  • Edit or delete a mirrored Google event from inside MessageMind when the connected account is the event organiser.

Requirements

  • A MessageMind account on the Professional or Enterprise plan (the GoogleCalendar card is plan-gated in the dashboard).
  • A Google account with permission to grant Calendar access and to host events on the calendar the AI will book on.
  • Only one booking-capable calendar integration can be the active source at a time; another active booking integration must be removed before Google Calendar can take over.

How to connect

  1. In the MessageMind dashboard, open /integrations and click the GoogleCalendar card. The 'Connect Google Calender' modal opens.
  2. Click Connect. MessageMind starts the Google OAuth 2.0 flow and sends you to Google's consent screen.
  3. Sign in to Google and approve the Calendar permission (scope https://www.googleapis.com/auth/calendar.events) so MessageMind can read busy events and create bookings on your behalf.
  4. Google redirects back to MessageMind, which stores the refresh token on the connecting person's calendar settings and opens the dedicated settings page at /ai-home/integrations/google-calendar.
  5. On that settings page, pick the host calendar the AI should read and write against. The AI can now check availability and create bookings on that calendar.

Authentication and permissions

Mechanism
Google OAuth 2.0 with a long-lived refresh token stored per connected person. Tokens refresh automatically when the stored access token is near expiry. Live change notifications are delivered as Google Cloud push notifications (JSON body) to POST /v1/webhooks/google-calendar and POST /v1/webhooks/google-calendar-v2.
Credentials
Access token, refresh token, granted scope and account identity (id, email) stored on the person's calendar settings.

Required scopes

  • https://www.googleapis.com/auth/calendar.events

Available data and actions

Reads

  • The connected Google account's identity (id, email).
  • The list of calendars the account can see, so the host can pick which one the AI books on.
  • Events on the chosen host calendar inside a rolling window (around 30 days back and 90 days ahead) for the display mirror.
  • Live busy events on the chosen calendar when the AI checks availability for a slot.

Writes

  • New calendar events on the host calendar when the AI confirms a booking in a conversation, with the booker optionally added as an attendee and an optional Google Meet link.
  • Updates to a mirrored event's editable fields when the user edits it from the MessageMind grid.
  • Deletion of a mirrored event when the user deletes it from the MessageMind grid.

AI agent use cases

  • Quote a free slot inside a WhatsApp, Instagram or SMS thread by reading the host's live Google Calendar, then lock the slot in Google as the booking is confirmed.
  • Attach a Google Meet link to the created event so the booker gets a join URL alongside the confirmation.
  • Keep the host's existing Google Calendar as the source of truth: everything the AI books lands there, and anything already on the calendar blocks the AI from offering a conflicting slot.

Configuration

  • A host calendar must be selected per connected account on /ai-home/integrations/google-calendar. All AI reads and writes target the selected calendar for that account.
  • Google events marked free or workingElsewhere, and cancelled events, do not block availability.
  • The display mirror holds a rolling window around today (roughly 30 days of history, 90 days ahead); events outside that window are not stored in the grid.
  • Only one booking integration can be the active calendar source at a time; adding Google Calendar booking while another booking integration is active is refused.

Example workflows

Chat-driven booking into Google Calendar

  1. Customer asks for a time inside the chat thread.
  2. The AI reads the host's selected Google Calendar for busy events across the requested window.
  3. The AI quotes a free slot in the chat.
  4. Customer confirms and provides any required details.
  5. The AI creates the event on the host's Google Calendar, optionally attaches a Google Meet link and optionally invites the booker.
  6. The join URL and confirmation are posted back into the chat.
  7. Google sends a push notification to the MessageMind webhook so the mirror reflects the new event right away.

Limitations

  • The display mirror is one-way: changes made by the AI write to Google, but a change made directly in Google is reflected into MessageMind only on the next push notification or sync pass.
  • Access depends on the granted Google scopes and the selected host calendar. This connector does not expose calendar creation/deletion or calendar-level sharing controls.
  • Only the event organiser can fully edit or delete a mirrored event from inside MessageMind. Non-organiser copies allow a limited set of fields (RSVP, colour, notifications).
  • Private or confidential events on shared calendars appear as masked ('Busy') and cannot be edited from MessageMind.
  • Google Meet links can be minted only on calendars where the connected account can host Meet.
  • The GoogleCalendar card is plan-gated to Professional and Enterprise and will not open the connect modal on lower plans.

Troubleshooting

The AI never offers any slots after connecting Google.

Open /ai-home/integrations/google-calendar and confirm a host calendar is selected for the connected account, and that the account has at least one calendar it can read. Also check that the host has working hours configured; a host with no working hours is not bookable anywhere.

A booking lands on the wrong Google calendar.

The AI writes to the host calendar selected for that connected account. Open /ai-home/integrations/google-calendar and change the host calendar selection.

Events edited directly in Google take minutes to show up in MessageMind.

The mirror relies on Google's push notification to /v1/webhooks/google-calendar (or /v1/webhooks/google-calendar-v2 on the v2 engine). If the push channel has expired, the next scheduled sync pass picks the change up and re-arms the channel; reconnecting the account forces a fresh channel immediately.

The GoogleCalendar card will not open the connect modal.

The integration is gated to the Professional and Enterprise plans. Upgrade the workspace plan and reload /integrations.

Disconnect and reconnect

  • In the MessageMind dashboard, open /ai-home/integrations/google-calendar and disconnect the Google account. The stored refresh token is removed, the push notification channel is dropped and the mirror cache is purged for that account.
  • To reconnect, run the Google OAuth flow again from the GoogleCalendar card on /integrations. Existing events on Google are not touched by disconnecting; only the stored credentials and the mirror cache are removed.