This page explains the Integrations hub, connector fields, lead conversion, simulator behavior, FlowOS contracts, custom app workflows, activity logs, support diagnostics, external mappings, settings, roles, and role-based notifications.
Workflow companion: If you need the plain-English "connect this, run this, then what changes" explanation with annotated screenshots, open Integration Workflow Manual.
Integrations Overview
Integrations is a tabbed hub for health, connector setup, lead intake, activity logs, contracts, and external mappings.
Tab/area
What it shows
Who uses it
Action
Connection
Health
Attention queue and provider ops metrics.
Vendor owner/admin.
Check what needs review.
Summarizes connector readiness and failures.
CRM
CRM connector settings and generated webhook credentials.
Vendor/admin.
Save, test, sync.
Imports leads and links external CRM records.
HR
HR connector settings.
Vendor/admin.
Save, test, sync.
Syncs staff/time-off style data when configured.
TicketPro
Support connector settings.
Vendor/admin/support manager.
Save, test, sync.
Creates support tickets from portal requests and AI receptionist follow-up handoff.
Ecommerce
Commerce connector settings.
Vendor/admin.
Save, test, sync.
Connects memberships, packages, vouchers, or ecommerce events.
FlowOS
Reception/automation webhook settings and active channels.
Vendor/admin.
Save, test, sync.
Sends booking/reception lifecycle events outward.
Custom Apps
Buyer-defined signed workflow payloads and mapping rules.
Vendor/admin/support.
Save, test, replay simulator.
Creates local records, benefits, or mappings from custom events.
Lead Intake
Imported CRM leads ready to convert.
Vendor receptionist/admin.
Create a booking from a lead.
Creates booking plus external mapping.
Activity
Sync/webhook/test logs with filters and selected payloads.
Support/admin.
Inspect failures or payloads.
Debugs external system behavior.
Contracts
Auth model, endpoints, inbound events, mappings.
Technical/support users.
Read integration contract.
Explains how BookFlow and external system agree.
Support Diagnostics
Preflight, support bundle, attention items, and activity evidence.
Support/admin.
Collect proof before changing credentials.
Separates hosting/config issues from connector bugs.
Health KPIs And Charts
Widget
What it counts
Source
How to read it
Why it matters
Health KPI cards
Connection count, ready/success/failure/last run style values.
Health cards generated by IntegrationController.
Each value is a connector operations snapshot.
Shows if integration layer needs attention.
Connector Health chart
Health values by label.
Health cards.
Higher or lower depends on the metric label; read with subtitle.
Quick visual check of connector readiness.
Activity Mix chart
Success logs, failed logs, webhook logs.
Sync logs.
Large failed slice means integration issues.
Helps support focus on failures.
Attention Queue
Connector issues needing review.
Attention items.
Severity value shows urgency.
Prevents silent failed syncs.
Provider Ops Metrics
Operational counters per provider.
Provider metrics summary.
Read provider label and metric hint.
Shows which connector is active/healthy.
Connector Setup Fields
Field
Shown for
Required?
Meaning
What changes
Common mistake
Name
All connectors
No
Friendly connector name.
Connection display label.
Leaving default name when multiple providers exist.
Status
All connectors
Yes
Active or inactive.
Whether connector is treated as enabled.
Saving credentials but leaving inactive.
Base URL
All connectors
No
External API base address.
Connection endpoint base.
Missing protocol such as https://.
API Token
All connectors
No
Credential used by connector.
Connection token storage.
Using production token in demo/test without care.
Connector Slug
CRM
No
CRM connector identifier.
CRM settings payload.
Mismatch with CRM configuration.
Department ID
TicketPro
Yes for live handoff
Support department destination.
TicketPro settings.
Wrong department sends tickets to wrong queue.
Category ID
TicketPro
Yes for live handoff
Support category destination.
TicketPro settings.
Unmapped category in external system.
Organization ID
TicketPro
No
Support organization destination.
TicketPro settings.
Using vendor id instead of TicketPro org id.
Outbound Webhook URL
FlowOS
No
Where BookFlow sends outbound events.
FlowOS webhook settings.
URL cannot receive BookFlow payloads.
Active Channels
FlowOS
No
Web chat, WhatsApp, SMS, phone channels.
FlowOS channel settings.
Checking channels not actually configured externally.
Event Templates
Custom Apps
No
Allowed custom workflow payload shape.
Controls simulator and live event mapping.
Accepting fields that are not mapped to local records.
Field Mappings
Custom Apps
No
How remote payload fields become BookFlow customer, booking, support, or benefit fields.
Creates local record and external mapping behavior.
Mapping customer email incorrectly, which breaks wallet matching.
Inbound Webhook URL
Saved connector
Read-only
URL external system should call.
Generated from provider and webhook key.
Copying URL before connector is saved.
Webhook Secret
Saved connector
Read-only
Secret used to verify inbound calls.
Generated connector secret.
Sharing publicly or changing external system without updating.
Connector Actions
Action
Confirmation/loading
System result
Success feedback
Error meaning
Save Connection
Yes/no confirmation, saving loader.
Creates or updates integration connection and settings.
Toast/flash says saved.
Validation, invalid URL, missing permission, or database error.
Test
Yes/no confirmation, testing loader.
Runs health check and records log.
Success/failure feedback.
Credentials, URL, or external system problem.
Sync
Yes/no confirmation, syncing loader.
Runs provider sync and records logs/mappings.
Sync result feedback.
External API, payload, mapping, or validation issue.
Lead Intake
Field/column
Required?
Meaning
What changes
Common mistake
Lead name/email/company
Read-only
Imported CRM lead identity.
No change until conversion.
Assuming every lead is already a booking.
Score/status
Read-only
CRM lead quality and state.
Helps prioritize conversion.
Ignoring low score leads may be okay depending on process.
Location
Yes
Branch for converted booking.
Booking location.
Choosing branch not linked to selected service.
Service
Yes
Service lead wants.
Booking service.
Guessing service without confirming with customer.
Staff
No
Preferred staff or any staff.
Booking staff assignment if selected.
Selecting unavailable staff.
Booking date
Yes
Appointment date.
Booking scheduled date.
Using a date before checking availability.
Slot value
Yes
Appointment time.
Booking scheduled time.
Typing unavailable time.
Convert
Action
Create booking from CRM lead.
Booking and external mapping record.
Converting same lead twice if status/mapping not checked.
Example: A CRM lead named Olivia asks for recovery massage. Maya chooses Downtown Studio, Recovery Session, Avery, tomorrow at 10:00, then converts. BookFlow creates a normal booking and records that the CRM lead maps to that booking.
CRM Program Ads Handoff
Step
Required state
BookFlow result
CRM responsibility
Proof
Load Programs Campaigns tab
Active CRM connection with an ads-capable API token.
BookFlow lists CRM ad accounts returned by `/api/crm/v1/ads/ad-accounts`.
CRM decides which provider/ad accounts are connected and available.
CRM Ad Account dropdown appears in Programs.
Create paid ad draft
Budget, dates, objective, landing URL, ad account, and creative fields are valid.
BookFlow posts a draft request to `/api/crm/v1/ads/ad-drafts` and creates a local paid ads retention campaign.
CRM validates workspace/account ownership, idempotency, and draft persistence.
Programs Activity shows Paid ad draft in CRM.
Review in CRM
CRM response includes campaign ID, draft ID, draft status, activation status, and cockpit URL.
BookFlow stores CRM IDs in campaign metadata and an external ad-draft mapping.
CRM handles approval, activation, publishing, provider sync, and audit trail.
CRM cockpit link opens from Programs Activity.
Boundary: BookFlow creates CRM ad drafts only. It does not store Meta/Facebook or Google credentials and does not publish or activate ads.
Activity, Contracts, And Mappings
Area
Field/column
Meaning
Source
Action
Activity filters
Provider
CRM, HR, TicketPro, Ecommerce, FlowOS.
Log provider.
Filter logs by system.
Activity filters
Status
Success or failed.
Log status.
Find errors quickly.
Activity filters
Run Type
Test, sync, webhook.
Log run_type.
Separate manual tests from real webhooks.
Activity filters
Direction
Pull or push.
Log direction.
Know whether data came in or went out.
Activity filters
Search
Endpoint or error text.
Log endpoint/error data.
Find a specific failure.
Activity table
Provider
Which connector produced log.
Sync log.
Identify external system.
Activity table
Run
Run type and direction.
Sync log.
Understand the operation.
Activity table
Status
Success or failed badge.
Sync log.
Spot failures.
Activity table
Endpoint
External endpoint used.
Sync log endpoint.
Debug API route.
Activity table
When
Log creation time.
Sync log timestamp.
Match with external logs.
Selected Activity
Request Payload
What BookFlow sent or received.
Sync log payload.
Debug mapping/validation.
Selected Activity
Response Payload
External response or local handling response.
Sync log payload.
Explain failures.
Connector Contracts
Auth, outbound, inbound
Technical agreement for each connector.
Contract definitions.
Help setup/integration teams.
External Record Mappings
Provider, remote type/id, local type/id
Links outside records to local BookFlow records.
Mapping table.
Prevent duplicate conversion and trace source.
FlowOS, Custom Apps, And Simulator Proof
Area
Contract behavior
Simulator behavior
Support proof
FlowOS outbound
BookFlow sends receptionist and booking lifecycle events to the saved outbound webhook URL.
Test/sync records show payload shape without requiring a live FlowOS endpoint.
Activity log, endpoint, response payload, and contract tab.
FlowOS inbound
Incoming conversation context can become receptionist context and follow-up work.
Seeded replay can show the conversation path without opening external channels.
Receptionist conversation and activity payload.
Custom app workflow
Signed custom payload maps into customer, booking, entitlement, or support records.
Simulator creates the same local result with known fixture data.
External mapping row, activity drawer, and local record link.
Ecommerce entitlement
Paid order events can create membership, package, voucher, or note-only benefits.
Replay proves wallet entitlement behavior without a live store.
Customer wallet, Programs ledger, and activity proof.
Support diagnostics
Preflight and support bundle gather environment, scheduler, storage, mail, provider, and webhook readiness.
Support can compare simulator success with live connector failure.
bookflow:preflight --json and bookflow:support-bundle.
Currency code and symbol for catalog and new bookings.
Owner/admin only.
Services, packages, memberships, vouchers, new invoices.
Expecting historical invoices to be rewritten.
Website section
Homepage and public CMS pages.
Vendors with manage tenant settings permission.
Storefront header/footer and trust pages.
Editing settings when the page is actually in Website.
Administration sidebar
Notifications and activity logs visibility.
Users with the relevant role/permission.
Role-based navigation and notification queries.
Showing admin-only sections to staff without permission.
Notifications
Role-scoped notification list/dropdown.
Platform admin sees all; vendor sees tenant items; customer sees own items.
Notification repository and tenant/customer relationships.
Expecting every user to see the same alerts.
Activity logs
Audit trail of admin/system events.
Admin/authorized vendor roles.
Useful for support and completed-booking edit approvals.
Using it as a customer-facing history.
Roles and permissions
Who can manage settings, bookings, notifications, admin areas.
Platform owner/admin.
Controls sidebar, actions, and route access.
Giving broad admin access instead of specific permissions.
Integration Examples
CRM Lead To Booking
CRM sends a lead. BookFlow stores it. The vendor opens Lead Intake, chooses location/service/staff/date/time, and converts. The created booking appears in Bookings, Calendar, Reports, and Customer Portal.
TicketPro Support
A customer sends a support request or the AI receptionist flags human follow-up. If TicketPro is active, BookFlow creates one support case, stores the external ticket reference, and locks repeat BookFlow follow-up.
FlowOS Reception
FlowOS settings define where outbound events go, which channels are active, and which receptionist or lifecycle events are shared.
Custom App Workflow
A signed custom event can add a booking, support item, membership, package, voucher, or mapped local record when fields match the saved contract.
Activity Debugging
If a sync fails, filter Activity by provider and failed status, open the eye icon, compare request payload to response payload, then fix credentials, endpoint, mapping, or hosting support diagnostics.
TicketPro Receptionist Handoff
Setup state
Receptionist behavior
Required fields
Buyer proof
TicketPro active
Receptionist detail shows Create TicketPro Follow-up Case. Submitting creates one requester ticket and marks the conversation TicketPro Handoff.
Base URL, API token, active status, department ID, category ID, and customer email on the conversation.
Ticket number/status/priority appears on the conversation and duplicate follow-up is disabled.
TicketPro inactive or missing
Receptionist detail hides TicketPro case creation and shows Resolve Locally plus Configure TicketPro.
No external credentials required for local resolution.
Resolved status appears with staff note, and repeat follow-up is disabled until reopen.
TicketPro configured later
New open conversations can use TicketPro. Already locally resolved conversations must be reopened first.
