Google Calendar
Audience: Sales, management, support, engineering · Where in app: Settings → Integrations → Google Calendar · Plan availability: All plans (verify)
Google Calendar lets visitors book a meeting against the team's real calendar without leaving the widget. The AI agent (or a "Book a meeting" button) shows genuine availability pulled from Google, the visitor picks a slot, and Knock Knock creates the event — with a Google Meet link and Google's standard invitation email — and lands the booking on the visitor's profile.
What it does
- Shows real availability from the connected Google Calendar.
- Creates a Calendar event (default 30 minutes) with the visitor as an attendee.
- Generates a Google Meet link and sends Google's standard invitation email.
- Unifies the booking onto
PersonProfile.bookings[]withsource=google.
How it works
Auth model: OAuth, owned by the backend (backend d2a31ae9f, ms-ai 2627f8533, ms-comm cd347b3, 2026-11-10). The consent flow still starts from ms-ai's integration screen, but ms-ai only forwards the code to backend POST /scheduling/google/{connect,status,disconnect}; the backend exchanges it (GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET) and keeps {access_token, refresh_token} in the credential vault (provider: 'google_calendar'). ms-ai stores only { connected, redirect_uri } (so agent tool gating and the card are unchanged), and ms-comm no longer writes Google tokens onto the company. "Connected?" is judged on companies.google_calendar_integration.redirect_uri (set at connect, unset on disconnect); never read a token to decide it. Rotated refresh tokens are persisted back to the vault.
Direction: both ways for our own bookings. Availability, booking, find, reschedule and cancel all go through backend /scheduling/* (scheduling/adapters/GoogleAdapter.js); the SCHEDULING_V2_GOOGLE switch and ms-ai's own Google booking path were removed. Events created directly in Google are still not imported, but CalendarSyncJob (every 15 min, schedular) re-reads each of our upcoming Google events and applies moves and deletions to bookings[] and the meetings mirror.
Booking flow:
- The AI agent or visitor triggers "Book a meeting"; the provider is the tenant's
calendar_choiceor the ladder (Google sits after Calendly and Cal.com). GoogleAdapterlists events in the window and computes free slots against company working hours on a grid of the calendar'sdefaultEventLength(_slotMinutes, 30-minute fallback).- On book it first looks for this caller's own event at that start (
find_call_bookings_at,6953e9336): same email → returned asalready_booked; a corrected email → the attendee is swapped in place (events.patch,sendUpdates: 'all') and the session row'scontact_emailcorrected — Google never refuses overlaps, so a retry used to create a second meeting. - Otherwise a final availability re-check, then
events.insertonprimarywith the visitor as attendee (Google sends the invite and, by default, a Meet link). - The booking is recorded by
BookingRecordService(booking_type: 'google',google_event_id).
Connection health: ms-ai's status call goes to backend POST /scheduling/google/status (lib/googleCalendar.status), which checks the vault tokens against Google; disconnect (lib/googleCalendar.disconnect) drops the vault record and the marker.
Configuration & options
| Item | Detail |
|---|---|
| Connect | Settings → Integrations → Google Calendar (OAuth) |
| Endpoints | ms-ai POST /integrations/actions/google-calendar (relays the code) → backend POST /scheduling/google/{connect,status,disconnect} |
| Slot / meeting length | Google's defaultEventLength (fallback 30); a voice caller's explicit request (5–480 min) overrides it on booking |
| Meeting link | Google Meet auto-generated; can be replaced per event type (e.g. always use a Zoom link) |
| Booking target | The connected user's calendar (one default user per company) |
Requested length (6121a0246, ms-ai 33c4f8d3b/863cb6c8c): POST /scheduling/book accepts duration_minutes and SchedulingService forwards it only to Google (GHL/Calendly/Jobber/HubSpot lengths are fixed by the calendar). GoogleAdapter._requestedMinutes rounds it and ignores anything outside 5–480, so the event is booked at what the visitor asked for instead of the AI confirming "your 30 minute call" and booking 60. ms-ai voice tools expose duration_minutes (only when the caller explicitly asked); the chat customDurationTools variant exists but isn't wired into an agent. The booking reply gives the agent the booked length and the time in the user's zone, and the meetings prompt tells Google/GHL agents to state the length book_meeting reports — never the one requested.
Behaviors & edge cases
- Time zones: slots are computed from the visitor's local time against your calendar's time zone — make sure the Google Calendar primary time zone matches your business hours, or busy hours won't block correctly.
- Blocking time: anything marked busy in Google Calendar blocks slots, including all-day events with
transparency=opaque(use for lunch/personal time). - Partial reverse sync: moves/deletes of our events are applied within ~15 min (
CalendarSyncJob); bookings made directly in Google Calendar still don't appear in the dashboard. Calendly's webhook approach is the closer equivalent if you need outside-the-widget bookings captured. - Round-robin / team availability: currently one default calendar per company; round-robin across multiple team calendars is roadmapped.
- Revoked tokens: auto-refresh handles normal expiry, but if a user revokes access at Google's end, reconnect is required.
Plan & limits
- Available on all plans (verify exact tier gating).
- Free/busy granularity is 1-minute, but the slot grid is fixed (usually 30 min).
Technical implementation
- Owning service:
backend—SchedulingController(googleConnect/googleStatus/googleDisconnect),scheduling/adapters/GoogleAdapter.js(googleapisCalendarv3),jobs/CalendarSyncJob.js,services/CredentialVault.js. - ms-ai:
src/integrations/actions/google-calendar/only relays the OAuth code;calendar-router.service.tssends every Google call to backend scheduling. - Env:
GOOGLE_CLIENT_ID,GOOGLE_CLIENT_SECRETin backend and schedular (the sync job refreshes tokens there).
What Nox can tell you
- Connection status.
- Recent Google Calendar bookings (
source=google). - Free/busy summary (via a tool call to the calendar).
Tools: knox-recent-bookings, knox-visitor-bookings.
Related
- Calendly · Cal.com · Outlook Calendar · GoHighLevel (GHL calendar) · Integrations Overview
- ms-ai