BSP Ecosystem + Handshake Reference

 Customer phone → 3CX (VoIP) → answered by tech OR voicemail
        │
        ├── answered → manual ST entry by Ashton
        └── voicemail → callback flow (70% book next day per MH)

📤 Direction

Customer → 3CX → (manual) ServiceTitan · voicemail → (manual) callback

🔐 Auth

PSTN → 3CX trunk · ST entry via Ashton user session

📡 Protocol

SIP (inbound), manual data entry (ST)

📍 Endpoint(s)

BSP published phone (913) 963-1029 · 3CX config API if programmatic lookup needed

⚡ Trigger

Customer dials the number

📦 Payload

Caller CID, call duration, recording URL (3CX side)

🎯 Purpose

First-touch customer contact → booking or lead

⚠️ Failure mode

Extension loop (Rule 14 Apr 21 incident — caller hits dead extension, can't reach anyone). 30% of after-hours voicemails don't convert.

🔄 Retry

Human callback; no automated retry

📝 Observability

3CX call log via THREECX_API_URL; MH bsp-apr20-memory-backfill-3cx-afterhours-routing

Sources: MH apr17-3cx-toggle-retired-permanent-fix, apr18-3cx-officehours-8am-correction, apr20-memory-backfill-3cx-afterhours-routing, apr21 Tim Mahony incident.

 Customer SMS → Telnyx number → webhook (POST) → /api/telnyx/inbound
        │
        ├── STOP/HELP → TCPA opt-out handler
        ├── Lead text → ServiceTitan lead creation
        └── Other reply → Slack to Ashton + titan.telnyx_messages log

📤 Direction

Customer → Telnyx → Nexus → ServiceTitan (outbound: Nexus → Telnyx → Customer)

🔐 Auth

Telnyx webhook signature (HMAC-SHA256). ST: OAuth2 per tenant credentials

📡 Protocol

Inbound webhook (JSON POST) · Outbound REST (Telnyx API v2)

📍 Endpoint(s)

Inbound: https://[VM]/api/telnyx/inbound route not yet built · Outbound: https://api.telnyx.com/v2/messages

⚡ Trigger

Customer sends SMS to BSP Telnyx number

📦 Payload

Inbound: message body, from_number, message_id, direction. Outbound: to, text, messaging_profile_id

🎯 Purpose

2-way SMS: customer inquiries + booking confirmation handshake + dismissed-queue rescue alerts

⚠️ Failure mode

Telnyx retries webhook 3x if our endpoint returns non-2xx. If Telnyx is down (very rare), messages queue on their end.

🔄 Retry

Telnyx built-in webhook retries · outbound: exponential backoff if we get 5xx

📝 Observability

Telnyx dashboard · titan.telnyx_messages table (once Tim's worker ships)

Sources: Codebase Doc §38 SMS+Voice rails · Tim handoff plan Apr 23 update.

 cron (hourly) → fetch_gbp_reviews_for_city(city_slug)
        → Internal /api/gbp/reviews or /api/gbp/reviews/recent
        → (internal wraps) mybusiness.googleapis.com
        → returns reviews[] with author, rating, text, date
        → pipeline filters by city + landmarks mention

📤 Direction

Pipeline → internal GBP wrapper → Google My Business API

🔐 Auth

OAuth2 access token stored on Nexus for BSP's GBP account

📡 Protocol

REST (JSON)

📍 Endpoint(s)

Internal: /api/gbp/reviews/recent?limit=400 · External: mybusiness.googleapis.com

⚡ Trigger

Pipeline runs (location_page_mining.py, nexus_doc_refresh.py, standup_autobuild.py)

📦 Payload

Request: limit, optional filters. Response: review objects with star rating, text, author, date, mentioned landmarks/cities

🎯 Purpose

Populate location page reviews section with real customer voices + mention detection

⚠️ Failure mode

Token expiry silently fails. API quotas (very high for GBP but finite).

🔄 Retry

Pipeline falls back to cached review_intelligence.db on failure

📝 Observability

Nexus logs · local SQLite review_intelligence.db

Sources: /opt/nexus/titan/api/gbp.py · /opt/nexus/titan/location_page_mining.py.

 Multiple callers (titan_sync_daemon, eta_relay, auto_dispatcher, referral_weapon, money_finder)
        → api.servicetitan.io/{crm|jpm|dispatch|telecom|settings}/v2/tenant/4316907157/...
        → OAuth2 bearer token per-tenant
        → returns jobs, customers, dispatch, calls

📤 Direction

Pipeline → ServiceTitan (bidirectional — we read jobs/customers, we write leads/campaigns)

🔐 Auth

ServiceTitan OAuth2 (client credentials grant) · tenant-specific headers

📡 Protocol

REST (JSON)

📍 Endpoint(s)

api.servicetitan.io/crm/v2/tenant/4316907157/leads (create lead — see Snippet #97 campaignId fix) · /jpm/v2/tenant/.../jobs (read jobs) · /telecom/v2/tenant/.../calls (call history) · /dispatch/v2/tenant/.../... (fleet dispatch) · /settings/v2/tenant/... (config)

⚡ Trigger

Cron (every 15 min: fleet_availability) · event (contact form submit → lead create) · daily (titan_sync_daemon)

📦 Payload

Varies per endpoint. Lead creation requires campaignId, businessUnitId, jobTypeId, customer object (learned via Apr 21 Tim Mahony incident).

🎯 Purpose

Sync customer + job data into local Postgres · create leads from web forms · measure funnel health

⚠️ Failure mode

Missing campaignId → 400 Bad Request (exact bug Apr 20). Token expiry → 401. Rate limits under heavy pipeline runs.

🔄 Retry

Exponential backoff on 5xx; token refresh on 401

📝 Observability

titan.jobs, titan.customers tables · Nexus logs

Sources: /opt/nexus/titan/api/*.py · MH bsp-apr20-contact-form-pipeline-full-fix · MH bsp-apr21-tim-mahony-incident-snippet97.

 Pipeline → /wp-json/wp/v2/pages/{id}                  (GET/POST/PUT)
         → /wp-json/code-snippets/v1/snippets          (GET/POST/PUT/DELETE)
         → /wp-json/bsp/v2/cache/purge                 (POST)
         → Basic auth with claude-api application pw

📤 Direction

Pipeline → WordPress (read + write page content, manage snippets)

🔐 Auth

Basic auth with Application Password (claude-api user · password in .env as BRICKS_WP_APP_PASSWORD)

📡 Protocol

REST (JSON)

📍 Endpoint(s)

See diagram above. Namespace discovery at /wp-json/ lists: wp/v2, code-snippets/v1, bricks/v1, bricks-ai-studio/v1, litespeed/v1-v3, bsp/v1-v3, hostinger-*, mcp.

⚡ Trigger

Pipeline run (page regeneration) · one-shot ops (consolidation, cache purge)

📦 Payload

Pages: title, content, meta. Snippets: name, code, scope, priority, active.

🎯 Purpose

Page content generation · snippet lifecycle (create, activate, deactivate, delete) · cache invalidation

⚠️ Failure mode

update_post_meta returns false on success (WP internal hash-compare false positive; Apr 23 discovery) — use $wpdb->update fallback · PUT on snippet active field inconsistent across Code Snippets plugin versions

🔄 Retry

Idempotent operations (PUT) · DELETE + POST if PUT active flag doesn't persist

📝 Observability

Nexus logs · WP debug.log · Code Snippets admin UI

Sources: Codebase Doc §28.2 update_post_meta false · §28.1 PUT active inconsistent.

 HTTP request → WP bootstrap → init action → snippets load
        │
        ├── wp_head hook: CSS snippets inject into 
        ├── wp_footer priority 99999: CSS/JS snippets inject before 
        ├── template_redirect priority 1: ob_start snippets rewrite HTML
        └── Bricks renders its own content_2 meta into main

📤 Direction

Plugin → WP render pipeline → final HTML output

🔐 Auth

None (runs server-side as WP)

📡 Protocol

PHP action/filter hooks

📍 Endpoint(s)

Hook: wp_footer priority 99999 (our standard) · template_redirect priority 1 (server-side img src swap) · init (one-shot mutations)

⚡ Trigger

Any page load · admin request · REST call

📦 Payload

PHP source code stored in wp_snippets table · executed in-process

🎯 Purpose

Runtime code injection without touching theme files (best-practice per Bricks Academy)

⚠️ Failure mode

PHP fatal errors → snippet auto-deactivates (Code Snippets plugin safety) · infinite loops → admin hangs until execution limit

🔄 Retry

None — failed snippet is inactive until fixed

📝 Observability

WP debug.log · Code Snippets admin Error log panel

Sources: Codebase Doc §27.5 Custom Code integration · Academy lesson 01_custom_code.md.

 Builder save → write to post_meta._bricks_page_content_2 (PHP-serialized array)
        → Bricks 2.3.2 quirk: some 4-value properties serialize as literal "Array" string
        → On frontend render, Bricks parses meta → emits CSS (inline or external)

📤 Direction

Builder UI → post meta · Render pipeline ← post meta

🔐 Auth

WP admin session (builder) · post meta public-read, admin-write

📡 Protocol

PHP direct DB access via get/update_post_meta

📍 Endpoint(s)

Meta keys: _bricks_page_content_2 (~49KB for OP 258), _bricks_template_conditions, _bricks_editor_mode, _bricks_template_type

⚡ Trigger

Builder save · Claude Code native-save (mutating tree directly)

📦 Payload

PHP-serialized array of element definitions (section → container → block → div hierarchy, each with id/name/parent/children/settings)

🎯 Purpose

Source-of-truth for visual page structure

⚠️ Failure mode

wp_postmeta.meta_value must be LONGTEXT (verified ✓ on staging). Bricks Array serialization bug for 4-value padding/margin/border-radius.

🔄 Retry

Data is idempotent; failed write can be retried. Use $wpdb->update when update_post_meta no-ops.

📝 Observability

MySQL direct query · Bricks builder preview

Sources: Codebase Doc §28.2, §28.3, §37.4 · Bricks Academy lesson 10 Known Issues.

 Claude Code (local) ──ssh/scp──▶ Nexus VM (34.55.179.122)
         │
         ├── python3 /tmp/script.py (with .env credentials)
         ├── curl /wp-json/... (WP REST)
         ├── curl /api/cloudflare/zones/{id}/purge_cache
         └── python3 nexus_html_logger.py (MH writes)

📤 Direction

Claude Code → VM (execute) · VM → Claude Code (stdout/stderr captured)

🔐 Auth

SSH key ~/.ssh/google_compute_engine (public half authorized on VM for user dovew)

📡 Protocol

SSH (execute + capture) · SCP (file transfer)

📍 Endpoint(s)

dovew@34.55.179.122 port 22

⚡ Trigger

Claude Code chooses to run a command · user sends a request requiring VM access

📦 Payload

Python scripts, shell commands, output

🎯 Purpose

Execute anything requiring server-side credentials or access to Nexus local state

⚠️ Failure mode

SSH key missing/rotated → connection refused · VM down → unreachable · network partition

🔄 Retry

No automated retry; Claude Code surfaces failure

📝 Observability

Shell exit codes · Claude Code conversation log

 Linux cron daemon → /usr/bin/python3 /opt/nexus/titan/{script}.py
        │
        ├── fleet_availability.py          every 15 min
        ├── GA4 full report                daily 8am
        ├── financial validator            daily after briefing
        ├── review intelligence             hourly
        ├── CPL monitor                    daily 3pm
        └── (22+ other automations)

📤 Direction

cron → Nexus pipelines (no return channel; pipelines log to stdout/stderr and local DB)

🔐 Auth

User dovew; .env loaded at process start

📡 Protocol

Unix cron

📍 Endpoint(s)

crontab -l under dovew

⚡ Trigger

Schedule defined per pipeline

📦 Payload

Each pipeline has its own inputs (DB queries, API calls) and outputs (JSON files in /opt/nexus/nexus/scripts/output/, SQLite/Postgres writes, MH entries, Slack messages)

🎯 Purpose

Automation — data freshness, monitoring, reporting

⚠️ Failure mode

Silent stderr (many pipelines redirect to /dev/null). Missing .env vars. Stale GCP auth.

🔄 Retry

Next schedule tick; no in-run retry

📝 Observability

/opt/nexus/nexus/scripts/output/*_cron.log files · MH entries

 Nexus script → POST https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/purge_cache
        Body: {"purge_everything": true}
        Auth: Bearer CLOUDFLARE_API_TOKEN

📤 Direction

Nexus → Cloudflare

🔐 Auth

API token (Bearer). Env vars: CLOUDFLARE_API_TOKEN + CLOUDFLARE_ZONE_ID.

📡 Protocol

REST (JSON POST)

📍 Endpoint(s)

https://api.cloudflare.com/client/v4/zones/{zone}/purge_cache

⚡ Trigger

After any page/snippet change that needs edge invalidation

📦 Payload

{"purge_everything": true} or {"files": ["https://..."]} for surgical purge

🎯 Purpose

Ensure edge cache reflects latest origin content

⚠️ Failure mode

Apr 23 discovery: scripts previously checked CF_API_TOKEN (wrong name) — env actually uses CLOUDFLARE_API_TOKEN. Purges silently returned no-op. Fixed.

🔄 Retry

Manual re-run if response success: false

📝 Observability

CF dashboard cache analytics · response body contains result.id for traceability

Source: Codebase Doc §34.1.

📤 Direction

Nexus → WordPress LSC plugin

🔐 Auth

WP Basic auth (claude-api)

📡 Protocol

REST (POST to custom BSP endpoint wrapping LSC)

📍 Endpoint(s)

/wp-json/bsp/v2/cache/purge (BSP custom route that calls LSC internally)

⚡ Trigger

Same as Cloudflare purge — after content change

📦 Payload

Empty POST

🎯 Purpose

Invalidate origin-side page cache before CF edge re-fetch

⚠️ Failure mode

LSC plugin disabled/malfunctioning → origin serves stale content. 200 response doesn't always mean purge succeeded — verify by checking page x-litespeed-cache header after.

📤 Direction

File on VM → web server → browser

🔐 Auth

Public (morpheus.callbrightside.com is publicly accessible)

📡 Protocol

HTTP(S)

📍 Endpoint(s)

morpheus.callbrightside.com/documents/*.html → serves from /opt/nexus/nexus/scripts/output/playbooks/*.html

⚡ Trigger

Any HTTP request for doc URL

📦 Payload

HTML files (Codebase Doc ~1.27MB · Master History ~2.6MB · this Reference doc ~TBD)

🎯 Purpose

Make institutional knowledge accessible to Robert + team without VM SSH

⚠️ Failure mode

Broken HTML → renders degraded · file not written → 404

📝 Observability

web server access log · Nexus file system

 Inbound call → 3CX routes to Daniel extension → Vapi answers
        │
        ├── AI conversation (Vapi-managed)
        ├── Transfer to human ext → 3CX routes to Ashton
        └── Booking intent → vapi_voice.py webhook → ST lead creation

📤 Direction

Customer phone → 3CX → Vapi · webhook back to Nexus for DB logging + ST lead

🔐 Auth

Vapi API key · 3CX SIP trunk · Nexus webhook signature validation

📡 Protocol

SIP (voice) · webhook (Vapi → Nexus JSON POST)

📍 Endpoint(s)

Daniel phone +19139639817 · Vapi assistant e2920d04 · Nexus webhook at /opt/nexus/titan/api/vapi_voice.py handler

⚡ Trigger

Customer dials Daniel line OR warm-transfer from human agent

📦 Payload

Vapi call events (start/end), transcripts, function calls (booking intent, etc.)

🎯 Purpose

AI-assisted call handling — reduces load on human agents for simple booking/FAQ

⚠️ Failure mode

Vapi down → calls go to 3CX voicemail fallback

📝 Observability

Vapi dashboard · titan.vapi_calls table via transcript_repo.py

Source: /opt/nexus/titan/api/vapi_voice.py · MH apr17-vapi-monitoring-deployed.

📤 Direction

Website chat button → tel:+19139639817 (phone) OR in-browser Vapi widget TBD

🔐 Auth

n/a (initiates call)

📡 Protocol

Browser handles tel: URI

📍 Endpoint(s)

Homepage + city pages: a.brxe-button href="#daniel-chat" currently · full Vapi browser widget integration deferred

⚡ Trigger

User clicks "Chat with Daniel our AI Agent" button

🎯 Purpose

Low-friction web → voice handoff for AI-assisted booking

⚠️ Failure mode

Current state: anchor href points at #daniel-chat — no JS handler yet. Needs Vapi widget wire-up. pending integration

 Customer submits contact form → WordPress POST handler → Snippet #97 → ST /leads API
        │
        └── (gap): NO positive handshake send-off back to customer
                  Tim (customer) raised this Apr 21: "did my form even go through?"

📤 Direction

Website form → ST lead creation (Apr 21 Tim incident confirmed this path works after Snippet #97 campaignId fix)

🔐 Auth

Server-side ST OAuth2 (credentials in .env, not browser-accessible)

📡 Protocol

PHP form POST → internal ST OAuth wrapper → ST /crm/v2/leads

📍 Endpoint(s)

Snippet #97 bsp-contact-form-st-lead

⚡ Trigger

Contact form submit

📦 Payload

customer object (name, phone, email, address), campaignId (GCLID-based routing), businessUnitId, jobTypeId

🎯 Purpose

Convert form visitors → ServiceTitan leads

⚠️ Failure mode

GAP: no customer-facing confirmation after submit. Tim Mahony wrote "I do not have any confirmation" Apr 21. This is the motivation for the Tim handoff plan Deliverable A (confirmation handshake via Telnyx SMS).

🔄 Retry

Browser submits once; no automatic retry

📝 Observability

Slack delivery · email delivery · ST leads list · NO customer-facing acknowledgement (the gap)

Source: Tim handoff plan · MH bsp-apr21-tim-mahony-incident-snippet97.

📤 Direction

Worker → ServiceTitan (read Dismissed bookings) · Worker → Telnyx (alert Ashton) · Worker → Slack (team visibility) · Worker → 3CX (emergency voice trigger)

🔐 Auth

ST OAuth2 · Telnyx API key · Slack webhook URL · 3CX admin key

📡 Protocol

REST polling (*/15 min) · Outbound webhooks

📍 Endpoint(s)

GET api.servicetitan.io/crm/v2/tenant/4316907157/bookings?status=Dismissed&source=Online Booking Widget&createdAfter={T-48h}

⚡ Trigger

Cron or systemd timer every 15 min during business hours 6am-10pm CT

📦 Payload

Booking objects (status, customer contact, booking_id, source, timestamps)

🎯 Purpose

Rescue dismissed-queue bookings before customer churns (prevents next Tim Mahony incident)

⚠️ Failure mode

Worker dies → bookings silently dismiss · ST token expiry · Telnyx quota · Slack webhook rotation

🔄 Retry

Next tick of cron · local titan.dismissed_queue_alerts tracks ack state to avoid double-pinging

📝 Observability

titan.dismissed_queue_alerts · daily MH entry bsp-{YYYYMMDD}-dismissed-queue-daily (planned) · Slack + SMS receipts

Source: Tim handoff plan Apr 23 update (Deliverable C).

📤 Direction

Vapi function call → Nexus webhook → ST lead/booking creation

🔐 Auth

Same ST OAuth2 as human channels

📡 Protocol

Vapi function calling → JSON POST to Nexus

📍 Endpoint(s)

Future: Nexus webhook for Vapi-initiated bookings · ST /crm/v2/leads

⚡ Trigger

Customer speaks booking intent during Daniel call

🎯 Purpose

Zero-human booking path: Daniel captures enough info, creates ST lead, optionally asks for ST-side booking confirmation

⚠️ Failure mode

Vapi mis-extracts call params · incomplete info → bad lead

📝 Observability

Vapi transcript · ST lead source tag

Status: medium-term (Q2-Q3 2026). Not shipped as of Apr 23 2026.

📤 Direction

Worker → Slack

🔐 Auth

Webhook URL (bearer by URL)

📡 Protocol

HTTPS POST

📍 Endpoint(s)

SLACK_WEBHOOK_URL TBD — Robert to create #bsp-alerts channel + webhook

⚡ Trigger

Dismissed-queue item aged > 60 min · 120-min re-alert · 240-min escalation

🎯 Purpose

Team-visible audit trail alongside SMS (which is private DM)