Every external service the CRM talks to is connected through a unified integration layer. The AI can call any integration by name. Credentials never touch the AI — they live in an encrypted vault and are resolved at the edge.
Architecture
The integration layer has five tiers:
AI Agent → MCP Layer → Workers → Vault → Vendors
| Tier | What It Does |
|---|
| AI Agent | Calls high-level MCP tools by name: send_sms, post_to_facebook, charge_card, geocode_address, upload_video, send_contract. The AI never sees raw credentials or vendor-specific APIs. |
| MCP Layer | Model Context Protocol abstraction. Each MCP tool maps to a specific vendor integration. The AI calls the tool; MCP routes the call to the correct Worker. |
| Workers | Cloudflare edge functions. Stateless, deployed per-integration. Each Worker resolves the contractor's encrypted credentials from the Vault and makes the vendor API call. No secrets in Worker code — credentials are injected at runtime. |
| Vault | Encrypted credential store. Holds all API keys, OAuth tokens, webhook secrets, and service accounts per contractor. Workers request credentials at call time. The AI agent never receives vault contents — only the Worker sees them. |
| Vendors | The actual third-party services: Twilio, Stripe, Meta, Google, Anthropic, etc. Workers call vendor APIs directly using the contractor's credentials. |
Security Model
The AI never sees raw API keys, OAuth tokens, or any credential material. When the AI calls crm/charge_card, the Worker retrieves the Stripe secret key from the vault, makes the Stripe API call, and returns only the result to the AI. The AI sees { success: true, charge_id: "ch_..." } — never the key itself.
Credential Vault
Every integration requires credentials stored in the vault. Four credential types are supported:
| Type | Used For | Examples |
|---|
| API Key | Services that authenticate with a static key | Twilio, SendGrid, Anthropic, Google Maps |
| OAuth Token | Services that use delegated access (account-level) | Google Calendar, Meta, YouTube, Google Business |
| Webhook Secret | Inbound events from vendors that must be verified | Stripe webhooks, Meta webhooks |
| Service Account | Long-lived service credentials with scoped permissions | Google Workspace, enterprise integrations |
Credentials are encrypted at rest and decrypted only by the Worker that needs them. Contractors manage credentials from Settings → Integrations → [Integration Name] → Credentials.
Integration Catalog
Voice & Communication
| Integration | Status | What It Powers |
|---|
| Twilio | 🟢 Connected | SMS send/receive, phone number provisioning, call routing, Digital Receptionist inbound call handling |
| ElevenLabs | 🟢 Connected | Voice synthesis for Digital Receptionist — natural-sounding AI voice for outbound calls and call responses |
| Deepgram / Whisper | 🟢 Connected | Speech-to-text transcription — call transcripts, field video audio extraction, voice mode in AI Assistant |
| SendGrid / Mailgun | 🟢 Connected | Transactional email delivery — estimates, invoices, follow-up sequences, email templates |
AI Models
| Integration | Status | What It Powers |
|---|
| Anthropic / Claude | 🟢 Connected | Core AI agent — all AI Assistant responses, email personalization, smart automation decisions, workflow routing |
| Google Gemini | 🟡 Planned / TBD | Multimodal AI — potential use for photo analysis, longer context windows, or model fallback |
| Higgsfield | 🟡 Planned / TBD | AI video generation — portfolio video creation from job photos and project data |
Payments
| Integration | Status | What It Powers |
|---|
| Stripe | 🟡 Planned / TBD | Online payment processing — Pay Now button in customer portal, invoice payments, recurring billing |
| Square | 🟡 Planned / TBD | In-person payment processing — card reader for on-site payment collection at job completion |
E-Signature
| Integration | Status | What It Powers |
|---|
| Dropbox Sign | 🟡 Planned / TBD | Contract e-signature — send_contract MCP tool, approval workflows, signed document storage |
| DocuSign | 🟡 Planned / TBD | Enterprise e-signature alternative — same use cases as Dropbox Sign, for contractors who already use DocuSign |
| Integration | Status | What It Powers |
|---|
| Meta (Facebook / Instagram) | 🟡 Planned / TBD | Post completed project photos to Facebook Page and Instagram profile automatically after job close |
| YouTube | 🟡 Planned / TBD | Upload portfolio/project videos to contractor's YouTube channel from the video pipeline |
| Google Business Profile | 🟡 Planned / TBD | Post project updates and review requests directly to Google Business listing |
| TikTok | ⚪ Not connected | Short-form video publishing — low priority; listed for future consideration |
| Contractor Website | 🟡 Planned / TBD | Sync completed projects, portfolio photos, and review content to the contractor's Tradesmen Website |
Advertising
| Integration | Status | What It Powers |
|---|
| Meta Ads | 🟡 Planned / TBD | Manage Facebook and Instagram ad campaigns from within the CRM — budget control, audience targeting, lead ad integration |
| Google Ads | 🟡 Planned / TBD | Search and display campaign management — keyword bidding, local service ads, conversion tracking tied to booked jobs |
Mapping & Location
| Integration | Status | What It Powers |
|---|
| Google Maps | 🟡 Planned / TBD | Address geocoding, distance calculations, service area boundaries, route optimization for dispatch |
| Mapbox | 🟡 Planned / TBD | Map rendering for the GPS tracking view, geofence boundary drawing, offline map tiles for mobile |
Incentives & Rewards
| Integration | Status | What It Powers |
|---|
| Marketing Boost | 🟡 Planned / TBD | Reward incentives for reviews and referrals — send vacation certificates or gift cards to customers who refer new business |
| Gift Card Vendor | ⚪ Not connected | Direct gift card fulfillment for referral rewards — vendor not yet selected |
Calendar & Scheduling
| Integration | Status | What It Powers |
|---|
| Google Calendar | 🟡 Planned / TBD | Two-way calendar sync — jobs booked in the CRM appear on the contractor's Google Calendar; events created in Google Calendar block CRM availability |
| Apple Calendar | ⚪ Not connected | CalDAV sync for iOS-primary contractors — not yet implemented |
How the AI Uses Integrations
The AI calls integrations through MCP tools. It doesn't know which vendor is behind each tool — it calls the tool by name, and the MCP layer routes to the right Worker and vendor.
| MCP Tool | What the AI Can Do With It |
|---|
crm/send_sms | Send a text message to any contact. Used in follow-up workflows, appointment reminders, and direct AI Assistant actions. Routed through Twilio. |
crm/send_email | Send a templated or free-form email. Used in workflows, estimate delivery, invoice reminders. Routed through SendGrid or Mailgun. |
crm/charge_card | Charge a stored payment method or initiate a payment request. Routed through Stripe or Square depending on contractor config. |
crm/post_to_social | Publish a post (text + image/video) to one or more connected social platforms. Routed to Meta, YouTube, or Google Business depending on target. |
crm/send_contract | Send a contract document for e-signature. Routed through Dropbox Sign or DocuSign. Returns signed status and document URL when complete. |
crm/geocode_address | Convert a street address to GPS coordinates. Used by dispatch, geofencing, and project association intelligence. Routed through Google Maps or Mapbox. |
Connecting an Integration
Every integration follows the same connection flow from Settings → Integrations → [Integration Name] → Connect.
| Auth Type | Steps | What Happens |
|---|
| API Key | 1. Copy your API key from the vendor dashboard. 2. Paste it into the API Key field. 3. Click Save & Test. | The system sends a test request to verify the key is valid and has the required permissions. Green check = connected. |
| OAuth | 1. Click Connect with [Vendor]. 2. Authorize in the vendor's login window. 3. Approve the requested permissions. | An OAuth token is generated and stored in the vault. The token refreshes automatically — no manual key rotation needed. |
| Webhook | 1. Copy the webhook URL shown in the CRM. 2. Paste it into the vendor's webhook configuration. 3. Set the signing secret if required. | Inbound events are verified using the signing secret before being processed. Invalid signatures are rejected. |
Integration Status & Health
| Status | Indicator | What It Means |
|---|
| Connected | 🟢 Green | Integration is active and last test call succeeded. |
| Warning | 🟡 Yellow | Integration is connected but a recent call returned a non-fatal error (e.g., rate limit, temporary vendor outage). |
| Error | 🔴 Red | Integration call failed. Credentials may be expired, revoked, or the vendor returned a hard error. Action required. |
| Not Connected | ⚪ Gray | No credentials stored. Integration is available but has not been configured. |
| Planned / TBD | 🟡 Yellow badge | Integration is on the roadmap but not yet available to configure. |
When an integration enters Error state, the CRM notifies the account owner via in-app alert and email. Workflows that depend on the failing integration are paused — they do not silently fail or drop data. Once credentials are updated and the integration passes a test call, paused workflow runs resume from the last successful step.
Open Questions
- Which SMS vendor is primary — Twilio, Vapi, or another? Does the contractor-facing config expose the vendor choice, or is it abstracted?
- Payment processor decision — Stripe vs Square vs both. Are both offered simultaneously, or does the contractor pick one on setup?
- E-signature vendor — Dropbox Sign vs DocuSign. Is one the default with the other as an enterprise option?
- Social media posting — should posts require contractor approval before publishing, or can the AI post directly to connected accounts?
- Google Calendar sync — should CRM be the source of truth, or should conflicts be surfaced for manual resolution?
- Webhook retry behavior — if a vendor sends a webhook and the CRM is temporarily unavailable, does the vendor retry? Does the CRM have an event replay queue?
- Rate limiting — how are per-contractor API usage limits tracked across concurrent workflow runs?
- Integration marketplace — will contractors be able to install third-party integrations beyond the built-in catalog? What's the security model for community integrations?