Skip to main content

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 practice query, then stored in the credential vault (provider: 'semble', never returned).
  • Booking settings: the clinic ticks appointment types (Semble products with productType appointment 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)​

RouteAuthPurpose
POST /semble/connect, /options, /settings, /status, /rotate-token, /disconnect, /backfillpassport (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-calendarspublicThe widget's choice list (publicCalendar, with a choice object holding the three parts)
POST /semble/availability, /semble/bookpublic, forceSembleCalendar middlewareSame SchedulingController handlers as /scheduling/* with calendar_type pinned to semble (8e38b412a)
POST /webhooks/semble/:companyIdHMAC over the raw bodyBare 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)​

  1. Needs an email or a phone (supportsPhone includes Semble for lookups too).
  2. 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.
  3. Idempotent retry: if the patient already holds a booking at that exact start, it returns it with already_booked: true.
  4. 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 createBooking on the slot's room (doctor omitted for General), with comment "<title> (booked via Knock Knock)" or "Booked via Knock Knock". Clash-like mutation errors map to SLOT_TAKEN. An auth error maps to AUTH_EXPIRED and flips connection_status: 'expired'.
  5. The session booking is stored with booking_type: 'semble' and semble_appointment_id. The user_sessions index is {company_id, 'bookings.semble_appointment_id'}. Person bookings source: '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: ensureWebhook subscribes booking.updated, booking.deleted, webhook.subscription.updated to <SEMBLE_WEBHOOK_BASE_URL or BASE_URL>/webhooks/semble/<companyId> (must be https, else status unavailable). A missing token permission gives failed. Deliveries are deduped on eventId for 24 h in Redis (semble_evt:*), then enqueued on BullMQ semble-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) and reconcile applies it only to our bookings, matched by MeetingModel.provider_event_id. Delete gives cancelByProviderId + cancel notification ("Cancelled in Semble"). A moved start (> 1 min) gives rescheduleByProviderId + reschedule notification.
  • SembleSyncJob (scheduler, SEMBLE_SYNC_INTERVAL_MINUTES, default 15) re-reads bookingsChanged since last_synced_at (5 min overlap) for every enabled and 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, unavailable or failed ("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)DefaultNotes
SEMBLE_WEBHOOK_BASE_URLBASE_URLPublic https base for webhook delivery
SEMBLE_SYNC_INTERVAL_MINUTES15Fallback sync cadence
SEMBLE_REQUEST_TIMEOUT_MS30000
SEMBLE_RATE_LIMIT_MAX / _WINDOW_MS10 / 1000Per 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 settings fail 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_id returns UNKNOWN_CALENDAR carrying 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 (global semble), SembleWebhookQueueService (global sembleWebhooks), 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.js counts a bookable Semble as a calendar. Booking badge "Semble" in callsFeed.js / SessionMoreInfoPanel.vue.
  • ms-communication: SchedulingClientHelper (routeFor, isSembleBookingEnabled), MessageController slots + _sembleSlotsFailed, CompanyContextHelper / CallsController ladder 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).