Simpro + Tapi
Audience: Sales, support, engineering · Where in app: Settings → Integrations → Simpro / Tapi cards · Plan availability: All plans (verify)
Simpro is the job-management system for trade businesses (plumbing, electrical, HVAC). The integration lets the AI voice agent create a Simpro job during a call — and, with auto-scheduling on, book it against a free technician while the caller is on the line — chases overdue invoices with outbound AI calls, and turns Tapi work-order emails into Simpro jobs.
What it does
- Flow A — in-call jobs: the voice agent classifies the work, maps it to a cost centre, and creates the job (title-cased name, spoken address split into Simpro's street/suburb/city/postcode, AI-picked trade tag, optional call-summary note).
- Auto-scheduling (2026-09-11): the agent offers real times from Simpro's technician availability and creates the job already scheduled.
- Flow B — invoice chasing:
SimproInvoiceChaseJobplaces outbound AI calls for overdue invoices and writes the outcome as an invoice note. - Flow C — Tapi:
TapiPollJobreads work-order emails over IMAP → ms-ai field extraction → Simpro job (optionally scheduled).
How it works
Auth: Build URL + user-supplied API key (simpro.api_key, select:false). The build URL is restricted to simPRO hosts (security review, 445133820). Multi-company builds pick simpro_company_id at connect. Phone search in Simpro must be digits-only.
Cost-centre mapping: simpro.cost_centre_map (classification → cost centre), default_cost_centre_id, high_ticket_classifications (never auto-booked — human callback). SimproService.resolveCostCentre token-matches the agent's classification against the map.
Call note: simpro.call_note_enabled (default on) — ms-comm pushes POST /simpro/call-note the instant a call summary is persisted; the note subject carries "Status: Booked".
Auto-scheduling
Settings on simpro.auto_schedule (Cost Centres modal, "Book appointments during the call"):
| Field | Default | Meaning |
|---|---|---|
enabled | false | Agent offers slots and books; off = job logged unscheduled + callback |
tapi_enabled | false | Also book the earliest free slot on jobs created from Tapi orders |
duration_mins | 120 | Appointment block length |
lead_time_hours | 2 | No slot sooner than this (0–168) |
horizon_days | 7 | Look-ahead (1–30) |
window_start/_end | 08:00/16:00 | Offering window, build-local HH:MM |
weekdays_only | true | Skip Sat/Sun |
excluded_staff_ids | [] | Never booked for any cost centre |
staff_preferences | {} | { <costCentreId>: [staffId…] } ranked; a non-empty list is exclusive |
Flow: ms-ai tool check_simpro_availability (workspace tool synced alongside create_simpro_job; prompt section branches on auto-scheduling) → POST /simpro/agent/availability → SimproService.findAvailableSlots: GET /available/technicians/ (free ranges per technician, already minus jobs and leave) for the cost centre with Duration, Limit: 50 (Simpro defaults to 10) and TechnicianIDs when a preference list exists; filtered to employees (plant comes back as technicians; /staff/ includes archived people), minus exclusions; clipped to the window, lead time, and weekdays on a grid_mins grid (wall-clock, DST-safe). _spreadOffers returns ≤8 offers: one per start, max 3 per day, a job length apart; rank wins a start, unranked technicians share by load. Labels are dddd D MMMM [at] h:mm A. A preferred day that's full returns alternatives (requested_date_available: false); high-ticket classifications and a disabled setting return ok:false with an instruction, never an error. The agent then calls create_simpro_job once with scheduled_start + staff_id copied verbatim from the chosen slot.
Booking safety: createJob is idempotent per call key (simpro:job:<company>:<key>): an identical replay keeps the booking; a replay with a new slot moves it (rescheduleJob — new block first, old block deleted after; a failed move keeps the old one, move_failed). Writes retry only on 429; a schedule that landed despite a failed POST is recovered from the list; a lost slot logs the job unscheduled rather than failing it. ScheduleRate is mandatory on a block — if the key can't read labour rates (schedule_rate_ok === false), no slots are offered (unavailable: 'labour_rates') and the modal says to grant Setup → Labour Rates. TimeStart/TimeEnd filters drop ranges instead of clipping, and blank working hours read as 00:00–23:59 (hence the "Never book" list).
Review surface: the booking is stored on inbound_outbound_calls.simpro_booking; ms-comm's transcript email prefixes the subject BOOKED <appointment> — and adds an "Appointment booked" card. Tapi rows store scheduled_start / scheduled_label / scheduled_staff_name (shown under the job number in the Work Orders modal) — Tapi's accept step needs a date.
Invoice chasing (Flow B)
simpro.invoice_chase (auto / manual-approval mode, attempts, spacing, grace days, minimum balance, call window, outbound agent). SimproInvoiceChaseJob runs every 2 min; per-call context is served token-guarded at GET /simpro/invoice-chase/:chase_id/context. Do-Not-Call customers are never dialled. The list pull fails loudly past 25k rows instead of truncating. Recording links in invoice notes use the vendor-neutral /recordings/… routes.
Tapi (Flow C)
Tapi has no API: TapiPollJob (every 2 min) reads a dedicated IMAP mailbox filtered by sender, records work-order emails, ms-ai extracts fields (accepting the build's tag vocabulary), and TapiService creates the Simpro job — scheduled via findAvailableSlots(max_slots: 1) when auto_schedule.tapi_enabled.
Configuration & options
| Action | Route | Auth |
|---|---|---|
| Connect / select company | POST /simpro/connect, /simpro/select-company | passport |
| Status / disconnect | POST /simpro/status, /simpro/disconnect | passport |
| Cost centres / staff | POST /simpro/cost-centres, /simpro/staff | passport |
| Save mapping + auto-schedule | POST /simpro/cost-centre-map | passport |
| Invoice chase settings/queue | POST /simpro/invoice-chase-settings, /queue, /calls, /action, /test-run, /invoices | passport |
| Agent config / create job | POST /simpro/agent/config, /simpro/agent/create-job | x-api-key |
| Agent availability | POST /simpro/agent/availability | x-api-key |
| Call note (from ms-comm) | POST /simpro/call-note | x-api-key |
ms-ai: POST /elevenlabs/sync-simpro-tool re-syncs the voice agent's Simpro tools; POST /agents/pick-job-tags picks one tag from the build's catalogue (an "AI-Booked" marker exists but is disabled). A workspace-backed tool that failed to attach is dropped from the prompt.
Behaviors & edge cases
- "Nobody is assigned to this cost centre" — Simpro's availability is per cost centre; assign technicians under People → Employee → Cost Centers or no slot can be offered.
- Slot taken between offer and create — job created unscheduled, not failed; the office sees it in the transcript email.
- Timezone — slots are computed in the build's timezone (
getBuildInfo), not the tenant's KK timezone.
Technical implementation
backend:app/services/SimproService.js,TapiService.js,app/controllers/SimproController.js,app/routes/simproRoutes.js,app/jobs/SimproInvoiceChaseJob.js,TapiPollJob.js; modelsCompanyModel.simpro,TapiWorkOrderModel,InboundOutboundCallModel.simpro_booking. Spec:test/simpro-availability.spec.js.ms-ai:src/integrations/actions/simpro/simpro-tool.service.ts,src/elevenlabs/elevenlabs.service.ts(prompt + tool sync).ms-communication: transcript email templateinboundOutboundCallTranscript.html.- Frontend:
SimproCostCentresModal.vue,SimproStaffPreference.vue,SearchablePicker.vue,TapiWorkOrdersModal.vue.