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 —
$filterhas nolike); create client + primarycompanycontactotherwise; additivefillContactfor a missing email/phone. Withcreate_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_joboff, 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_uuidis 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 andopening_hoursfrom 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)
| Route | Auth | Purpose |
|---|---|---|
GET /servicem8/install | public (signed single-use state) | OAuth callback |
GET /servicem8/install-url | passport | Authorize URL (?popup=1) |
GET /servicem8/status | passport | Card state: connected, account, connection_status, staff, job length, create_lead_job, has_opening_hours, configured, allowed |
POST /servicem8/verify | passport | Re-reads vendor.json (name, tz, opening hours); the card calls it on mount |
GET /servicem8/staff | passport | Active staff minus hide_from_schedule |
PUT /servicem8/settings | passport | booking_staff_uuids (must exist in the account), job_duration_minutes (15–480, multiple of 15), create_lead_job |
DELETE /servicem8/uninstall | passport | Disconnect |
PUT /company/:_id/servicem8-allowed | super 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'sCompanyModel.companies.servicem8_allowed(default false) — hides the card (views/settings/integrations/Index.vue) and refusesinstall-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_linksproviderservicem8(servicem8_client_idflat column);bookings[]booking_type: 'servicem8',servicem8_activity_uuid,servicem8_job_uuid(also onperson_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 viacrmLinks.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
Unsuccessfulwith the note "Booking cancelled by the customer via Next Level AI." No customer notification. - Ladder rung:
isServiceM8BookingEnabled= connected + ≥1booking_staff_uuids; after PracSuite, beforecustom_calender(both backend and ms-commSchedulingClientHelper). Widget acceptsbooking_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
| Env | Default | Notes |
|---|---|---|
SERVICEM8_CLIENT_ID / SERVICEM8_CLIENT_SECRET | — | App ID / secret from the ServiceM8 Development Partner account. Service doesn't load without both. |
SERVICEM8_REDIRECT_URI | BASE_URL + /servicem8/install | Host must match the Store Connect Return URL |
SERVICEM8_OAUTH_HOST / SERVICEM8_API_BASE | https://go.servicem8.com / https://api.servicem8.com/api_1.0 | |
SERVICEM8_SCOPES | vendor, staff, customers, contacts, jobs, job contacts, job notes, schedule | |
SERVICEM8_HANDSHAKE_TTL | 600 | Seconds |
SERVICE_SERVICEM8 | true |
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(globalservicem8),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=servicem8return),ServiceM8SettingsModal.vue; admin toggle onviews/admin/companies/Detail.vue("ServiceM8 integration"). - ms-communication:
SchedulingClientHelperladder rung +CompanyModelmirror (8ff8fd9). ms-ai:calendar-types.ts. widget:stores/widget.ts.
Related
- Bookings — Sources & Unified View · CRM & External Integration
- Simpro + Tapi — the other field-service integration