Google Calendar integration

Bookings need a Google Calendar connection to function — the calendar is the operational source of truth for the staff. Our booking row holds the customer-relationship truth (who, why, lifecycle).

Connect

Configure the OAuth credentials once

An agency admin opens /dashboard/oauth-configs → New OAuth config → purpose GOOGLE_CALENDAR → paste Client ID + Client Secret from your Google Cloud project. The redirect URI is auto-computed:


/api/integrations/oauth/google_calendar/callback

Connect per-agency or per-client

/dashboard/integrations → Google Calendar card → Connect. OAuth popup → grant calendar.events scope → token persisted (AES-256-GCM encrypted).

Verify

Reload the integrations page — the card shows a connected account with the chosen default calendar.

What happens on a booking

The booking is recorded in your dashboard first (status: CONFIRMED).
An event is then created on the connected Google Calendar.
On success, the Google event is linked to the booking record.
On failure, the booking still saves but is tagged with a “Google sync failed” note in the dashboard so you can see what to clean up.

What happens on cancel

The Google Calendar event is deleted.
The booking status flips to CANCELLED with the reason recorded.
A booking_cancelled event is fired (subscribe via Webhooks).

Cancellations come from three places:

Dashboard → bookings table → Cancel button
Customer WhatsApp → cancel_booking_picker flow block
Hosted page cancel link → signed JWT in the URL

Multiple connected accounts

An agency can connect multiple Google Calendar accounts (e.g. one per staff member). The booking flow’s offer_slots block picks which account each booking lands on. The hosted page uses the agency’s “default” (oldest ACTIVE) account.