Skip to main content
This page covers integration-side setup for each CRM driver. The platform-level overview (driver interface, encryption, audit posture) lives at Product → CRM; this page is the per-driver how-to.
Vorel writes into your CRM and treats your CRM as the system of record. Vorel-side persistence for conversation transcripts, leads, customer profiles, appointments, and cases is short-lived and ADR-locked: class-(c) rows purge on a 7–90 day post-CRM-write window. The authoritative copy lives in your CRM. See Product → CRM for the architectural commitment and Security → Data retention for the full per-class TTL windows.

​
Driver maturity

Vorel ships ten driver implementations plus a registered-but-unimplemented opentable slug. Every shipped driver implements the full CrmDriver interface (read, search, create, update, delete, introspection) and has unit coverage. HubSpot is the only driver with live production traffic (proven on the Skyline tenant). Treat the rest as built-and-tested but not yet exercised against a real account, and validate on the kickoff call before relying on a given provider.

​
Driver compatibility matrix

DriverAuthRefreshableReadWriteDelete
HubSpotOAuth 2.0 (auth-code)Yes (auto-refresh + re-encrypt)YesYesSoft (archive)
SalesforceOAuth 2.0 (auth-code)YesYesYesSoft (archive)
ZohoOAuth 2.0 (per-DC)YesYesYesSoft (archive)
AthenahealthOAuth 2.0 (client_credentials)Yes (lazy cache)YesYes (PHI-gated)Unsupported (clinical retention)
MindbodyForm (site id + API key)n/a (long-lived)YesYesUnsupported (manual at provider)
TekmetricForm (shop id + client id/secret)n/aYesYes (appointments)Unsupported (manual at provider)
OdooForm (URL + DB + user + key)n/aYesYesHard (unlink)
ToastPartner client-credentialsn/aYes (loyalty guest)Yes (loyalty guest only)Soft-redact (no hard delete)
Custom webhookBearer secret (HMAC)n/an/a (write bridge)YesPass-through
Generic RESTAPI key / bearer / basic / nonen/aYesYesConfigurable (hard or unsupported)
OpenTablepartnership-onlyn/an/an/an/a
A few driver-specific notes:
  • Athenahealth is PHI-gated. No production tenant may connect until a signed HIPAA BAA and compliance review exist. Write-back uses the least-PHI-invasive patientcase surface.
  • Toast wires the Toast loyalty guest object only (no notes, deals, or activities); writes outside guest are rejected, and erasure is a soft-redact rather than a hard delete.
  • Generic REST (rest_api) is a first-class configurable HTTP connector: you supply per-verb request templates, an auth type, and a deleteIsHard flag. It is the structured alternative to the fixed-envelope custom webhook.
  • OpenTable is reserved as a registered slug but not implemented. There’s no public OpenTable API that would support agent-driven reads/writes, so tenants requesting OpenTable use the custom_webhook driver against a partner-built adapter.

​
OAuth providers (HubSpot / Salesforce / Zoho)

HubSpot, Salesforce, and Zoho connect via the shared OAuth authorization-code flow during the kickoff call. (Athenahealth and Toast also use OAuth, but via the client_credentials grant: there’s no user-redirect step; the operator enters the client id/secret in the admin form like a form-based provider.)
1

Operator initiates the OAuth flow

From /admin/tenants/[id]/crm, your Vorel operator clicks Connect HubSpot (or Salesforce / Zoho). The provider’s OAuth page opens.
2

You sign in on the provider side

Authenticate on HubSpot.com / Salesforce.com / etc. with an account that has the required scopes (read + write on the relevant objects: leads, contacts, deals, appointments, depending on the provider).
3

Provider redirects with a code

Provider sends back to Vorel’s callback handler with an authorization code. Vorel exchanges it for an access token + refresh token + per-instance metadata.
4

Tokens land encrypted

Vorel envelope-encrypts the credential payload (access token + refresh token + instance URL + scopes) with AES-256-GCM and writes the row into tenant_credentials with status 'active'.
5

Live test connection

Your operator clicks Test connection. Vorel calls the provider’s lightest GET endpoint (/v1/account for HubSpot, /services/data for Salesforce, etc.) and reports success or the failure reason.

​
Refresh handling

Each OAuth driver knows how to handle 401 Unauthorized from the provider:
  1. Detect 401 during a tool call.
  2. Refresh via the refresh token.
  3. Retry the original call with the new access token (single retry).
  4. Re-encrypt + persist the refreshed credential payload back into tenant_credentials (rotated_at updated, audit-log entry written).
  5. Bubble up if the refresh itself fails (audit-log + auth_error to the agent).
This means tokens stay fresh across process restarts without operator intervention. The agent falls back gracefully on terminal failures (audit-log + “I’ll have someone follow up” copy).

​
Common OAuth failures

HubSpot refresh tokens expire after 6 months of inactivity. If a tenant’s CRM is dormant for that long and a tool call eventually fires, refresh fails with auth_error / refresh_failed. Operator re-runs the OAuth flow; new tokens land.
The user who connected may have been deactivated. Symptom is the same as above. Solution: operator re-runs OAuth with an active user.
If the OAuth grant didn’t include all the scopes Vorel needs (e.g. tenant accidentally chose a read-only OAuth profile), the agent’s first write call fails with auth_error / insufficient_scope. Operator re-runs OAuth with the right scope set.
Zoho has US / EU / IN / CN data centres. The OAuth flow captures which DC the customer is on; the driver pins all calls to that DC’s endpoints. If the customer migrates DCs (rare), re-run OAuth.

​
Form-based providers (Mindbody / Tekmetric / Odoo)

Providers without standard OAuth use form-based credential entry:
1

Collect credentials from the customer

Each provider’s credential set differs: - Mindbody: Site ID + API key (issued in the Mindbody developer portal). - Tekmetric: Shop ID + API key (issued from Tekmetric admin). - Odoo: Instance URL + database + username + API key (or password). The user must have access to res.partner + crm.lead models.
2

Operator enters them in the admin form

/admin/tenants/[id]/crm → driver-specific form. Credentials encrypt at rest the same way OAuth tokens do (AES-256-GCM, env-var master key).
3

Test connection live

Vorel calls the provider’s lightest endpoint to verify. If it fails, the operator troubleshoots with the customer on the call.
4

Stamp active

On successful test, tenant_credentials.status='active'. The agent now uses the driver on every relevant tool call.
Form-based credentials don’t auto-refresh (most are long-lived static API keys). Rotation is operator-driven: customer rotates the API key at the provider, sends Vorel the new value, your operator updates the form.

​
Custom webhook driver

For CRMs without a Vorel-shipped driver, the custom_webhook driver is the universal adapter:
  • Vorel POSTs lead / appointment / customer payloads to your team’s HTTPS endpoint.
  • Vorel signs each request with a per-tenant HMAC.
  • Your team translates the canonical Vorel shape to the underlying CRM’s native format.
This is the path for any of:
  • CRMs without a Vorel-native driver (Pipedrive, Insightly, Microsoft Dynamics, etc.)
  • Internal warehouses (push leads into your own database / data lake)
  • Multi-fan-out scenarios (write to two CRMs simultaneously: Vorel writes once, your webhook handler fans out)
Setup:
1

Build the webhook receiver

Standard HTTPS endpoint accepting POST + JSON. Verify HMAC against the per-tenant secret Vorel surfaces during connection.
2

Map the canonical shape to your CRM

Vorel calls the receiver with a uniform shape ({object, fields, idempotency_key}). Your handler translates fields into the target CRM’s native call.
3

Connect in admin

Operator enters the receiver URL + receives the HMAC secret. Test connection fires a no-op event your handler should ack with 200.

​
Per-tenant field mapping

Every driver supports per-tenant field mapping via tenant_crm_field_mappings. Your CRM’s “Mobile Phone” custom field is not Vorel’s customer.phone; the mapping table translates Vorel slot names (e.g. lead.budget_max) to your CRM’s field paths (e.g. Salesforce lead.UF_Budget_Max__c, HubSpot deal.budget_aed). Configured during the kickoff call. Default mappings ship per-vertical for common slots; tenants override per-field as needed. The mapping is write-direction today: Vorel writes named fields into your CRM. Reading arbitrary CRM custom fields back into Vorel slots is a Phase A2 follow-up.

​
Right-to-erasure

When a customer requests deletion under PDPL Art. 17 / GDPR Art. 17:
  1. Vorel-side scrub runs via /api/tenant/forget (operator-gated, dry-run-by-default).
  2. CRM-side scrub calls the driver’s deleteRecord for the customer’s CRM-side record.
  3. Drivers without a delete API (Mindbody, Tekmetric, Athenahealth) throw delete_unsupported. Toast soft-redacts (scrubs PII, marks inactive) rather than hard-deleting. In every case the operator gets a flag indicating manual action at the provider’s dashboard may be required.
  4. Audit log records the divergence so you can demonstrate compliance even when the CRM side requires manual action.

​
Connection rotation

Rotating credentials per your security policy:
  • OAuth providers: re-run the OAuth flow. Old refresh token continues to work until the new connection is verified, then operator marks the old row revoked.
  • Form-based providers: customer issues a new API key at the provider, sends it to your operator, operator updates the form. Old credential row is set to status='revoked'.
  • Custom webhook: operator regenerates the HMAC secret in the admin form. Customer’s receiver updates to the new secret in the same maintenance window.
Every credential rotation lands in audit_log with the actor, the previous credential id, and the new credential id.

​
What’s NOT supported today

  • Multiple drivers per tenant. One CRM per tenant. Use custom_webhook for multi-fan-out.
  • Reading CRM custom fields back into Vorel slots. Write-direction only today.
  • CRM-side webhook → Vorel. Listening for “CRM record updated” events is roadmap.
  • Self-service CRM connect by tenant team. Operator-driven only; protects against misconfiguration during a regulated-vertical onboarding.
  • Product → CRM: driver interface, credential encryption, audit posture
  • Quickstart: Step 5 of the kickoff flow
  • Verticals: vertical-specific CRM expectations (clinic uses Athenahealth, salon uses Mindbody, auto-service uses Tekmetric)
  • Security overview: encryption + audit posture