Integration Guide

1

Create or select a tenant

Choose the tenant that owns the website, widget, and API credentials for this integration.

2

Generate credentials

Create a tenant-scoped widget key from Customer Portal → Widget Setup, or use a customer JWT for server-side automation.

3

Install the widget or call the API

Use the website widget for front-end chat or the API for server-side workflows.

4

Test with browser proof

Verify the integration from the live browser, not just a mock request.

<!-- Tenant-scoped bundle — replace YOUR_TENANT_UUID after onboarding -->
<script src="https://office16852.com/widget/YOUR_TENANT_UUID/widget.js" async></script>

Ready when verified: After embed, open your site in a real browser and confirm Bob loads. Use System Status if chat fails to connect.

External integrations connect systems outside the platform to Bob. Day-to-day front-office work happens in the Customer Portal.

Tenant created
Business profile completed
Website or channel configured
API credentials generated
Allowed origins configured
Test conversation completed

Environment	Purpose	Where to configure
Production	Live customer traffic	Customer Portal → Widget Setup
Staging / preview	Pre-launch verification	Allowed origins + test domain
Automation	Server-side webhooks & APIs	Customer JWT from portal login

Important: Never expose tenant API keys or customer JWTs in client-side code. Use server-side calls for protected API requests.

1

Generate credentials

required

Sign in to the Customer Portal and create widget keys in Widget Setup, or obtain a customer JWT via POST /api/customer/auth/login for automation.

2

Send Authorization header

Server-to-server automation uses Authorization: Bearer <token> with JSON bodies.

curl https://office16852.com/api/customer-portal/widget-code \
  -H "Authorization: Bearer YOUR_CUSTOMER_JWT" \
  -H "Content-Type: application/json"

3

Handle auth errors

Return structured errors to your integration layer and retry only when appropriate.

Status	Meaning
401	Missing or invalid credential
403	Credential is valid but lacks permission
429	Rate limit exceeded

POST /api/customer/auth/login

Customer Portal login. Returns JWT for authenticated integration calls.

POST /api/customers/auth/login

Multi-tenant customer login mounted at /api/customers. Same JWT contract as Customer Portal login.

POST /api/auth/login

Mission Control operator login (platform administration only).

Three paths: (1) Public same-origin → POST /api/chat. (2) Cross-origin embed → POST /api/widget/chat with X-Widget-Key. (3) Mission Control → POST /api/chat/message (requires chat.manage; not for anonymous public fetch).

POST /api/chat

Public anonymous chat on your own domain. Body: message, session_id, optional business_id.

POST /api/widget/chat

Cross-origin widget chat. Headers: X-Widget-Key, Content-Type. Origin must be allowlisted.

POST /api/widget/chat/audio

Speech-to-text for widget voice input. Same key and origin rules as chat.

POST /api/chat/session

Create session when logged into Mission Control (RBAC + CSRF for cookies).

POST /api/chat/message

Authenticated admin UI send (chat.manage). Returns 401 if called anonymously.

GET /api/chat/history/:session_id

Conversation history (authenticated).

const response = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    session_id: sessionId,
    message: userMessage,
    business_id: 'your-tenant-slug'
  })
});
const data = await response.json();

After onboarding, your embed code is in the Customer Portal under Widget Setup. The publishable widget key (pk_live_…) is configured there—not embedded in static HTML.

<!-- Tenant-scoped bundle from Customer Portal → Widget Setup -->
<script src="https://office16852.com/widget/YOUR_TENANT_UUID/widget.js" async></script>

Item	Purpose	Example
Tenant UUID in script path	Identifies your widget bundle	From Widget Setup
Publishable widget key	Authenticates cross-origin chat	pk_live_… (configured in portal, not in HTML)
Allowed origins	Domains permitted to call widget chat	https://your-site.com

Browser proof: Verify the widget in a real browser on each allowed origin before production launch.

GET /api/customer-portal/widget-code

Returns ready-to-paste embed markup. Requires customer JWT (config.read).

Inbound provider webhooks (Stripe, telephony carriers, etc.) are platform infrastructure—not covered here. This section documents your outbound subscription endpoints only.

Event	Description
conversation.escalated	Human handoff requested
conversation.takeover.started	Agent took live control
conversation.takeover.released	Returned to Bob
lead.created	New intake captured
appointment.booked	Scheduling confirmation
billing.payment_failed	Account risk signal
billing.payment_recovered	Payment restored
webhook.test	Connectivity check from portal
*	All events above

1

Create a subscription

Use a Customer Portal admin JWT. POST url, events, and description to /api/webhooks/subscriptions.

{
  "url": "https://your-app.com/webhooks/bob",
  "events": ["lead.created", "conversation.escalated"],
  "description": "CRM intake"
}

2

Verify signatures

Verify webhook signatures server-side before trusting the payload. Deliveries include X-AskBob-Signature — HMAC-SHA256(secret, "<timestamp>.<raw JSON body>").

{
  "event": "lead.created",
  "tenantId": "tenant_...",
  "conversationId": "conv_...",
  "createdAt": "2026-06-19T12:00:00Z",
  "data": {}
}

GET /api/webhooks/subscriptions

List subscriptions (secrets are never returned).

POST /api/webhooks/subscriptions

Create subscription. Signing secret shown once in response.

DELETE /api/webhooks/subscriptions/:id

Remove a subscription.

POST /api/webhooks/subscriptions/:id/test

Queue webhook.test delivery.

GET /api/webhooks/deliveries

Delivery log including dead-letter rows.

Most customers configure Bob's voice and tone in the Customer Portal. API routes below require an authenticated token with persona.manage.

Business voice

Tone, greeting style, and brand-aligned responses.

Escalation behavior

When Bob hands off to humans or creates tasks.

Topic boundaries

Approved topics and safe refusal patterns.

Workflow preferences

Department routing and automation hooks.

GET /api/personas

List personas for the authenticated tenant.

GET /api/personas/:id

Get one persona by id.

POST /api/personas

Create persona with name, tone fields, systemPrompt, etc.

PUT /api/personas/:id

Update an existing persona.

Persona settings should be tested before production changes. Use browser proof and reviewed conversations to validate behavior.

Feature	Starter	Pro	Enterprise
List price (USD/mo)	$79	$249	$899
AI credits granted each month	15,000	75,000	250,000
Unused credits	Add up; each grant expires 90 days after issue	Add up; each grant expires 90 days after issue	Add up; each grant expires 90 days after issue
Team seats	Up to 3	Up to 10	Unlimited
Standard integrations	1	3	10
Support	Email	Priority	Dedicated

GET /api/pricing/marketing-cards

Plan cards for marketing and checkout (public, no auth).

GET /api/pricing/snapshot

Public-safe full pricebook snapshot (no provider cost fields).

Plan and billing management APIs are private and available through approved integrations only—not documented on this public guide.

Each month you are granted your plan’s AI credits. Unused credits stay on your account and add up. Each grant expires 90 days after it is issued. Credits are usage units, not cash, and are not refunded.

GET /api/health

Lightweight health probe for monitors and load balancers.

GET /api/health/public

Public status payload consumed by the System Status page.

View System Status →

HTML

Website chat widget

Add Bob to a marketing site or customer portal.

View example →

JavaScript

Server-side conversation API

Same-origin anonymous chat from your app.

View example →

Node.js

Webhook listener

Verify signatures and process lead.created.

View example →

Workflow

CRM handoff flow

React to conversation.escalated events.

View example →

Automation

Lead capture workflow

Subscribe to lead.created for intake.

View example →

Support

Support escalation

Monitor escalations and takeover events.

View example →

const response = await fetch('https://office16852.com/api/widget/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Widget-Key': 'pk_live_...',
    'Origin': 'https://your-customer-site.com'
  },
  body: JSON.stringify({ session_id: sessionId, message: userMessage })
});

Website / App

Widget or API Client

Office 168/52 Gateway

Tenant Context

Bob Agent Runtime

Knowledge & Training

Human Handoff / Dashboard

Webhooks / External Systems

Customer Portal and Mission Control APIs are session-backed UI routes—not published here. For a concise platform diagram, see architecture overview and proof center.

Quick Start

Create or select a tenant

Generate credentials

Install the widget or call the API

Test with browser proof

Setup

Authentication

Generate credentials

Send Authorization header

Handle auth errors

Chat & Conversations

Widget Installation

Dashboard Webhooks

Create a subscription

Verify signatures

Persona Automation

Business voice

Escalation behavior

Topic boundaries

Workflow preferences

Plans & Pricing APIs

Health & Status

Integration Examples

Website chat widget

Server-side conversation API

Webhook listener

CRM handoff flow

Lead capture workflow

Support escalation

Architecture Overview