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 toBookingModelfor 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_meetinglead-scoring signal.
How it works
Sources
| Source | How |
|---|---|
| Widget booking flow | Visitor picks a slot inside the widget, powered by the configured calendar provider |
| Calendly | Calendly event embedded in the widget, or used externally — the invitee.created webhook still captures it |
| Cal.com | The tenant's picked Cal.com event type (API key); see Cal.com |
| Google Calendar | Direct Google Calendar OAuth booking flow; widget queries slots and creates events |
| Outlook Calendar | Microsoft Graph, default calendar; card hidden until MICROSOFT_* is set — see Outlook Calendar |
| GoHighLevel Calendar | GHL calendar selection (V2 supported), booking via embed; optional multi-calendar picker with per-calendar purposes |
| HubSpot Meetings | A HubSpot meeting link (hubspot.meeting_slug); HubSpot creates contact, CRM meeting and invite. No reschedule/cancel |
| Jobber | A Request + scheduled Assessment, 60-minute slots from working hours minus the Jobber schedule |
| Semble | Clinic appointments: patient picks appointment type × clinician (or any) × location; patient found/created in Semble, booking created there. See Semble |
| PracSuite | Same model as Semble for PracSuite clinics; no webhooks, 30-min poll. See PracSuite |
| ServiceM8 | A 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 |
| Manual | Admin 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:
- GHL with
calendar_id(andbooking_enabled !== false) - HubSpot Meetings (connected, meeting-link scope,
meeting_slug) - Calendly (
calendly_integration.connected_at) - Cal.com (
calcom_integration.event_type_id) - Google Calendar (
google_calendar_integration.redirect_uri) - Outlook (
outlook_calendar_integration.account_email) - GHL connected, no calendar
- Jobber · 9. Semble · 10. PracSuite · 11. ServiceM8 (≥1
booking_staff_uuids) 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. Carriesbooking_url(GHL slug) and, for GHL per-day caps,day_full: true. ms-comm answers the widget withGhlBookingMessageHelper.SLOT_TAKEN_MESSAGEorDAY_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 sharebooking_urlif present and offer a follow-up; the provider sentence is deliberately not echoed.- Lost-result retries (
6953e9336): for GHL, Calendly and Google,SchedulingServicepassesfind_call_bookings_atso a slot held by a booking this call/session already made is returned asalready_booked. Google, which never refuses overlaps, patches the attendee in place when the caller corrected their email (email_moved_from; the session row'scontact_emailis 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_ERRORas before.
Sync back from the calendar
| Provider | Mechanism |
|---|---|
| Calendly | invitee.created / invitee.canceled webhooks |
| GHL | Native Appointment webhooks (GhlWebhookQueueService) |
| Semble | Webhooks + SembleSyncJob (15 min) |
| PracSuite | PracSuiteSyncJob (30 min) |
| Google, Outlook, Cal.com | CalendarSyncJob (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, HubSpot | None — 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_purposeis required oncheck_calendar_availability/book_meetingand matched againstgo_high_level.multi_calendar_purposes; hidden calendars can't be booked. - Failures: a real conflict is
SLOT_TAKEN(+booking_urlfallback when the calendar has a slug); a retry that collides with the invitee's own just-created appointment returnsalready_booked: trueand 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 withINVALID_REQUESTbefore 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: trueshows 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
| Setting | Where | Effect |
|---|---|---|
companies.calendly_integration (event_type_uri, event_type_duration, tokens) | Integrations → Calendly | Calendly connection + default event |
companies.calendar_choice | Integrations → Booking calendar | Tenant's booking calendar ('' = automatic ladder) |
companies.google_calendar_integration.redirect_uri (tokens in the vault) | Integrations → Google Calendar | Google connection marker |
companies.calcom_integration.event_type_id | Integrations → Cal.com | Cal.com event type (bookable once set) |
companies.outlook_calendar_integration.{account_email,duration_minutes} | Integrations → Outlook Calendar | Outlook connection + meeting length |
companies.pracsuite.{appointment_types,clinicians,locations,enabled} | Integrations → PracSuite → Booking settings | What patients can book |
companies.servicem8.{booking_staff_uuids,job_duration_minutes,create_lead_job} | Integrations → ServiceM8 → Settings | Bookable staff, job length, lead Quote job |
companies.go_high_level.calendar_id | Integrations → GoHighLevel | Which GHL calendar to book against |
companies.go_high_level.booking_enabled | Integrations → GoHighLevel | Enable GHL widget booking |
companies.go_high_level.multi_calendar_{enabled,ids,purposes} | Integrations → GoHighLevel → Booking | Visitor-choosable calendars + AI purpose matching |
companies.hubspot.meeting_slug | Integrations → HubSpot → Configure | HubSpot meeting link the AI books on ('' = none) |
companies.semble.{appointment_types,clinicians,locations,enabled} | Integrations → Semble → Booking settings | What patients can book; enabled set on save |
companies.simpro.auto_schedule.* | Integrations → Simpro → Cost Centres | In-call technician booking |
companies.booking_button | Settings → Widget | Show the "Book a meeting" button |
lead_score.booked_meeting | Settings → Lead Scoring | Weight 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.outcomesupportsattended/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/lostspecifically 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_idif 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 ontoPersonProfileModel. - Models:
PersonProfileModel.bookings[](unified per-person),BookingModel(company-wide, withoutcomeenum). - 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 withknox-history-lookupfor "what was each booked lead's full journey?". - Subsystems: CRM Integration, Identity Graph, Session Recording.
Related
- Leads — Overview — booking as a lead source
- Lead Scoring —
booked_meetingweight - Recorded Sessions — the journey behind a booking
- CRM Integration · Identity Graph