Integrations

On the Integrations page, each provider can be set to Platform (use our key, billed in tokens) or BYOK (your key, you pay the provider directly; that usage spends no tokens but carries a flat orchestration fee — $0.06/voice-min, $0.006/message). Connect a key and click Test to validate it before you rely on it. Admins set platform-wide keys under Platform Keys.

Beyond the AI providers, you can connect external accounts that your agent's tools use. Open Integrations, pick the service, paste the credential, and click Test:

Once connected, the matching built-in tool works automatically: create_booking writes a real event to your calendar (Google or CalDAV), and shopify_order looks up real orders by number, email, or phone. If no calendar is connected, create_booking still records the booking and tells the agent to connect one.

Data export & deletion

Under Settings → GDPR & Privacy you can export everything we hold for your account as a JSON bundle (business, agents, phone numbers, calls + transcripts) or file a deletion request. Requests are tracked with a status and an append-only audit trail.

Option A — Google Calendar (OAuth)

1. Integrations → Google Calendar → click Connect Google Account and approve access.
2. Leave the Calendar field as `primary` to use your main calendar.
3. To target a different calendar, open Google Calendar → Settings for my calendars → pick the calendar → Integrate calendar → copy the Calendar ID (your email, or a …@group.calendar.google.com address) and paste it into the Calendar field.
4. Click Test — it should say connected.

Option B — Apple / CalDAV (paste only, no OAuth)

Works with iCloud, Fastmail, Nextcloud, and any CalDAV server.

1. Create an app-specific password — for iCloud: appleid.apple.com → Sign-In and Security → App-Specific Passwords.
2. Integrations → Apple / CalDAV Calendar.
3. Paste the CalDAV URL (iCloud uses your calendar collection URL), your username (e.g. you@icloud.com), and the app-specific password.
4. Click Test, then add the create_booking tool to your agent.

Once either is connected, create_booking writes real events to that calendar automatically.

Most integrations need nothing but a pasted key. A few depend on platform-level configuration the account owner sets once (in Vercel env vars or a provider console). This section is the checklist for whoever operates the platform.

Google Calendar (OAuth) — already provisioned

Google Calendar uses OAuth, not a pasted key. The Google Cloud project (OAuth consent screen + Web client) is already set up by the owner. To verify or move it, confirm the following:

1. Two env vars exist in Vercel (Production): GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET. The Integrations page reads env.googleOauth from these — if either is missing the Connect button is hidden and status shows "not configured".
2. In Google Cloud Console → APIs & Services → Credentials, the OAuth client is type "Web application".
3. That client's Authorized redirect URIs must contain EXACTLY the callback the app builds: `${NEXT_PUBLIC_APP_URL}/api/integrations/google/callback` (e.g. https://your-app.vercel.app/api/integrations/google/callback). It must be an exact string match — no trailing slash, correct scheme/host. If NEXT_PUBLIC_APP_URL is unset the app falls back to the request origin, so set it to avoid drift.
4. The OAuth consent screen requests these scopes: calendar.events, calendar.readonly, openid, email. Add them to the consent screen's scope list (and to any test-user / verification config).
5. The Google Calendar API must be enabled for the project (APIs & Services → Library → Google Calendar API → Enable).

Microsoft Outlook — Sign in with Microsoft (Azure AD + Graph)

Outlook works like Google: a one-time Azure app registration by the owner, then each business clicks "Connect Microsoft Account". One-time owner steps:

• Azure Portal → Microsoft Entra ID → App registrations → New registration. Name it (e.g. "CustomWeb Calendar").
• Supported account types: "Accounts in any organizational directory and personal Microsoft accounts" (so both Outlook.com personal and work/school accounts can connect).
• Redirect URI (platform = Web): `${NEXT_PUBLIC_APP_URL}/api/integrations/microsoft/callback` (e.g. https://your-app.vercel.app/api/integrations/microsoft/callback) — exact match, no trailing slash.
• Copy the Application (client) ID. Then Certificates & secrets → New client secret → copy the secret VALUE (not the ID).
• API permissions → Microsoft Graph → Delegated: add offline_access, openid, email, User.Read, Calendars.ReadWrite.
• Add the two values to Vercel env: MS_OAUTH_CLIENT_ID and MS_OAUTH_CLIENT_SECRET. The Integrations page reads env.microsoftOauth from these — if missing, the Connect button is hidden and only the read-only ICS fallback shows.

Per-business pasted credentials (no platform setup)

These need nothing from the owner — each business pastes its own credential and clicks Test:

Webhooks let your agent call your own systems. There are two directions:

• Outbound (tools) — a webhook tool POSTs the model's arguments to your URL during a call/chat and feeds the JSON response back to the agent. Define the parameter schema so the LLM knows what to send. 10-second timeout with retry.
• Inbound (platform) — Twilio voice/SMS webhooks (signature-verified) drive calls, and Stripe billing webhooks (signing-secret verified) drive subscriptions and token grants. All handlers are idempotent so retries never double-charge.

POST https://your-api.com/book
Content-Type: application/json
{ "name": "Jane", "date": "2026-06-10T14:00:00Z", "service": "Consultation" }

// your endpoint replies, and the agent uses it:
{ "ok": true, "confirmationId": "BK-1042" }