Semble
Audience: Sales, support, engineering · Where in app: Settings → Integrations → Calendars & booking → Semble card ("Clinic Calendar") · Plan availability: All plans, no flag (always loaded)
Semble is clinic practice-management software. The integration books patient appointments into the clinic's Semble diary from the widget booking panel, the chat agent and the voice agent. It sits on the shared SchedulingService as one more calendar adapter, near the bottom of the automatic ladder (above PracSuite and ServiceM8).
What it does
- Connect with a clinic API token (Semble → Settings > API Access > New). The token is validated with the
practicequery, then stored in the credential vault (provider: 'semble', never returned). - Booking settings: the clinic ticks appointment types (Semble products with
productTypeappointment that are bookable), clinicians (non-deleted users, plus a synthetic General entry when the practice has availability with no clinician) and locations (Semble sites,PracticeLocation.groupId, not rooms). Names are snapshotted onto the company so listing choices never calls Semble. - Choices: every type × location × clinician is one bookable "calendar", plus "any available clinician" when more than one clinician is ticked (
services/semble/choices.js). The calendar id encodes the choice:<typeId>~<locationId>~<clinicianId|any>, so availability and booking need no other state. - Book / find / reschedule / cancel through
scheduling/adapters/SembleAdapter.js. - Sync back: booking moves and deletes made inside Semble are applied to our bookings by webhook.
SembleSyncJob(every 15 min) is the fallback.
How it works
Data (companies.semble, strict subdoc)
practice_id/name/timezone, locations[] {id,name}, appointment_types[] {id,name,duration}, clinicians[] {id,name}, enabled, connection_status (ok|error|expired), connection_error, last_verified_at, last_synced_at, webhook {id, status: active|paused|unavailable|failed, error, checked_at} (the API token and webhook secret are vault-only). The legacy environment enum is still in the schema but unused. Bookable = enabled + ≥1 type + ≥1 location + ≥1 clinician + connection_status !== 'expired' (isSembleBookable).
CompanyController exposes calendar_type: 'semble' and multi_calendar_enabled = sembleCalendars().length > 1 to the widget and strips the semble subdoc.
Routes (routes/sembleRoutes.js)
| Route | Auth | Purpose |
|---|---|---|
POST /semble/connect, /options, /settings, /status, /rotate-token, /disconnect, /backfill | passport (company managers) | Card + modal. settings re-checks the ticked ids against live Semble, sets enabled: true and calls ensureWebhook. rotate-token refuses a token for a different practice. backfill (no UI) re-syncs a date range. |
GET /semble/:company_id/booking-calendars | public | The widget's choice list (publicCalendar, with a choice object holding the three parts) |
POST /semble/availability, /semble/book | public, forceSembleCalendar middleware | Same SchedulingController handlers as /scheduling/* with calendar_type pinned to semble (8e38b412a) |
POST /webhooks/semble/:companyId | HMAC over the raw body | Bare 401 on any rejection |
The public slot/book routes exist because Semble originally only had the keyed /scheduling/* path, so a wrong BACKEND_API_KEY between ms-communication and backend broke Semble alone. Google (/google/calendar/*) and GHL (/go-high-level/*) never needed the key. ms-comm's SchedulingClientHelper.routeFor(op, type) sends Semble availability and booking to /semble/*. Meetings, reschedule and cancel stay on the keyed /scheduling/* (c8dbd9d).
Client (services/semble/SembleClient.js)
GraphQL POST to https://open.semble.io/graphql (live only. Sandbox was removed in 0d0d6076f) with an x-token header. Queries retry on 429/5xx/network. Mutations retry only on 429 and on connection errors where nothing was sent (ECONNREFUSED, ENOTFOUND, EAI_AGAIN), because a timed-out createBooking may have succeeded. Rate limit per clinic token: 10 req/s (SEMBLE_RATE_LIMIT_*). Logs carry only operation, status, duration and Semble's request id, never the token, variables or bodies (patient data). test/semble-operations.spec.js validates every operation against the checked-in schema (services/semble/schema.graphql, refreshed with scripts/semble-introspect.js) and asserts no clinical fields are requested.
Availability
SembleService.freeSlots asks availabilitySlots (≤ 28 days a call; Semble rejects start === end, so it asks through the next day and trims). It filters by clinician ids, or by site when "General" is involved, then splits windows into appointment-length starts in the practice timezone. If that returns nothing, the practice may be on Semble's older appointment system. legacyWindows then asks the deprecated availabilities query per room × clinician, in ≤ 168 h chunks and whole practice days, because Semble only returns windows lying entirely inside the range. Those times are practice wall-clock mislabelled as UTC. The adapter only offers starts that one of the chosen clinicians can take, and dedupes the same start across clinicians.
Booking (SembleAdapter.book)
- Needs an email or a phone (
supportsPhoneincludes Semble for lookups too). findOrCreatePatient: exact email match, then phone tail (last 9 digits) over Semble's fuzzy search. It never books onto a near-match. A new patient gets first/last name (last-when single-word), email and mobile.- Idempotent retry: if the patient already holds a booking at that exact start, it returns it with
already_booked: true. - Re-checks free slots for the exact start and picks a clinician inside the patient's choice (any-clinician picks whoever is free). Then it calls
createBookingon the slot's room (doctoromitted for General), with comment"<title> (booked via Knock Knock)"or"Booked via Knock Knock". Clash-like mutation errors map toSLOT_TAKEN. An auth error maps toAUTH_EXPIREDand flipsconnection_status: 'expired'. - The session booking is stored with
booking_type: 'semble'andsemble_appointment_id. Theuser_sessionsindex is{company_id, 'bookings.semble_appointment_id'}. Person bookingssource: 'semble'. Only ids are kept, with no patient record on our side.
Reschedule keeps the booking's clinician and refuses a time they aren't free (excludeBookingIds = the booking itself). Cancel is deleteBooking with sendCancellationMessages: true, so Semble messages the patient.
Sync back
- Webhooks:
ensureWebhooksubscribesbooking.updated,booking.deleted,webhook.subscription.updatedto<SEMBLE_WEBHOOK_BASE_URL or BASE_URL>/webhooks/semble/<companyId>(must be https, else statusunavailable). A missing token permission givesfailed. Deliveries are deduped oneventIdfor 24 h in Redis (semble_evt:*), then enqueued on BullMQsemble-webhook. The job id is the booking, with a 3 s collapse delay, 5 attempts and exponential backoff. The worker runs only in the scheduler pod (Bull Board/admin/queues). The worker re-reads the booking (webhooks carry ids only) andreconcileapplies it only to our bookings, matched byMeetingModel.provider_event_id. Delete givescancelByProviderId+ cancel notification ("Cancelled in Semble"). A moved start (> 1 min) givesrescheduleByProviderId+ reschedule notification. SembleSyncJob(scheduler,SEMBLE_SYNC_INTERVAL_MINUTES, default 15) re-readsbookingsChangedsincelast_synced_at(5 min overlap) for everyenabledand non-expired company. It also refreshes the practice timezone and the webhook's paused flag. Errors are per-company.- The card shows a note when the webhook is
paused,unavailableorfailed("changes made in Semble sync every 15 minutes").
AI agents (ms-ai)
calendar_type: 'semble' goes through the central backend scheduling path (like Jobber), for chat (check_calendar_availability / book_meeting) and ElevenLabs voice. Prompts get a Clinic appointment section (integrations/actions/calendar/semble-choices.ts) listing the three option lists. They don't list every combination, because 8 types × 2 sites × 3 clinician options is already 48. The agent is told to ask the type, then the clinician (or any), then the location, and to compose calendar_id from those ids. The tool layer validates it against the full list. app.controller.ts refuses a voice availability or book call with no calendar_id when the clinic has more than one choice. Without that check the backend would silently use the first combination (ff8999389).
Widget
SembleChoicePicker.vue (4f01e38) replaces the GHL purpose list when bookingType === 'semble': Location (only when > 1) → Clinician ("Any available clinician" first) → Appointment type → Continue, single-option lists auto-selected. It is used in ChatWidget, AIVoiceWidget and AIVoiceWidgetClassic. When a choice has no slots, or ms-comm's _sembleSlotsFailed answers with an error echoing the calendar_id, the store clears the previous choice's slots and shows cal.noSlotsForChoice (ae6daae, ms-comm e4539ff). i18n en/sv/ar.
Configuration & environment
| Env (backend + schedular) | Default | Notes |
|---|---|---|
SEMBLE_WEBHOOK_BASE_URL | BASE_URL | Public https base for webhook delivery |
SEMBLE_SYNC_INTERVAL_MINUTES | 15 | Fallback sync cadence |
SEMBLE_REQUEST_TIMEOUT_MS | 30000 | |
SEMBLE_RATE_LIMIT_MAX / _WINDOW_MS | 10 / 1000 | Per clinic token |
No env is required in PROD. SembleService is loaded unconditionally (hooks.js), the endpoint is hardcoded to live, and the webhook URL falls back to BASE_URL (https://api.knock-knockapp.com in both PROD backend and schedular). SERVICE_SEMBLE and SEMBLE_ENV, set only in flux-deployments/Apps/DEV/backend/configmap.yaml (ba107e37), have been dead since 0d0d6076f, which removed the service flag and the sandbox switch. They can be deleted. The webhook queue needs Redis. The scheduler pod decrypts clinic tokens for the sync job and the webhook worker, so SECRET_ENCRYPTION_KEY must match between backend and schedular, as it already must for mailboxes.
Behaviors & edge cases
- Ladder: GHL calendar → HubSpot meeting link → Calendly → Cal.com → Google → Outlook → GHL (no calendar) → Jobber → Semble → PracSuite → ServiceM8 → custom booking URL. Any earlier provider connected for booking wins unless the tenant picks Semble as
calendar_choice(Integrations → Booking calendar). PracSuite is a deliberate copy of this integration. - A ticked type, clinician or location deleted in Semble makes
settingsfail with "A ticked location, appointment type or clinician no longer exists in Semble." Existing snapshots keep being offered until the next save. Booking then fails at Semble. - An unknown
calendar_idreturnsUNKNOWN_CALENDARcarrying the current list, so the agent or widget asks again. - A booking moved in Semble to a time that differs by under a minute is
unchanged. Bookings not created by Knock Knock are ignored (not_ours). - Disconnect best-effort deletes the webhook subscription. Existing Semble appointments stay.
Technical implementation
- backend:
SembleController,SembleService(globalsemble),SembleWebhookQueueService(globalsembleWebhooks),jobs/SembleSyncJob,services/semble/{SembleClient,operations,choices,errors,verifySignature}.js,scheduling/adapters/SembleAdapter.js,middlewares/forceSembleCalendar.js,scheduling/resolveProvider.js. Specs:semble-client,semble-operations,semble-scheduling-adapter,semble-webhook-signature,force-semble-calendar,scheduling-resolve-provider. - frontend:
components/integrations/SembleCard.vue+SembleModal.vue(vee-validate + zod token form).s2sDefaultPrompt.jscounts a bookable Semble as a calendar. Booking badge "Semble" incallsFeed.js/SessionMoreInfoPanel.vue. - ms-communication:
SchedulingClientHelper(routeFor,isSembleBookingEnabled),MessageControllerslots +_sembleSlotsFailed,CompanyContextHelper/CallsControllerladder copies. - ms-ai:
calendar-router.service.ts,semble-choices.ts,meetings.agent.ts,calendar.tool.ts,elevenlabs.service.ts,app.controller.ts. - widget:
components/SembleChoicePicker.vue,stores/widget.ts(noSlotsForChoice).
Related
- Bookings — Sources & Unified View
- Simpro + Tapi: the other vertical-specific booking integration
- Google Calendar · Calendly