Skip to main content

ServiceM8

Audience: Sales, support, engineering · Where in app: Settings → Integrations → Field service → ServiceM8 card ("CRM & job booking", Beta badge) · Plan availability: All plans, but hidden per company until a super admin enables it (companies.servicem8_allowed)

ServiceM8 is job-management software for trade businesses. The integration (backend 469e6319e + follow-ups, 2026-11-13/16) is both a CRM port adapter (client + primary contact, Quote job, job-diary notes, job-status stage) and a scheduling port adapter (Work Order job + scheduled job activity). It is shaped after Jobber: public OAuth add-on, signed single-use state parked in Mongo, rotating refresh tokens behind a Redis lock, tokens in the credential vault.

What it does​

  • Connect via ServiceM8 OAuth (popup or same-tab). Connection marker: servicem8.account_uuid.
  • Lead sync (CRM fan-out): find client by email, then phone (no name search — $filter has no like); create client + primary companycontact otherwise; additive fillContact for a missing email/phone. With create_lead_job (default on) each session gets one Quote job, Web lead via Next Level AI: <who> + first visitor message + page.
  • Notes on the session's lead job (else the client's newest open Quote/Work Order; with create_lead_job off, only on an existing job): lead-source note, chat transcript (one per chat, chats.servicem8_note_id), AI call summary (service_rooms.servicem8_note_id).
  • Stage (getContactStage): furthest job status — Completed → Job completed (won), Work Order, Quote, Unsuccessful (lost).
  • Booking: availability, book, find, reschedule, cancel through scheduling/adapters/ServiceM8Adapter.js.

How it works​

OAuth​

GET /servicem8/install-url?popup=1 (passport, canManageIntegrations, 403 unless servicem8_allowed, 503 when the service isn't loaded) creates a servicem8_oauth_handshakes row (state = nonce.HMAC(client_secret), TTL index on expires_at, SERVICEM8_HANDSHAKE_TTL 600 s) and returns https://go.servicem8.com/oauth/authorize. ServiceM8 doesn't document echoing state, so it also rides in the redirect_uri as kk_state (plus kk_popup=1 for the popup flow) — only the host has to match the Store Connect Return URL.

GET /servicem8/install (public) verifies the signature, consumes the handshake (findOneAndDelete), exchanges the code, reads vendor.json, and:

  • One live link per ServiceM8 account — any other company holding the same account_uuid is disconnected first.
  • Reconnecting to a different account clears booking_staff_uuids (old staff would make every slot look free).
  • Stores tokens in the vault (provider: 'servicem8'), access_token_expires_at = expires_in − 120 s, account name/timezone and opening_hours from the vendor.

Popup flow answers with a tiny page that postMessages { type: 'servicem8_oauth_result', success, error } to the portal origin and closes; same-tab flow redirects to /settings/integrations?integration=servicem8&success=…&error=…. Error codes are specific so the toast says where it failed: handshake_expired, bad_state, encryption_key_mismatch (vault key differs between pods — see CredentialVault), token_missing, token_exchange_<status>, account_lookup_<status>, http_<status>, or ServiceM8's own error.

Refresh: proactive within 60 s of expiry and once on 401, deduped in-process and serialised by Redis lock servicem8:refresh:<company> (30 s PX, 40 × 250 ms wait). A 400/401 on refresh sets connection_status: 'expired' ("Refresh token rejected — please reconnect ServiceM8"); request() then refuses until reconnect. Disconnect (DELETE /servicem8/uninstall) only drops our tokens — ServiceM8 has no revoke endpoint.

Routes (routes/servicem8Routes.js)​

RouteAuthPurpose
GET /servicem8/installpublic (signed single-use state)OAuth callback
GET /servicem8/install-urlpassportAuthorize URL (?popup=1)
GET /servicem8/statuspassportCard state: connected, account, connection_status, staff, job length, create_lead_job, has_opening_hours, configured, allowed
POST /servicem8/verifypassportRe-reads vendor.json (name, tz, opening hours); the card calls it on mount
GET /servicem8/staffpassportActive staff minus hide_from_schedule
PUT /servicem8/settingspassportbooking_staff_uuids (must exist in the account), job_duration_minutes (15–480, multiple of 15), create_lead_job
DELETE /servicem8/uninstallpassportDisconnect
PUT /company/:_id/servicem8-allowedsuper admin (user_type === 'admin'){ enabled } — the only writer of servicem8_allowed; CompanyController.update strips it

Data​

  • companies.servicem8 (strict subdoc): access_token_expires_at, account_uuid, account_name, account_timezone, opening_hours[] {day, start_mins, end_mins}, enabled, connection_status (ok|error|expired), connection_error, last_refresh_at, last_verified_at, booking_staff_uuids[], job_duration_minutes (60), create_lead_job (true). Mirrored in ms-communication's CompanyModel.
  • companies.servicem8_allowed (default false) — hides the card (views/settings/integrations/Index.vue) and refuses install-url. Turning it off does not disconnect an existing connection.
  • user_sessions.servicem8_lead_job_uuid (claimed with a conditional update before the job is created, so two concurrent syncs can't open two Quote jobs); crm_links provider servicem8 (servicem8_client_id flat column); bookings[] booking_type: 'servicem8', servicem8_activity_uuid, servicem8_job_uuid (also on person_profiles.bookings[]).

CRM port​

crm/resolveProvider order is now ghl → hubspot → salesforce → jobber → servicem8; connected = account_uuid + enabled !== false + not expired. Capabilities: contact get / find by email & phone / create / update, note_create, contact_stage — nothing else (no name search, tags, custom fields, deals, workflows). CrmSyncHelper fans out to it like the other CRMs (options.skipServiceM8); after a first link it back-fills the chat transcript and session calls (logChat / logCalls). ChatTranscriptEmailJob and CallController queue sync-servicem8-chat-transcript / sync-servicem8-call-note on crm-sync.

Scheduling adapter​

ServiceM8 has no free-slot API and nothing stops a double booking, and every timestamp is account-local wall clock with no offset (zone = account_timezone, else company tz).

  • Availability = ServiceM8 opening hours (else company working_hours, else 9–5) minus each ticked staff member's scheduled activities; a slot is free when any ticked staff member is free. Step = min(job length, 60) minutes; slots are built on wall-clock times so DST days work (9ef2146e6).
  • Book (needs email or phone) runs under a per-company Redis lock (60 s): re-reads the schedule, takes the first ticked staff member still free (else SLOT_TAKEN), resolves/creates the client, creates a Work Order job (Booked via Next Level AI: <name> + notes) and a job activity. provider_event_id = activity uuid. Links the client to the session via crmLinks.setLink.
  • Reschedule moves the activity, keeping the same staff member if free, else another ticked one.
  • Cancel deletes the activity (soft delete in ServiceM8) and, if no other activity remains on the job, sets it Unsuccessful with the note "Booking cancelled by the customer via Next Level AI." No customer notification.
  • Ladder rung: isServiceM8BookingEnabled = connected + ≥1 booking_staff_uuids; after PracSuite, before custom_calender (both backend and ms-comm SchedulingClientHelper). Widget accepts booking_type: 'servicem8' (d5167ab); ms-ai lists it among backend-only calendar types (ba638033c).
  • No sync job: moves/cancels made inside ServiceM8 are not applied back to bookings[] (find/reschedule/cancel read ServiceM8 live).

Configuration & environment​

EnvDefaultNotes
SERVICEM8_CLIENT_ID / SERVICEM8_CLIENT_SECRET—App ID / secret from the ServiceM8 Development Partner account. Service doesn't load without both.
SERVICEM8_REDIRECT_URIBASE_URL + /servicem8/installHost must match the Store Connect Return URL
SERVICEM8_OAUTH_HOST / SERVICEM8_API_BASEhttps://go.servicem8.com / https://api.servicem8.com/api_1.0
SERVICEM8_SCOPESvendor, staff, customers, contacts, jobs, job contacts, job notes, schedule
SERVICEM8_HANDSHAKE_TTL600Seconds
SERVICE_SERVICEM8true

Set the keys in backend AND schedular: crm-sync workers and ChatTranscriptEmailJob run on the schedular, and global.servicem8 missing there silently drops notes. As of 2026-11-16 flux sets SERVICEM8_CLIENT_ID/_SECRET only in Apps/DEV/backend (not DEV schedular, nothing in PROD). Tokens are in the credential vault, so SECRET_ENCRYPTION_KEY must match across pods — a mismatch is the encryption_key_mismatch connect error.

Technical implementation​

  • backend: services/ServiceM8Service.js (global servicem8), controllers/ServiceM8Controller.js, models/ServiceM8OauthHandshakeModel.js, services/crm/adapters/ServiceM8Adapter.js, services/scheduling/adapters/ServiceM8Adapter.js, helpers/CrmSyncHelper.js (_syncContactToServiceM8, _openServiceM8LeadJob, syncServiceM8*), configs/servicem8.js. Spec: test/servicem8-scheduling-adapter.spec.js.
  • frontend: components/integrations/ServiceM8Card.vue (popup connect, desktop opens the browser, ?integration=servicem8 return), ServiceM8SettingsModal.vue; admin toggle on views/admin/companies/Detail.vue ("ServiceM8 integration").
  • ms-communication: SchedulingClientHelper ladder rung + CompanyModel mirror (8ff8fd9). ms-ai: calendar-types.ts. widget: stores/widget.ts.