Skip to main content

CRM & External Integration

backend is the integration hub. The dominant CRM is GoHighLevel (GHL); HubSpot, Salesforce, Jobber, Slack, Stripe/Xero, Twilio, and several enrichment providers are also wired in. Each integration is a service under backend/app/services/<Name>Service.js with config in app/configs/ — but since 2026-09 tenant CRM access goes through the CRM port described first, and touching a provider service directly is an allowlisted exception.

The CRM port (crm global)​

app/services/CrmService.js is the port; app/services/crm/ holds capabilities.js, canonical.js, errors.js, resolveProvider.js, and adapters/{Ghl,Hubspot,Salesforce,Jobber,ServiceM8}Adapter.js. It's loaded as the crm global (hooks.js app.loadService('crm', …)), and adapters are stateless — they resolve their provider service off the global at call time (SERVICE_GLOBAL: ghl→goHighLevel, hubspot→publicHubspot, salesforce→salesforce, jobber→jobber, servicem8→servicem8).

Calling it. crm.run({ company, capability, requested, call }) picks a provider and returns an envelope { ok, provider, data, unsupported, error }. A capability the provider lacks comes back as unsupported, never a throw. Helpers: forCompany, connected/isConnected, supports, providersWith, resolveProvider, and passthrough('ghl') — the escape hatch for GHL-only surfaces, which throws for any other provider.

Provider precedence (crm/resolveProvider.js): ghl → hubspot → salesforce → jobber → servicem8, each with its own connection test (GHL location_id — exported as isGhlConnected, the one "GHL connected" rule every controller/job now uses (637e65f8e); HubSpot access_token_expires_at and not expired (tokens are select:false); Salesforce instance_url and not expired; Jobber account_id; ServiceM8 account_uuid, enabled !== false, not expired). REQUIRED_FIELDS is the projection callers must select — the Salesforce tokens are select:false, so a lean company doc without them reads as disconnected. Naming a requested provider that isn't connected returns null rather than falling through.

Capability matrix (crm/capabilities.js, 20 keys): contact get / find by email, phone, name / create / update / enrichment, note_create, activity_log, call_log, task_create, deal_write, workflows, tags, custom_fields, dormant_search, pipelines, contact_stage, deal_search, deal_search_by_contact. The adapter vocabulary grew with HubSpot parity (a71bf7577): getOutreachContact, addTags/setTags, setFields, createTask, logActivity, logCall, searchDormant, moveDeal/createDeal, listWorkflows/enrollInWorkflow. HubSpot supports every key; GHL every key except call_log (calls go to Conversations) and task_create (GHL sends follow-ups itself); Salesforce reads Leads and Contacts (get, find by email/phone/name, pipelines, stage, deals, deals-by-contact) but writes are lead-create only — no update/enrichment/notes; Jobber has no enrichment/pipelines/deals but does derive contact_stage; ServiceM8 (2026-11-13) supports only contact get/find by email & phone/create/update, note_create (job-diary notes) and contact_stage (from job status) — see ServiceM8. Nox's knox_crm tool takes provider: auto|ghl|hubspot|salesforce|jobber and reports which CRM it read (ms-ai BackendCrmClient CRM_PROVIDERS allowlist — Jobber results used to arrive with provider: null).

The GoHighLevel boundary. capabilities.js GHL_ONLY splits GHL's non-portable surface into BY_DESIGN (auth, marketplace, sso (getLocationUsers, iframe staff mapping), calendar, tag listing/removal, conversations, aggregate) and NOT_YET_PORTED (custom-field reads/writes by id, upsertContact). test/crm-registry.spec.js enforces it: every public GoHighLevelService method must be ported or classified (not both, no stale names), calendar methods must not appear in GhlAdapter, and only the 21 files in GHL_DIRECT_ALLOWED may reference global.goHighLevel — a new direct caller fails the suite, as does a stale allowlist entry. Add through the port.

Security + data review (445133820, merged 7887d40ac 2026-09-23). Signed, expiring OAuth state for GHL/HubSpot (app/lib/oauthState.js, 24h); /company/owner scoped to the caller's company; agency GHL install/uninstall/complete-install require managing that agency; client- controlled _deferred_crm_sync dropped from /user-session/create; no raw SDK/axios errors in GHL responses; native GHL webhook replay guard (48h); workflow-webhook location check observe-only until GHL_WEBHOOK_ENFORCE_LOCATION=true; HubSpot refresh token revoked on disconnect. Data: failed provider syncs retry via BullMQ; enrichment guesses (apollo, lead_sync) reach GHL only and never overwrite a stated link; serialised GHL token refresh (manual refresh endpoint removed); UNINSTALL scoped to the app version and every company on the location; a location change clears cached field ids, calendars and calendar purposes; Knox CRM failed reads throw instead of caching empties; Jobber gets one lifecycle row per object/stage (unique partial index jobber_lifecycle_once) and one company per account; Simpro list pulls fail loudly past 25k rows.

HubSpot parity + access gates (2026-10). HubSpot now does everything the port offers — see HubSpot. The same review (24c614a4a, 6c7dd2a7b) gated PUT /company/:_id and ~20 sibling /company/:id/* handlers on GeneralHelper.canManageCompany (integration tokens/ids never writable there; admin-only fields stripped for non-admins), stopped the public GET /company/:_id returning integration configs, and made go_high_level/ghl_self_account/agency GHL tokens, GHL secret_key and HubSpot tokens select:false.

Sync fan-out. CrmSyncHelper is now a registry-driven loop: every connected provider receives each lead (CrmSyncHelper.js ~220–250), and visitor-stated name/email/phone are written onto matched contacts, not just created ones (014f45457). Chat transcripts and AI-call summaries post as notes wherever note_create is true (GHL, HubSpot, Jobber). Recording links in those notes use ms-comm's vendor-neutral /recordings/{ai,call,agent}/… aliases (072ff5a40; vendor-named routes stay live for old links).

Lead source (2026-09-25). Every captured lead carries a lead_source object (app/lib/leadSource.js — type, page, product, start/landing URLs, traffic source + UTMs + gclid; URLs origin + path only). It rides the new_lead webhook (see Webhooks), is written as a "Lead source" note on GHL + HubSpot for every company with either connected (sync-lead-source-note job, 60 s delay, gclid also into GHL's gclid custom field / HubSpot hs_google_click_id), and lands in the Salesforce Lead Description; flattenLeadSource exposes scalar keys (page_url, utm_campaign, gclid, …) for salesforce.custom_field_map. The per-company crm_lead_source_note_enabled toggle was added and removed on the same day — there is no gate.

Enrichment-guess links. An Apollo guess never syncs for a visitor VisitorIdentityHelper.knowsVisitor can name, and a guessed GHL link (user_session.ghl_contact_from_enrichment) is released (lib/enrichmentLink.releaseGuessedContact) as soon as a person is stamped or the visitor states any field — see GoHighLevel. Backlog: /migrations/unlink-apollo-contacts (+ Identity Maintenance card).

UserSessionModel and PersonProfileModel carry crm_links: [{ provider, object, external_id }] with one multikey index {company_id, 'crm_links.provider', 'crm_links.external_id'}. The legacy flat columns (ghl_contact_id, hubspot_contact_id, salesforce_lead_id) are dual-written; Jobber is the first provider with no legacy column (provider→object: salesforce→lead, jobber→client).

  • app/lib/crmLinks.js linkOps() builds two guarded atomic ops — $set on crm_links.$ when $elemMatch proves presence, $push when $not:$elemMatch proves absence — run ordered:true, so concurrent writers can't duplicate a (provider, object) row (d7cc53758). A blank external_id clears the row and nulls the legacy column. setLink wraps it; many:true is for the relink-all-sessions reconcile paths.
  • readLink still prefers the legacy field and falls back to the array. The flip to array-first is a one-line change in crmLinks.js that has not happened yet; do it only after the backfill has run in prod.
  • Contact-keyed records (lib/crmContact.js, a71bf7577): 10 record models (Nox actions/scheduled actions/commitments/suggestion decisions, lifecycle events, funnel contacts/recon items/audit log, Agent K LinkedIn sequences, SMS agent messages) carry crm_links too. GHL ids dual-write ghl_contact_id; HubSpot ids are array-only. Query with crmContact.match/matchAny/LINKED/ID_EXPR, write with fieldsFor(company_id, id).
  • Backfill: app/lib/crmLinksBackfill.js via POST /migrations/backfill-crm-links + GET …/jobs/:id (dry-run default, background:true on real data). It walks company by company with {company_id, <col>: {$gt: ''}} so it rides the existing indexes — the first collection-wide $or was a COLLSCAN that timed out in prod — and queries the unindexed salesforce_lead_id only on tenants with a Salesforce connection. BATCH = 500, bulkWrite ordered:false, idempotent. Applied in prod 2026-09-05. Extended for the record models (sweepRecords; Agent K rows with crm_provider: 'hubspot' move their id off ghl_contact_id) and retries a company on a Mongo timeout (a9301ed8b) — re-run it after deploying the HubSpot parity work.

Scheduling port​

app/services/scheduling/ mirrors the pattern for calendars: resolveProvider.js, normalize.js, errors.js, adapters/{Ghl,HubspotMeetings,Calendly,Calcom,Google,Outlook,Jobber,Semble,PracSuite,ServiceM8}Adapter.js, exposed as POST /scheduling/{calendars,availability,book,meetings,reschedule,cancel} (plus /scheduling/google/{connect,status,disconnect} for the ms-ai-relayed Google OAuth). Since 225840d0d (2026-11-05) the tenant picks the calendar (companies.calendar_choice, GET/PUT /company/calendar-settings); unset or disconnected falls back to the automatic ladder, which is now one list (RUNGS): GHL with calendar_id → HubSpot Meetings → Calendly → Cal.com → Google → Outlook → GHL-connected → Jobber → Semble → PracSuite → ServiceM8 → custom_calender. CompanyController uses it instead of its own copy, and ms-communication keeps exactly one mirror (SchedulingClientHelper.resolveProvider, replacing the copies in CompanyContextHelper/MessageController/CallsController). Rung tests read connected markers only. booking_type is 'ghl' | 'hubspot' | 'google' | 'calendly' | 'calcom' | 'outlook' | 'jobber' | 'semble' | 'pracsuite' | 'servicem8' | 'manual'. Ladder, failure codes (SLOT_TAKEN + day_full, BOOKING_REFUSED) and sync-back per provider: Bookings — Sources.

Booking length (6121a0246): book({ duration_minutes }) reaches Google only — GoogleAdapter._requestedMinutes accepts 5–480 and wins over the calendar's defaultEventLength (fallback otherwise); GHL/Calendly/Jobber/ HubSpot lengths are fixed by the calendar. In ms-ai the voice tools expose duration_minutes (VOICE_DURATION_MINUTES_DESCRIPTION, only when the caller asked); the chat customDurationTools variant is built but not wired into any agent. The booking reply reports the time in the user's zone and the booked length for Google + GHL (863cb6c8c/33c4f8d3b), never throwing on an empty zone (4ffab059a).

Cancel (16b7f0b5e, ms-comm dbc49a1, widget b53ede9): ms-ai public POST tools/calendar/<uuid>/cancel + a cancelMeeting tool (meeting id must come from a prior my-meetings call; never retried — the backend answers MEETING_NOT_FOUND on a repeat); the widget's "Cancel a meeting" sheet sends calendar_booking_meta.cancel and ms-comm MessageController.cancelMeeting answers on cancel-result (chat transcript row type booking-cancel). Owners cancel from the Meetings page via POST /company/meetings/cancel (CompanyMeetingsController, owner/super-admin only; GET /company/meetings lists upcoming non-cancelled user_sessions.bookings[], soonest first). HubSpot rows are never cancellable.

Recent port fixes: GHL books and reschedules at the calendar's own slotDuration, renders times in the location zone, recovers a lost-success retry as already_booked (no second tenant push), attaches booking_url to SLOT_TAKEN, and enforces the multi-calendar visible subset + per-calendar purposes — details on GoHighLevel. JobberAdapter now resolves the Assessment id from the Request id (provider_event_id) when SchedulingService passes no raw — every reschedule/cancel used to fail MEETING_NOT_FOUND (859555b17). CalendarSyncJob (15 min, 225840d0d) applies cancels/moves made directly in Google, Outlook or Cal.com to our bookings, the way SembleSyncJob / PracSuiteSyncJob do for the clinic calendars.

Platform CRM vs tenant CRM​

PlatformCrmService.js is Knock Knock's own CRM accounts — signup and lifecycle tagging, certification and partner funnels — not a tenant integration. It fans out upsertContact, syncCompany, and updateContactEmail to every provider enabled in configs/platformCrm.js that is connected and implements the verb (PlatformGhl on a private-integration token, PlatformHubspot); one provider throwing is logged and returns false without stopping the others. PlatformHubspot adopts the existing contact on a 409 ("Existing ID: …") instead of failing (97d9d6205). It returns {} without writing on dev and staging, is loaded behind SERVICE_PLATFORM_CRM, and is deliberately not gated on tenant GHL OAuth credentials.

CRM smoke test​

POST /migrations/crm-smoke (+ jobs poll), re-exposed as POST /admin/identity/maintenance/crm-smoke for the admin panel's Identity Maintenance card. app/lib/crmSmoke.js drives the deployment's own HTTP routes — what ms-ai sees — discovering its own tenants with bounded, indexed, maxTimeMS(20_000) queries and firstAlive() token probes (a dead token skips a check, it doesn't fail the run). It asserts api-key enforcement, envelope provider names, GHL/HubSpot read shapes, dry-run backfill writes nothing, apply-then-rerun idempotence, and the write path — which refuses to touch a customer tenant unless an explicit ghl_company_id is passed. Our own tenants (owner @knockknockapp.ai) outrank linked ones in discovery.

Boot order: the scheduler loads last​

SchedulerService constructs all 62 jobs and starts ticking in its constructor, so any job whose constructor reads a global defined later in hooks.js crashed the schedular pod only — API pods never construct jobs. KkTokenSyncJob → AgentKPushService → NoxGhlActionService reading crm was the first casualty (1e57eefab); the real fix (7d5409b19) makes app.loadService('scheduler', …) the last statement of boot(). Keep it there, and reproduce schedular-only crashes locally with SERVICE_CRON=true.

GoHighLevel (GHL)​

UI copy now says "LeadConnector" (frontend-wide rename); code/config keys remain go_high_level/ghl.

The largest integration (GoHighLevelService.js, ~61 KB). It syncs contacts, posts call/chat outcomes as notes, updates pipeline stages, triggers workflows, and handles calendar/SMS/voice.

Mechanics:

  • Inbound webhooks — native marketplace events arrive via goHighLevelRoutes.js, are verified and replay-guarded, and are enqueued on GhlWebhookQueueService (processed by GhlNativeEventHelper on the schedular); workflow webhooks are handled in-request.
  • Outbound — cron jobs post activity back to GHL:
    • OutboundCallGhlSyncJob (1 min) — call transcripts → contact notes.
    • AiCallGhlTranscriptSyncJob (5 min) — AI call transcripts + the recording attached to GHL Conversations as a playable inbound message (sendCallRecording, needs only conversations/message.write; .mp3 URL suffix for the inline player).
    • KnoxGhlSyncJob (nightly 03:00) — pipeline-stage sync + new-visitor backfill.
    • Post-call extras: outcome tags per agent_key → post_call_tags (GhlPostCallTagsService, clobber-guarded) and a per-outbound-agent post_call_summary_field custom-field write.
  • Resilience — app/lib/ghlResilience.js wraps calls for retry/backoff.
  • One app (v1 retired, 2026-10-19) — only the marketplace app is configured (GO_HIGH_LEVEL_V2_* env names); every install stamps app_version: 'v2' and any other token is refused before refresh with GHL_APP_RETIRED (red reinstall banner in both portals). Public marketplace-directory installs are stateless (install code handed to the SPA, agency + sub-account two-step, needs_mapping), and disconnect now fully uninstalls the app GHL-side (location, company-level, and agency installs). See GoHighLevel.

Recent (2026-07/08):

  • Multi-calendar booking — go_high_level.multi_calendar_enabled / multi_calendar_ids, public GET /go-high-level/:company_id/booking-calendars, widget picker, ms-ai calendar_id tool param only when >1 calendar (one-time POST /elevenlabs/sync-calendar-tools).
  • Refresh-token race fix — bookCalendar warms the OAuth token once (getCompanyClient) before fanning out parallel GHL calls (GHL refresh tokens are single-use; a race could persist a stale token) and parallelizes contact + calendar fetches to fit ms-ai's 20s booking budget.
  • Chat-start-URL note — adds the chat's starting page URL as a contact note on sync (CrmSyncHelper); ungated for every GHL-connected company since 2026-09-25 (the leadconnector_chat_start_url_enabled flag is gone).

Recent (2026-09):

  • Native webhooks are queued (GhlWebhookQueueService, 8 contact-keyed BullMQ shards, workers on the schedular only) instead of processed in the request; go_high_level.location_id is indexed. Inbound webhooks no longer go through CrmSyncQueueService.
  • Calendar purposes (multi_calendar_purposes) + a required meeting_purpose on the ms-ai calendar tools in multi-calendar mode.
  • Booking chat logs — ChatLogHelper writes GHL booking requested/created/failed rows into the shared logs stream.

Recent (2026-10):

  • Iframe SSO — marketplace Custom Page at /connect/sso (company from the SSO payload's activeLocation), per-staff login via go_high_level.user_map and the owner-only Team access tab (links + blocked entries → ghl_user_blocked); needs GO_HIGH_LEVEL_V2_SSO_KEY.
  • Custom Page sidebar — per-location name/hide via public GET /go-high-level/sidebar read by a Custom JS script; menu links are now optional (created only without the SSO key), tracked by custom_menu_held_by and managed via POST/DELETE /go-high-level/menu-link by whoever's GHL agency holds them (agency portal GhlClientModal).
  • Scopes — lc-email.readonly + workflows.readonly requested; granted_scopes recorded per grant, /user/me returns missing_scopes; custom_page_at (first Custom Page login) drives the app-update banner.
  • Tokens hidden (select:false) and one isGhlConnected rule — after-chat tags had been skipped for every tenant because the job never loaded the token.
  • Appointment descriptions carry the real email + the contact's own name/phone fallback; malformed emails are refused before booking.
  • ?contact_id= landing removed from the widget loader (spoofable; it never worked) — kk_token links are the campaign-recognition path.

Recent (2026-10/11):

  • Tag writes are add-only (23744b9f5): GHL replaces the whole tag list when tags rides on an upsert/update, which wiped a tenant's own tags on an AI inbound call. upsertContact/updateContact now send tags only via addTags; GhlPostCallTagsService.syncTags only adds missing tags; GhlAdapter.setTags was removed. The funnel stage swap is the only path that still removes tags.
  • Existing contacts are never overwritten from AI calls or bookings (906d9a2c1): inbound-call identity reconcile only fills empty fields regardless of ghl_contact_update_policy; a phone-matched booking contact's email is only filled when empty. d3c5fecb4 then fills missing fields (lib/ghlContactFill transcript_ai rule — name only over blank/placeholder, email only when none, phone only when blank) via AiCallContactExtractedController._fillExistingContact, retrying without the email when GHL refuses it as another contact's duplicate; the scheduling GhlAdapter writes the invitee's name onto a nameless matched contact.
  • Conversations marked unread (0590b533d, d31280514): SDK @gohighlevel/api-client ^3.1.1; GoHighLevelService.sendMessage marks the conversation unread (markConversationUnread) for every caller (chat sync, voice transcripts, recordings, Nox actions). ghl_conversation_id is now in the ChatModel schema (373de1aee), so the synced id actually persists.
  • Outbound-call workflow action passes /ai-outbound/webhook 4xx rejections through instead of re-logging them as a 500 (c3c8aeac0).
  • GHL tokens moved into the credential vault (dual-write window); ms-comm's booking ladder reads go_high_level.access_token_expires_at, not the token (ms-comm 0da83f0).

Details: GoHighLevel.

Nox also writes to GHL through its own action layer (ms-ai knox-ghl-sync.service.ts) — see Nox Assistant.

Calendar bookings (unified)​

Every booking source — Calendly, Cal.com, GHL, HubSpot Meetings, Google Calendar, Outlook, Jobber, Semble, PracSuite, ServiceM8, generic — records through backend/app/services/BookingRecordService.js (record({ company_id, user_session_id, booking, event_name, end_time })), which stamps the new booking fields on UserSessionModel (bookings[]: booking_type/booking_date/booking_time/Calendly invitee ids for webhook dedupe, had_booking) and PersonProfileModel. Don't write bookings ad hoc.

Calendly custom questions: since 2026-09-29 the event type's questions are asked of the visitor (GET /calendly/:company_id/booking-questions, widget sheet + ms-ai prompt/booking_answers) and supplied answers win. CalendlyController._getLeadContext(user_session_id) — session phone, Apollo/Snitcher company name, a digest of the visitor's chat — only fills questions left unanswered. Never throws. See Calendly.

Calendly UTM tracking (afe477309): direct bookings and booking links carry utm_source (knock_knock_ai, or the agency name slug for agency clients) and utm_content = user_session_id — see Calendly.

HubSpot​

PublicHubspotService.js (tenant OAuth app, publicHubspot global — loaded only when HUBSPOT_CLIENT_ID/HUBSPOT_CLIENT_SECRET are set, in backend and schedular) and HubspotService.js (private token, internal). At GHL parity since 2026-10: contacts/notes/calls/tasks/kk_tags through the port, CrmCallLogJob + CrmVisitActivityJob, app webhooks (HubspotWebhookHelper), workflow actions + contact card, hubspotutk identification (POST /user-session/hubspot-utk), HubSpot Meetings booking, and Agent K / Nox / funnel on HubSpot. Full detail: HubSpot.

Salesforce​

SalesforceService.js + crm/adapters/SalesforceAdapter.js, SalesforceController.js, salesforceRoutes.js, configs/salesforce.js.

  • Gating: SERVICE_SALESFORCE plus SALESFORCE_CLIENT_ID, _SECRET, and _REDIRECT_URI all present (hooks.js) — the service throws on construction if any is missing, and an unconfigured server must still boot. _REDIRECT_URI is deliberately not derived from app.base_url.
  • OAuth: PKCE + HMAC-signed single-use state (10-minute handshake TTL). Sandbox (test.salesforce.com) and production (login.salesforce.com) are different token issuers — a token minted at one can't be refreshed at the other, so the environment is chosen at connect time and stored. Scopes are api refresh_token offline_access, never full.
  • Bring-your-own app: credentials come from an External Client App (the legacy Connected App path is restricted from Spring '26). POST/DELETE /salesforce/app-credentials stores a tenant's own client id + encrypted secret; _credsFromDoc prefers those and reports source: 'customer' | 'knockknock'. Disconnect does not clear them.
  • Writes: buildLeadPayload — LastName and Company are the only required-on-create fields. LastName ladder: explicit → last token → email local part → Unknown (a derived LastName equal to FirstName blanks FirstName). Company ladder: name → email domain unless in FREEMAIL_DOMAINS → [Unknown]. SOQL literals go through escapeSoql because emails/phones are visitor input. If the org rejects an optional field (picklist/validation), the optional set is dropped and the insert retried.
  • Upsert: upsertLead PATCHes sobjects/Lead/{external_id_field}/{value} only when an admin has set salesforce.external_id_field; HTTP 300 means an ambiguous match and nothing is written. Sforce-Duplicate-Rule-Header: allowSave=true unless allow_duplicates === false. The config knobs (lead_source, owner_id, external_id_field, allow_duplicates, custom_field_map) exist on CompanyModel with no UI.
  • Reads (2026-09-23): SalesforceService + the restored SalesforceAdapter search by email/phone/name across both Leads and Contacts, fetch contact details by id, present OpportunityStage as one "Opportunities" pipeline, find Opportunities via OpportunityContactRole, and derive contact_stage with a Lead.Status fallback. SOQL sticks to constructs a restricted org can't reject: FirstName/LastName prefix match (never compound Name), best-effort COUNT() falling back to a floor total, pipeline query retried without its IsActive filter. KnoxCrmController renders Salesforce rows and tags cursors sf:; identified-visitor lists and their dedupe key cover all four CRMs. Spec: test/salesforce-read.spec.js.
  • Lead source: formatLeadSourceLines go into Description (sacrificial on create); flattened lead-source keys are mappable via custom_field_map.
  • SalesforceTokenHeartbeatJob: Salesforce enforces a 30-day refresh-token idle timeout, so quiet orgs die silently. The job pings /limits for orgs untouched for 14 days (25 per batch, read-only) and marks the connection expired so the card says Reconnect. Nothing flows back automatically — no webhooks, no polling; reads happen only on Nox request. Salesforce and Jobber refresh locks outlive the request timeout (and Salesforce requests now have one).

Jobber (beta, 2026-09)​

JobberService.js + crm/adapters/JobberAdapter.js + scheduling/adapters/JobberAdapter.js, JobberController.js, JobberWebhookHelper.js, jobberRoutes.js, configs/jobber.js. Plan doc: backend/docs/jobber-integration-plan.md.

  • Gating/env: SERVICE_JOBBER + JOBBER_CLIENT_ID, JOBBER_CLIENT_SECRET, JOBBER_REDIRECT_URI (defaults to {BASE_URL}/jobber/install); JOBBER_API_HOST, JOBBER_GRAPHQL_VERSION (default 2025-04-16), JOBBER_HANDSHAKE_TTL. Env must exist in both backend and schedular configmaps (done in PROD 2026-09-09). PROD redirect is https://api.nextlevelai.site/jobber/install (flux a608b86d). Request details are branded "Next Level AI" (673ba43f8).
  • OAuth: PKCE, signed single-use state parked in JobberOauthHandshakeModel, rotating refresh tokens serialised behind _withRefreshLock (a concurrent refresh would burn the token), tokens select:false, connection marker jobber.account_id. Routes: GET /jobber/install and POST /jobber/webhook public; install-url, status, verify, uninstall behind passport.
  • GraphQL client: gql() retries once after a 401-triggered refresh; unwrap() treats top-level errors as failures and maps extensions.code === 'THROTTLED' to RateLimited with retry_after_ms from the cost-bucket deficit — throttles arrive as HTTP 200. Limits are 2,500 requests per 5 minutes plus a 10,000-point cost bucket refilling 500/s; always pass first: — an unbounded connection costs 100 nodes.
  • Webhooks: HMAC X-Jobber-Hmac-SHA256 over the raw body; Jobber wants an answer within 1s, so APP_DISCONNECT is one indexed update and work objects go to crmSync.jobberWebhook. Payloads are ids-only, so the helper re-queries the work object → client.id → matches the session/profile via crm_links $elemMatch. Topics: QUOTE_SENT, QUOTE_APPROVED, JOB_CREATE, JOB_CLOSED, INVOICE_CREATE, PAYMENT_CREATE (also moves the funnel contact to won). Registration is per-app in the Jobber Developer Center, one URL per topic — not per account through the API.
  • Stage ladder (Jobber has no pipeline object): Invoice paid (won) → Invoiced → Job completed → Job scheduled → Quote approved → Quote sent → Quote drafted → Assessment scheduled → Request received; archived quote/request = lost. Furthest wins, emitted in the GHL/HubSpot getContactStage shape with pipeline_id: 'jobber'.
  • Booking = a Request with a scheduled Assessment (createRequest, editAssessment, deleteAssessment, listScheduledItems). Jobber has no free-slot API, so availability is working hours minus the schedule: SLOT_MINUTES = 60, LOOKUP_WINDOW_DAYS = 60, default 09:00–17:00.
  • Reschedule/cancel: our provider_event_id is the Request id; the mutations act on its Assessment, which JobberAdapter looks up when the caller didn't supply raw (859555b17).
  • Contact fill (ef72d4cd0): a matched or already-linked client gains a phone/email the visitor stated later (e.g. phone from an AI call after an email-only chat) via clientEdit phonesToAdd/emailsToAdd — additive, never overwrites (parity with GHL/HubSpot).
  • Nox (8fe6e1c6a): recentBookings merges Jobber assessments/visits/ events (matched_via: jobber_calendar, deduped against mirror rows; scheduledItems needs includeUnassigned: true or KK-booked assessments are omitted) and GET /internal/knox/crm/requests lists Jobber requests in a window (ms-ai c4f56c705).
  • Lifecycle dedupe: duplicate LeadLifecycleEventModel rows (source: jobber) block the jobber_lifecycle_once unique partial index, and a failed index build is silent. POST /migrations/dedupe-jobber-lifecycle (+ /admin/identity/maintenance/dedupe-jobber-lifecycle, admin "Dedupe Jobber Lifecycle Rows" card) dry-runs the list; apply keeps the oldest row.
  • Plan caveats: a draft Jobber app is capped at 5 paying accounts; going beyond needs marketplace review (APP_DISCONNECT handling, token rotation on, Manage App URL, 384px logo, gallery). note_create shipped true (the v1 plan said false); pipelines and Jobber enrichment are deliberately not built.

Slack​

SlackService.js — notifications and message relay; ms-communication also does Slack thread sync for chats (OAuth + event subscriptions with raw-body signature verification). The hardcoded SLACK_CLIENT_ID/SLACK_CLIENT_SECRET defaults were removed from configs/slack.js (c583ea511) — env only; and a malformed signature or timestamp now answers 400/401 instead of crashing the ms-comm pod (08f97d0). See Slack.

Payments & accounting​

Stripe (StripeService.js, checkout/billing) and Xero (XeroService.js, invoice sync). Revenue reporting depends on paid_at being stamped on paid invoices and currency stored per invoice.

Telephony​

Twilio (calls/SMS/video, mostly via ms-communication) and ElevenLabs (AI voice, via ms-ai).

Enrichment providers​

Clearbit, Apollo, Rb2b — B2B company/person data feeding the identity graph. Tracked via ApolloRecordModel, ClearbitSessionModel, Rb2bService.js. HappierLeads was deleted (d8a283a1b, 2026-09-09) — pixel, service, and webhook; only readers of the stored happier_leads_data blob remain. LeadContactSyncJob — the job that pushed enrichment-guessed contacts into GHL/HubSpot — is disabled globally (commented out of SchedulerService).

Trade / field-service (Simpro + Tapi)​

SimproService.js (connect, cost-centre mapping, in-call AI job creation, in-call technician booking since 2026-09-11, outbound invoice-chasing) and TapiService.js (IMAP work-order emails → ms-ai field extraction → Simpro, optionally scheduled). Phone search in Simpro must be digits-only. SimproInvoiceChaseJob and TapiPollJob run every 2 minutes. Job creation applies an AI-picked trade tag (ms-ai POST /agents/pick-job-tags). Full detail — auto_schedule settings, /available/technicians/ quirks, booking idempotency — on Simpro + Tapi.

ServiceM8 (beta, 2026-11-13, card hidden unless super-admin servicem8_allowed): OAuth add-on with rotating tokens in the vault, CRM adapter (client + Quote job + job-diary notes) and scheduling adapter (Work Order job + activity on owner-ticked staff, per-company Redis lock because ServiceM8 allows double bookings). Nox's knox_crm provider allowlist (ms-ai BackendCrmClient CRM_PROVIDERS) does not include servicem8 yet. Full detail on ServiceM8.

Webhooks (generic)​

webhookRoutes.js + WebhookModel/WebhookLogModel/WebhookEventModel support customer-registered outbound webhooks (HubSpot, Zapier, custom). Dualhook handles WhatsApp onboarding (HMAC-verified). Post-call webhooks now ship call_sentiment/transcript_text/a signed recording_url, delivery waits for the ElevenLabs analysis with a PostCallWebhookFallbackJob exactly-once fallback, and the new_user_identified event is revived. Since 2026-10-21 new_lead is debounced to one per settled visit, duplicate lead_score_update / new_user_identified sends are fixed, and a super-admin flag can mute form-intercept new_lead — see Webhooks.

ManyReach (Agent K)​

ManyReachService.js pushes kk-tokenized prospects into a tenant's ManyReach cold-email campaigns (routes under /knox/agent-k/manyreach/*; the agent_k_beta_enabled gate was removed 2026-09-25); a CSV token-minting path covers any other external sender. See ManyReach.

The sync queue pattern​

Most CRM work flows through Redis-backed queues + cron sweepers rather than synchronous calls, so a slow or failing CRM doesn't block request handling and work is retried. Watch CrmSyncQueueService (which now also drains Jobber webhooks) and the *GhlSyncJob family when debugging sync gaps.