Skip to main content

Bookings — Sources & Unified View

Audience: Sales · Management · Support · QA · Engineering · Where in app: Settings → Integrations (calendar connections), Settings → Widget (booking button); bookings appear on Person Detail and the dashboard · Plan availability: All plans (a connected calendar provider is required for self-serve booking)

Bookings (a.k.a. meetings) can come from several sources — the in-widget booking flow, Calendly, Cal.com, Google Calendar, Outlook Calendar, GoHighLevel, HubSpot Meetings, Jobber, Semble, PracSuite, ServiceM8, or a manual admin add. The tenant picks which connected calendar is booked (companies.calendar_choice), falling back to an automatic ladder. Whatever the source, every booking is unified onto the visitor's Person so admins and the AI see one combined timeline: the booking, the session that produced it, the lead score at booking time, and the journey before it. booked_meeting is one of the highest-weight lead-scoring signals — a booking usually pushes a visitor straight over the hot threshold.

What it does​

  • Captures bookings from multiple calendar providers and the widget's own booking flow.
  • Unifies every booking onto PersonProfileModel.bookings[] and mirrors to BookingModel for fast company-wide queries.
  • Deduplicates near-identical bookings for the same person.
  • Attributes each booking to its originating session journey for Nox/reporting.
  • Sends new-booking notifications and feeds the booked_meeting lead-scoring signal.

How it works​

Sources​

SourceHow
Widget booking flowVisitor picks a slot inside the widget, powered by the configured calendar provider
CalendlyCalendly event embedded in the widget, or used externally — the invitee.created webhook still captures it
Cal.comThe tenant's picked Cal.com event type (API key); see Cal.com
Google CalendarDirect Google Calendar OAuth booking flow; widget queries slots and creates events
Outlook CalendarMicrosoft Graph, default calendar; card hidden until MICROSOFT_* is set — see Outlook Calendar
GoHighLevel CalendarGHL calendar selection (V2 supported), booking via embed; optional multi-calendar picker with per-calendar purposes
HubSpot MeetingsA HubSpot meeting link (hubspot.meeting_slug); HubSpot creates contact, CRM meeting and invite. No reschedule/cancel
JobberA Request + scheduled Assessment, 60-minute slots from working hours minus the Jobber schedule
SembleClinic appointments: patient picks appointment type × clinician (or any) × location; patient found/created in Semble, booking created there. See Semble
PracSuiteSame model as Semble for PracSuite clinics; no webhooks, 30-min poll. See PracSuite
ServiceM8A Work Order job + scheduled activity on the first free owner-ticked staff member. Beta, super-admin gated. See ServiceM8
Simpro (voice only)The voice agent books a technician on the Simpro job itself — not a meeting; see Simpro + Tapi
ManualAdmin adds a booking from the dashboard (rare)

Unified storage​

Every booking lands on PersonProfileModel.bookings[]:

{
source: "google" | "calendly" | "ghl" | "hubspot" | "jobber" | "semble" | "pracsuite" | "outlook" | "calcom" | "servicem8" | "manual",
booking_date,
booking_time,
duration_minutes,
attendees: [{ email, name }],
user_session_id, // session that triggered it
meeting_url, // Zoom / Google Meet / etc.
status: "scheduled" | "completed" | "cancelled" | "no-show",
created_at
}

It's also persisted on BookingModel for fast company-wide queries. Dedup: same Person + similar time (within 5 minutes) collapses to one entry — keyed on (person_id, time ± 5min).

Choosing the provider: calendar_choice and the ladder​

scheduling/resolveProvider.js is the single backend ladder (RUNGS; CompanyController uses it instead of its old copy). resolveProvider(company) returns the tenant's calendar_choice while isUsable(company, choice), else the first usable rung:

  1. GHL with calendar_id (and booking_enabled !== false)
  2. HubSpot Meetings (connected, meeting-link scope, meeting_slug)
  3. Calendly (calendly_integration.connected_at)
  4. Cal.com (calcom_integration.event_type_id)
  5. Google Calendar (google_calendar_integration.redirect_uri)
  6. Outlook (outlook_calendar_integration.account_email)
  7. GHL connected, no calendar
  8. Jobber · 9. Semble · 10. PracSuite · 11. ServiceM8 (≥1 booking_staff_uuids)
  9. custom_calender (custom booking URL)

Connection tests read markers only, never tokens (tokens live in the credential vault; a stale refresh token once let a disconnected Google outrank Calendly). ms-communication keeps exactly one mirror (helpers/SchedulingClientHelper.resolveProvider, which replaced the copies in CompanyContextHelper, CallsController and MessageController); change both together. ms-ai's CalendarRouterService.resolveCalendarType asks the backend for the tenant's calendar when calendar_type is blank (60 s cache), so phone calls book the chosen calendar too. Tenant UI and API: see Integrations Overview.

Booking failures​

Adapters throw a typed SchedulingError (scheduling/errors.js); callers switch on code:

  • SLOT_TAKEN (409) — real conflict. Carries booking_url (GHL slug) and, for GHL per-day caps, day_full: true. ms-comm answers the widget with GhlBookingMessageHelper.SLOT_TAKEN_MESSAGE or DAY_FULL_MESSAGE ("…that day is now fully booked. Please select another day…"), whose load-bearing opening makes the widget reopen and re-fetch the time sheet. ms-ai tells the model to re-run availability before offering another time.
  • BOOKING_REFUSED (422, b73e5cbfa) — GHL refused a slot it still lists as free (buffer, team member, cap race). ms-ai tells the model not to retry or guess other times, to share booking_url if present and offer a follow-up; the provider sentence is deliberately not echoed.
  • Lost-result retries (6953e9336): for GHL, Calendly and Google, SchedulingService passes find_call_bookings_at so a slot held by a booking this call/session already made is returned as already_booked. Google, which never refuses overlaps, patches the attendee in place when the caller corrected their email (email_moved_from; the session row's contact_email is corrected); Calendly recovers a booking made under a different email.
  • NEEDS_LINK, CALENDAR_REQUIRED, UNKNOWN_CALENDAR, NO_CALENDAR, AUTH_EXPIRED, INVALID_REQUEST, MEETING_NOT_FOUND, PROVIDER_ERROR as before.

Sync back from the calendar​

ProviderMechanism
Calendlyinvitee.created / invitee.canceled webhooks
GHLNative Appointment webhooks (GhlWebhookQueueService)
SembleWebhooks + SembleSyncJob (15 min)
PracSuitePracSuiteSyncJob (30 min)
Google, Outlook, Cal.comCalendarSyncJob (15 min, 225840d0d): re-reads each of our upcoming bookings (30 days ahead, ≤ 100 per company) and applies cancels/moves (> 1 min) to bookings[] and the meetings mirror
Jobber, ServiceM8, HubSpotNone — find/reschedule/cancel read the provider live, but bookings[] isn't updated for changes made there

Per-source mechanics​

Widget booking flow — visitor clicks "Book a meeting" (e.g. in AI chat or from a CTA) → slots fetched from the connected calendar → on selection the provider's API creates the event → confirmation to visitor + admin.

Calendly — OAuth via Settings → Integrations → Calendly; companies.calendly_integration stores tokens + event_type_uri + event_type_duration. The invitee.created webhook captures bookings even when Calendly is used outside the widget. A detected calendly.event_scheduled also counts as identity verification. The event type's invitee questions are asked in the widget sheet / by the AI and sent as invitee.answers; heuristics fill only unanswered required ones — see Calendly.

Calendly UTMs — every Knock Knock-made Calendly booking (direct POST /invitees or a shared booking link) carries utm_source (knock_knock_ai, or the agency-name slug for agency clients) and utm_content = user_session_id, which is also how invitee.created finds its session — see Calendly.

Google Calendar — OAuth via Settings → Integrations → Google Calendar. Since 2026-11-10 the backend owns it: ms-ai forwards the code to /scheduling/google/{connect,status,disconnect}, tokens are in the credential vault, ms-ai keeps only { connected, redirect_uri }, and every Google booking goes through backend /scheduling/* (the SCHEDULING_V2_GOOGLE switch and ms-ai's own Google path are gone). Meetings use Google's defaultEventLength, or the length a voice caller explicitly asked for (duration_minutes, 5–480 — Google and Outlook).

HubSpot Meetings — Settings → Integrations → HubSpot → Configure → AI agents book meetings on sets companies.hubspot.meeting_slug; needs the optional scheduler.meetings.meeting-link.read scope. Ladder rung right after a GHL calendar with calendar_id. Offline meeting links (is_offline) get a "team will confirm by email" reply. Session rows: booking_type: 'hubspot', hubspot_meeting_id (the CRM meeting id). See HubSpot.

GoHighLevel — OAuth via Settings → Integrations → GoHighLevel (UI now labels it LeadConnector); companies.go_high_level.calendar_id selects the calendar; companies.go_high_level.booking_enabled turns on widget booking. Supports GHL V2 forms, the new GHL calendar-selection UI, and embedding GHL calendars in the widget. (Handled by GoHighLevelService; see CRM Integration.)

POST /go-high-level/book-calendar also back-fills the GHL contact's phone (and mirrors an email back-fill) from what the visitor gave at booking — only when the CRM field is empty, never overwriting. Conversational-AI bookings (ms-ai book_meeting tool) send only email + user_session_id; phone/name fall back to the identity stamped on the user_session (phone_number/name, ignoring placeholder names like "Guest"), so chat-given details still land on the contact and the calendar's Phone field.

GHL booking behaviour since 2026-09 (details on GoHighLevel):

  • Length comes from the calendar's slotDuration (was a hardcoded 30, which GHL rejects on 45/60-minute calendars); times are rendered in the location's timezone.
  • Multi-calendar: the AI must learn the meeting purpose first — meeting_purpose is required on check_calendar_availability/book_meeting and matched against go_high_level.multi_calendar_purposes; hidden calendars can't be booked.
  • Failures: a real conflict is SLOT_TAKEN (+ booking_url fallback when the calendar has a slug); a retry that collides with the invitee's own just-created appointment returns already_booked: true and skips the second tenant notification. The widget's "no longer available" line (which reopens the calendar) is reserved for genuine conflicts.
  • Placeholder emails (user@example.com, test@test.com, …) are refused by ms-ai before any provider call.
  • Diagnostics: GHL booking requested/created/failed rows go into the session's chat log (ChatLogHelper, body.from_backend: true).
  • Description prints the real email (it used to print the contact id) and falls back to the matched contact's name/phone before Unknown; a malformed email is refused with INVALID_REQUEST before it's written onto the contact.

Semble — Settings → Integrations → Semble: clinic API token (SecretCrypto) + ticked appointment types / clinicians / locations (companies.semble). Last provider rung before the custom booking URL. Each combination is a calendar id <type>~<location>~<clinician|any>; the widget shows SembleChoicePicker (Location → Clinician → Appointment type), the agents compose the id from three prompt lists. Email or phone is enough. Session rows: booking_type: 'semble', semble_appointment_id. Moves/deletes made in Semble come back by webhook (BullMQ semble-webhook) or the 15-minute SembleSyncJob, applied only to our bookings. Widget slots/booking use backend's public /semble/availability + /semble/book (no BACKEND_API_KEY). See Semble.

Cal.com / Outlook / PracSuite / ServiceM8 — see their pages: Cal.com, Outlook Calendar, PracSuite, ServiceM8. All four go through backend /scheduling/* from ms-comm (getBackendAvailableSlots / TYPE_BY_PROVIDER, PracSuite via its public /pracsuite/* routes) and from ms-ai (calendar-types.ts).

Jobber — Request details are a Next Level AI section, the assessment's instructions and the request's Source item read "Booked via Next Level AI" (673ba43f8, was "Knock Knock").

Owner Meetings page and cancellation​

The frontend Meetings page (/meetings, MeetingsView.vue, sidebar under Calls with an upcoming-count badge from useUpcomingMeetingsCount) moved booked meetings out of a Calls tab (0814ce65; a stale ?tab=meetings redirects). It's owner / super-admin only (canSeeMeetings; the view redirects others to Calls). Since 0c247242 it has two views: List (agenda grouped by day, from = now − 60 min so a just-started meeting stays, paged 25 at a time with "Show later meetings") and Calendar (month grid incl. past days, from/to = the visible weeks, limit 500), a server-side contact search (q on name/email/phone) and a MeetingDetail side panel (Join meeting, Call/Text/Email, "View the visit that booked this", Cancel meeting). GET /company/meetings (699100770) takes optional from/to/q/limit (≤ 500)/skip; without from it is "upcoming from now"; non-cancelled user_sessions.bookings[], soonest first, max 1,000 candidates. POST /company/meetings/cancel { session_id, booking_type, provider_event_id } cancels through SchedulingService (PROVIDER_BY_TYPE: ghl/calendly/google/jobber/hubspot/semble/pracsuite/servicem8/outlook/calcom); cancellable is false for HubSpot, manual/legacy rows with no provider id, and meetings that have already started. Provider badges and "will notify the attendee" wording live in frontend utils/meetings.js MEETING_PROVIDERS. MEETING_NOT_FOUND at the provider marks the row cancelled anyway. Sub-users get 403 (CompanyMeetingsController._ownerCompanyId; registered in container.js, ee3758419).

Visitors cancel from the widget (Cancel a meeting sheet → ms-comm cancelMeeting), and the chat/voice agents via ms-ai's cancelMeeting tool — meeting id must come from a prior lookup, never retried.

Booking buttons in the widget​

  • companies.booking_button: true shows a "Book a meeting" button in the widget header.
  • The Welcome widget's Schedule Appointment CTA sets schedulingIntent + openCalendarOnChatOpen, so the chat opens with the booking calendar already up (only when the company has bookable slots; waits for the in-flight slot request instead of re-asking).
  • The AI chat agent can offer booking via a tool call ("Would you like to book a demo?").
  • The AI call agent can book during a voice call.

Configuration & options​

SettingWhereEffect
companies.calendly_integration (event_type_uri, event_type_duration, tokens)Integrations → CalendlyCalendly connection + default event
companies.calendar_choiceIntegrations → Booking calendarTenant's booking calendar ('' = automatic ladder)
companies.google_calendar_integration.redirect_uri (tokens in the vault)Integrations → Google CalendarGoogle connection marker
companies.calcom_integration.event_type_idIntegrations → Cal.comCal.com event type (bookable once set)
companies.outlook_calendar_integration.{account_email,duration_minutes}Integrations → Outlook CalendarOutlook connection + meeting length
companies.pracsuite.{appointment_types,clinicians,locations,enabled}Integrations → PracSuite → Booking settingsWhat patients can book
companies.servicem8.{booking_staff_uuids,job_duration_minutes,create_lead_job}Integrations → ServiceM8 → SettingsBookable staff, job length, lead Quote job
companies.go_high_level.calendar_idIntegrations → GoHighLevelWhich GHL calendar to book against
companies.go_high_level.booking_enabledIntegrations → GoHighLevelEnable GHL widget booking
companies.go_high_level.multi_calendar_{enabled,ids,purposes}Integrations → GoHighLevel → BookingVisitor-choosable calendars + AI purpose matching
companies.hubspot.meeting_slugIntegrations → HubSpot → ConfigureHubSpot meeting link the AI books on ('' = none)
companies.semble.{appointment_types,clinicians,locations,enabled}Integrations → Semble → Booking settingsWhat patients can book; enabled set on save
companies.simpro.auto_schedule.*Integrations → Simpro → Cost CentresIn-call technician booking
companies.booking_buttonSettings → WidgetShow the "Book a meeting" button
lead_score.booked_meetingSettings → Lead ScoringWeight for the booking signal (high)

Behaviors & edge cases​

  • Dedup is (person_id, time ± 5min) — two genuinely different meetings booked within 5 minutes of each other for the same person can collapse into one entry.
  • Outcome tracking is not auto-populated. BookingModel.outcome supports attended / no_show / cancelled / rescheduled / closed_won / closed_lost, but nothing writes attended/no-show automatically yet — it would require calendar webhooks or CRM stage syncs. closed_won/lost specifically needs CRM stage sync.
  • External-tool bookings (Calendly used outside the widget) are captured by webhook, so they may arrive without a tied user_session_id if the person can't be matched.
  • A booking is a top-weight score signal — expect a hot-lead notification to fire around most bookings.
  • Booking confirmations and reminders come from the calendar provider (Google/Calendly/Cal.com/Outlook/GHL), not Knock Knock. A Semble cancel from Knock Knock passes sendCancellationMessages: true, so Semble messages the patient. ServiceM8 sends nothing on cancel (the job is marked Unsuccessful with a note).

Plan & limits​

  • Bookings are supported on all plans, but self-serve widget booking requires a connected calendar provider (GHL / HubSpot meeting link / Calendly / Cal.com / Google / Outlook / Jobber / Semble / PracSuite / ServiceM8 / custom URL).
  • GHL bookings additionally require the GHL integration (V2 app) connected — see CRM Integration and the GHL integration page (v1 app retired).
  • Outcome write-back (attended / closed-won) is not yet available automatically.

Technical implementation​

  • Service: backend — GoHighLevelService (GHL calendars/booking), Calendly/Google OAuth + webhook handlers; booking write/dedup logic onto PersonProfileModel.
  • Models: PersonProfileModel.bookings[] (unified per-person), BookingModel (company-wide, with outcome enum).
  • Attribution: each booking links to its user_session_id, the full session journey (pages, conversations, friction), the lead score at booking time, and the traffic source — the basis for Nox journey questions.
  • Notifications: new booking → in-app + email (provider sends the visitor's confirmation/reminders).
  • Nox tools: knox-recent-bookings(window=24h|7d|30d), knox-visitor-bookings(person_id), combined with knox-history-lookup for "what was each booked lead's full journey?".
  • Subsystems: CRM Integration, Identity Graph, Session Recording.