Skip to main content

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[] with source=google.

How it works​

Auth model: OAuth. Connect from Settings → Integrations → Google Calendar. The OAuth client (GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET) stores access_token, refresh_token, and redirect_uri on the ms-ai integration record. Tokens auto-refresh: the client subscribes to the Google tokens event and persists any rotated refresh token. The granted scopes cover read/write of calendar.events and the calendar list (the consent screen drives the exact scope grant).

Direction: outbound (Knock Knock creates events). There is no inbound webhook from Google — events created directly in Google Calendar do not flow back into Knock Knock.

Booking flow:

  1. The AI agent or visitor triggers "Book a meeting".
  2. ms-ai's calendar router asks Google for events in a window (from the visitor's local time, ~2 days out) via events.list (singleEvents, orderBy=startTime).
  3. Free slots are computed from the booked events and presented (30-minute default).
  4. The visitor picks a slot; a final availability re-check runs to avoid double-booking.
  5. The event is inserted on the primary calendar (events.insert) with summary, start/end.dateTime, company timeZone, the visitor's email as an attendee, and (for voice calls) conversation notes as the description.
  6. Google sends its standard invitation email and (by default) attaches a Google Meet link.
  7. The booking is unified onto PersonProfile.bookings[] (source=google).

getStatus() verifies the connection by listing one calendar (calendarList.list({ maxResults: 1 })) and returns { connected, reason }.

Configuration & options​

ItemDetail
ConnectSettings → Integrations → Google Calendar (OAuth)
EndpointPOST /integrations/actions/google-calendar (OAuth callback / create-update)
Default slot length30 minutes
Meeting linkGoogle Meet auto-generated; can be replaced per event type (e.g. always use a Zoom link)
Booking targetThe connected user's calendar (one default user per company)

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).
  • No reverse sync: bookings made directly in Google Calendar do not appear in the Knock Knock dashboard — only widget-initiated bookings do. 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: ms-ai — src/integrations/actions/google-calendar/google-calendar.service.ts + .controller.ts. Uses googleapis Calendar v3.
  • Unified calendar router: src/integrations/actions/calendar/calendar-router.service.ts (checkAvailability / bookMeeting) routes across google-calendar, ghl-calendar, and calendly.
  • Env: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET.

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.