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).
crm_links — one id array instead of a column per provider
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.jslinkOps()builds two guarded atomic ops —$setoncrm_links.$when$elemMatchproves presence,$pushwhen$not:$elemMatchproves absence — runordered:true, so concurrent writers can't duplicate a(provider, object)row (d7cc53758). A blankexternal_idclears the row and nulls the legacy column.setLinkwraps it;many:trueis for the relink-all-sessions reconcile paths.readLinkstill prefers the legacy field and falls back to the array. The flip to array-first is a one-line change incrmLinks.jsthat 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) carrycrm_linkstoo. GHL ids dual-writeghl_contact_id; HubSpot ids are array-only. Query withcrmContact.match/matchAny/LINKED/ID_EXPR, write withfieldsFor(company_id, id). - Backfill:
app/lib/crmLinksBackfill.jsviaPOST /migrations/backfill-crm-links+GET …/jobs/:id(dry-run default,background:trueon real data). It walks company by company with{company_id, <col>: {$gt: ''}}so it rides the existing indexes — the first collection-wide$orwas a COLLSCAN that timed out in prod — and queries the unindexedsalesforce_lead_idonly 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 withcrm_provider: 'hubspot'move their id offghl_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 onGhlWebhookQueueService(processed byGhlNativeEventHelperon 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 onlyconversations/message.write;.mp3URL 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-agentpost_call_summary_fieldcustom-field write.
- Resilience —
app/lib/ghlResilience.jswraps 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 stampsapp_version: 'v2'and any other token is refused before refresh withGHL_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, publicGET /go-high-level/:company_id/booking-calendars, widget picker, ms-aicalendar_idtool param only when >1 calendar (one-timePOST /elevenlabs/sync-calendar-tools). - Refresh-token race fix —
bookCalendarwarms 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 (theleadconnector_chat_start_url_enabledflag 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_idis indexed. Inbound webhooks no longer go throughCrmSyncQueueService. - Calendar purposes (
multi_calendar_purposes) + a requiredmeeting_purposeon the ms-ai calendar tools in multi-calendar mode. - Booking chat logs —
ChatLogHelperwrites GHL booking requested/created/failed rows into the sharedlogsstream.
Recent (2026-10):
- Iframe SSO — marketplace Custom Page at
/connect/sso(company from the SSO payload'sactiveLocation), per-staff login viago_high_level.user_mapand the owner-only Team access tab (links +blockedentries →ghl_user_blocked); needsGO_HIGH_LEVEL_V2_SSO_KEY. - Custom Page sidebar — per-location name/hide via public
GET /go-high-level/sidebarread by a Custom JS script; menu links are now optional (created only without the SSO key), tracked bycustom_menu_held_byand managed viaPOST/DELETE /go-high-level/menu-linkby whoever's GHL agency holds them (agency portalGhlClientModal). - Scopes —
lc-email.readonly+workflows.readonlyrequested;granted_scopesrecorded per grant,/user/mereturnsmissing_scopes;custom_page_at(first Custom Page login) drives the app-update banner. - Tokens hidden (
select:false) and oneisGhlConnectedrule — 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_tokenlinks are the campaign-recognition path.
Recent (2026-10/11):
- Tag writes are add-only (
23744b9f5): GHL replaces the whole tag list whentagsrides on an upsert/update, which wiped a tenant's own tags on an AI inbound call.upsertContact/updateContactnow send tags only viaaddTags;GhlPostCallTagsService.syncTagsonly adds missing tags;GhlAdapter.setTagswas 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 ofghl_contact_update_policy; a phone-matched booking contact's email is only filled when empty.d3c5fecb4then fills missing fields (lib/ghlContactFilltranscript_airule — name only over blank/placeholder, email only when none, phone only when blank) viaAiCallContactExtractedController._fillExistingContact, retrying without the email when GHL refuses it as another contact's duplicate; the schedulingGhlAdapterwrites the invitee's name onto a nameless matched contact. - Conversations marked unread (
0590b533d,d31280514): SDK@gohighlevel/api-client^3.1.1;GoHighLevelService.sendMessagemarks the conversation unread (markConversationUnread) for every caller (chat sync, voice transcripts, recordings, Nox actions).ghl_conversation_idis now in theChatModelschema (373de1aee), so the synced id actually persists. - Outbound-call workflow action passes
/ai-outbound/webhook4xx 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-comm0da83f0).
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_SALESFORCEplusSALESFORCE_CLIENT_ID,_SECRET, and_REDIRECT_URIall present (hooks.js) — the service throws on construction if any is missing, and an unconfigured server must still boot._REDIRECT_URIis deliberately not derived fromapp.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 areapi refresh_token offline_access, neverfull. - 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-credentialsstores a tenant's own client id + encrypted secret;_credsFromDocprefers those and reportssource: 'customer' | 'knockknock'. Disconnect does not clear them. - Writes:
buildLeadPayload—LastNameandCompanyare 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 inFREEMAIL_DOMAINS→[Unknown]. SOQL literals go throughescapeSoqlbecause emails/phones are visitor input. If the org rejects an optional field (picklist/validation), the optional set is dropped and the insert retried. - Upsert:
upsertLeadPATCHessobjects/Lead/{external_id_field}/{value}only when an admin has setsalesforce.external_id_field; HTTP 300 means an ambiguous match and nothing is written.Sforce-Duplicate-Rule-Header: allowSave=trueunlessallow_duplicates === false. The config knobs (lead_source,owner_id,external_id_field,allow_duplicates,custom_field_map) exist onCompanyModelwith no UI. - Reads (2026-09-23):
SalesforceService+ the restoredSalesforceAdaptersearch by email/phone/name across both Leads and Contacts, fetch contact details by id, presentOpportunityStageas one "Opportunities" pipeline, find Opportunities viaOpportunityContactRole, and derivecontact_stagewith aLead.Statusfallback. SOQL sticks to constructs a restricted org can't reject:FirstName/LastNameprefix match (never compoundName), best-effortCOUNT()falling back to a floor total, pipeline query retried without itsIsActivefilter.KnoxCrmControllerrenders Salesforce rows and tags cursorssf:; identified-visitor lists and their dedupe key cover all four CRMs. Spec:test/salesforce-read.spec.js. - Lead source:
formatLeadSourceLinesgo into Description (sacrificial on create); flattened lead-source keys are mappable viacustom_field_map. SalesforceTokenHeartbeatJob: Salesforce enforces a 30-day refresh-token idle timeout, so quiet orgs die silently. The job pings/limitsfor orgs untouched for 14 days (25 per batch, read-only) and marks the connectionexpiredso 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(default2025-04-16),JOBBER_HANDSHAKE_TTL. Env must exist in both backend and schedular configmaps (done in PROD 2026-09-09). PROD redirect ishttps://api.nextlevelai.site/jobber/install(fluxa608b86d). 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), tokensselect:false, connection markerjobber.account_id. Routes:GET /jobber/installandPOST /jobber/webhookpublic;install-url,status,verify,uninstallbehind passport. - GraphQL client:
gql()retries once after a 401-triggered refresh;unwrap()treats top-levelerrorsas failures and mapsextensions.code === 'THROTTLED'toRateLimitedwithretry_after_msfrom 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 passfirst:— an unbounded connection costs 100 nodes. - Webhooks: HMAC
X-Jobber-Hmac-SHA256over the raw body; Jobber wants an answer within 1s, soAPP_DISCONNECTis one indexed update and work objects go tocrmSync.jobberWebhook. Payloads are ids-only, so the helper re-queries the work object →client.id→ matches the session/profile viacrm_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
getContactStageshape withpipeline_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_idis the Request id; the mutations act on its Assessment, whichJobberAdapterlooks up when the caller didn't supplyraw(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) viaclientEditphonesToAdd/emailsToAdd— additive, never overwrites (parity with GHL/HubSpot). - Nox (
8fe6e1c6a):recentBookingsmerges Jobber assessments/visits/ events (matched_via: jobber_calendar, deduped against mirror rows;scheduledItemsneedsincludeUnassigned: trueor KK-booked assessments are omitted) andGET /internal/knox/crm/requestslists Jobber requests in a window (ms-aic4f56c705). - Lifecycle dedupe: duplicate
LeadLifecycleEventModelrows (source: jobber) block thejobber_lifecycle_onceunique 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_createshippedtrue(the v1 plan said false);pipelinesand 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.