Integrations Overview
Audience: All teams (sales, management, QA, support, engineering) · Where in app: Settings → Integrations (and Settings → Webhooks / Settings → Notifications) · Plan availability: All plans (some integrations are higher-tier — see each page and the matrix below)
Knock Knock connects to the common business tools a customer already runs — their CRM, their calendar, their store, their chat tool, and their automation platform. Each integration lives under Settings → Integrations and is connected with one click (OAuth) or a pasted API key. Once connected, leads, conversations, bookings, and product data flow between Knock Knock and the other tool automatically, so the customer never has to copy data by hand and the AI agent always has up-to-date context.
For sales and management: integrations are a core part of the pitch — "it plugs into your existing stack." The two CRMs (GoHighLevel and HubSpot, now at parity) are the deepest; calendars (Google Calendar, Calendly, Cal.com, plus vertical calendars Jobber, Semble, PracSuite and ServiceM8) drive bookings, and the tenant picks which one is booked; Shopify/WooCommerce make the AI product-aware; Slack/Zapier/webhooks push events out to wherever the customer wants them.
What it does
- Pushes new leads and conversation summaries out to the customer's CRM.
- Pulls CRM state (lifecycle stage, deals/opportunities, tags, notes) back in to enrich the identity graph so the AI knows who a returning visitor is.
- Recognizes returning visitors from the tenant's own HubSpot
hubspotutkcookie and from?kk=recognition-token links (GHL + HubSpot). The GHL?contact_id=landing was removed from the widget loader (spoofable, and it never worked). - Lets visitors book meetings straight from the widget against a real calendar.
- Syncs the customer's product catalog into the RAG store so the AI can recommend products mid-conversation.
- Fires events (new visitor, hot lead, booking, chat ended, …) to Slack, Zapier, and any custom webhook endpoint.
How it works
Shared auth model
Every integration uses one of four connection methods:
| Method | Used by | How it's stored |
|---|---|---|
| OAuth | HubSpot, GoHighLevel, Salesforce, Jobber, ServiceM8, Calendly, Google Calendar, Outlook Calendar, Slack, Shopify | Tenant CRM/calendar tokens are in the backend credential vault (credentials collection, one record per company + provider, key-fingerprint checked across pods in credential_keys); companies.<integration> keeps only non-secret state and a connected marker. Shopify/WooCommerce stay on ms-ai integrations rows. Refresh is automatic. |
| API key / secret | Cal.com, Semble, PracSuite (clinic key + our PRACSUITE_VENDOR_KEY), WooCommerce, and internal/admin providers (Stripe, Twilio, ElevenLabs, Ultravox, ScrapingBee) | Tenant keys go to the credential vault and are never returned (status endpoints expose a hint at most). Zapier and Lead API keys are stored as a SHA-256 hash + hint and shown once. |
| Webhook URL | Zapier, native custom webhooks | Customer-supplied destination URL + a signing secret. |
| Embed | Calendly inline scheduler, GHL calendar embed, GHL/HubSpot forms in the widget | No token for the embed itself; the booking/form is rendered inside the widget. |
Tokens are refreshed automatically by the owning service layer. Connection state is per-integration, and CRM tokens are select:false (GHL, HubSpot, Salesforce, Jobber, Google), so connection is judged on a marker field that is set at connect and cleared at disconnect — GHL go_high_level.location_id (backend) / access_token_expires_at (frontend), HubSpot access_token_expires_at + connection_status !== 'expired', Salesforce instance_url, Jobber account_id, ServiceM8 account_uuid, Google redirect_uri, Calendly connected_at, Outlook account_email, Cal.com event_type_id (bookable). The CRM port's REQUIRED_FIELDS is the projection to select.
Settings → Integrations screen (views/settings/integrations/Index.vue, 681605a4): cards are grouped into labelled sections — CRM (LeadConnector, HubSpot, Salesforce, Jobber), Field service (Simpro, Tapi, ServiceM8 — only when company.servicem8_allowed), Calendars & booking (the Booking calendar chooser as the section header, then Google Calendar, Outlook Calendar — rendered only when the server has MICROSOFT_* — Calendly, Cal.com, Semble, PracSuite, Custom Integration), Messaging & email (Your Mailbox, Slack, ManyReach), E-commerce (Shopify, WooCommerce), Automation (Zapier) — on an auto-fill grid (cards ≥ 250px). Each card shows the brand's official logo, self-hosted under public/assets/integrations/ on a neutral tile (23293354; the LeadConnector logo is no longer hot-linked from Freshdesk; WooCommerce keeps a generic icon because its trademark terms forbid logo use).
Booking calendar (tenant choice)
companies.calendar_choice ('' = automatic) picks which connected calendar the widget and every AI agent book into: GET/PUT /company/calendar-settings (CalendarSettingsController, resolveIntegrationCompany) returns { choice, effective, choice_connected, connected: [{id, label}] } and refuses a choice that isn't usable now. Unset or disconnected → the automatic ladder in scheduling/resolveProvider.js RUNGS (mirrored by ms-comm SchedulingClientHelper.resolveProvider — change both together). Frontend: BookingCalendarCard.vue (vee-validate + zod), refreshed via useCalendarSettings.notifyCalendarsChanged when a calendar card connects/disconnects. Details: Bookings — Sources.
Data sync direction
- Outbound (Knock Knock → tool):
CrmSyncQueueServicepushes new contacts and conversation summaries to the CRM; calendar services create events; e-commerce services don't push (read-only). - Inbound (tool → Knock Knock):
CrmEnrichmentQueueServicepulls CRM state back and caches it onPersonProfile.crm_enrichment; calendar/Calendly webhooks land bookings; Shopify/WooCommerce webhooks update the product RAG store.
Both CRM queues are Redis-backed, async, with retry/backoff — a slow or failing CRM never blocks request handling, and work is retried rather than dropped. Failures surface in the admin API Request Logs.
Events that trigger sync
| Event | What syncs |
|---|---|
| Chat ended | Contact info → CRM Contact, transcript summary → CRM note |
| Call ended | Same |
| Booking created | Calendar event / CRM event (where supported) + booking landed on the Person timeline |
| Lead score crossed hot | CRM property / tag update; Slack + webhook alerts |
| Form submitted | CRM Contact creation + identity capture |
Integration matrix
| Integration | Category | Auth | Direction | Plan | Owning service |
|---|---|---|---|---|---|
| HubSpot | CRM + calendar (Meetings) | OAuth (env-only app creds) | Bi-directional + webhooks | All (verify) | backend (+ ms-comm/ms-ai booking) |
| GoHighLevel | CRM | OAuth (marketplace app; v1 retired) / self-account | Bi-directional | All (verify) | backend + ms-ai |
| Google Calendar | Calendar | OAuth | Bookings + 15-min sync back | All (verify) | backend (OAuth relayed by ms-ai) |
| Calendly | Calendar | OAuth + webhook | Inbound (bookings) + embed | All (verify) | backend |
| Semble | Calendar (clinic) | API key + webhook | Bookings via widget/voice | All | backend + ms-comm + ms-ai |
| PracSuite | Calendar (clinic) | Vendor key + clinic API key, 30-min poll | Bookings via widget/voice | All (Coming soon without vendor key) | backend + ms-comm + ms-ai |
| Cal.com | Calendar | API key | Bookings + 15-min sync back | All | backend (+ ms-comm/ms-ai routing) |
| Outlook Calendar | Calendar | OAuth (Microsoft Graph) | Bookings + 15-min sync back | Hidden until MICROSOFT_* set | backend |
| ServiceM8 | CRM + job booking | OAuth add-on | Outbound (clients, Quote jobs, notes) + bookings | Beta, super-admin servicem8_allowed | backend |
| Slack | Communication | OAuth | Outbound (notifications) | All (verify) | backend + ms-communication |
| Zapier | Automation | Webhook URL + secret | Outbound (events) | All (verify) | backend |
| Shopify | E-commerce | OAuth | Inbound (product sync) | Pro (verify) | ms-ai |
| WooCommerce | E-commerce | API key + secret | Inbound (product sync) | Pro (verify) | ms-ai |
| Webhooks | Custom | Webhook URL + HMAC secret | Outbound (events) | All (verify) | backend |
| Tenant Mailbox | SMTP/IMAP app password (SecretCrypto) | Outbound (lead email) + inbound (reply/bounce poll) | All | backend (+ schedular) | |
| ManyReach | Cold email | API key | Outbound (prospect push) | Agent K | backend |
| Simpro + Tapi | Field service | API key / IMAP | Outbound (jobs, bookings, invoice notes) | All (verify) | backend + ms-ai |
GoHighLevel also provides a calendar (booking embed inside the widget) and automation event mirroring — covered on the GHL page.
Naming: all user-facing UI copy now says LeadConnector where it used to say GoHighLevel (frontend rename); code, config keys, and routes remain
go_high_level/ghl.
Configuration & options
- Connect: Settings → Integrations → pick the tool → authorize (OAuth) or paste credentials (API key). E-commerce and CRM integrations show a sync/connection status after connecting.
- Permissions: the web owner and team members granted
settings.integrationscan manage all integrations (was owner-only 403s) —GeneralHelpercheck in backend. - Toggles: Slack alerts are toggled in Settings → Notifications (
slack_new_visitor,slack_hot_lead); webhook/Zapier subscriptions are managed in Settings → Webhooks; calendarbooking_enabledand event-type selection live on the integration record. - Field mappings: CRM custom-field syncing requires explicit per-company mapping (notably GHL custom fields).
Behaviors & edge cases
- Disconnect removes the tokens and stops future sync. Historical data already synced stays put (contacts already in the CRM, transcripts already posted, bookings already on the timeline). Cached
crm_enrichmentIDs remain for reference but stop refreshing. GHL disconnect additionally uninstalls the app GHL-side (location/company/agency installs) — see the GHL page. - Enrichment-guessed contact push is off:
LeadContactSyncJob— the cron pushing enrichment-guessed (Clearbit/Apollo) contacts into GHL/HubSpot — is disabled globally (commented out ofSchedulerService). Event-driven sync of real captured leads is unaffected. - OAuth refresh failures (e.g. a user revokes access at the provider) silently degrade — the integration's status flips and admins should reconnect. Monitor connection status.
- Rate limits: high-volume tenants can hit CRM/Slack rate limits. Sync queues back off gracefully but don't drop; Slack/Zapier may drop under extreme volume — prefer hot-lead-only alerts.
- Dead webhook deliveries: a custom webhook whose deliveries fail 5 times in a row (after BullMQ retries) is auto-disabled with a
disabled_reasonand must be re-enabled; a Zapier hook answering410is removed — see Webhooks. - Connection health (Google Calendar / Shopify / WooCommerce cards):
useIntegrationStatus.describeIntegrationStatusnormalises ms-ai's per-platformGET /integrations/:idshape intook | warning | broken | unknown(pills Connected / Needs attention / Not working / Unverified), friendly issue lines, and the rawstatus/reasonshown verbatim so support can match a card to logs. Cards render "Checking…" until the status query resolves (a4bb3667) instead of flashing "Connect".
Plan & limits
- All integrations appear under Settings → Integrations on every plan screen, but availability per tier is plan-gated — Shopify/WooCommerce are marked Pro in the knowledge base; CRM/calendar/Slack/webhooks are "all plans." Treat exact tier gating as verify against the current package config.
- E-commerce re-embedding consumes AI credits; large catalog syncs take time.
Technical implementation
- CRM hub:
backend—CrmSyncQueueService(outbound),CrmEnrichmentQueueService(inbound),GoHighLevelService.js,HubspotService.js/PublicHubspotService.js,SlackService.js,WebhookController.js+WebhookModel/WebhookEventModel/WebhookLogModel. - E-commerce + calendar:
ms-ai—src/integrations/(Shopify/WooCommerce RAG sync, Google Calendar actions, integration entity withsync_status). - Nox CRM tools:
knox-crm(CRM queries),knox-automation-activity(GHL automation events),knox-action-feed,knox-recent-bookings,knox-visitor-bookings. - Subsystem deep dive: CRM & External Integration and Identity Graph.
ServiceM8 has its own page: ServiceM8. Salesforce and Jobber are covered in CRM & External Integration; Simpro + Tapi (including in-call technician booking) have their own page: Simpro.
What Nox can tell you
- Which integrations are connected, last sync time, and sync status per integration.
- Sync failures (recent webhook events / API request logs).
- Whether a specific contact is in the CRM (
knox-crm), and which leads have CRM IDs.