API Documentation

Integration Guide

Set up Bob, connect your website, and integrate customer conversations with governed front-office APIs and tools.

Quick Start

Get Bob connected to your website or front-office workflow in a few guided steps.

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.

Widget embed (from Customer Portal) 
<!-- Tenant-scoped bundle — replace YOUR_TENANT_UUID after onboarding -->
<script src="https://www.askbob.cool/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.

Setup

Complete these prerequisites before calling protected APIs or publishing the widget on production domains.

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
EnvironmentPurposeWhere to configure
ProductionLive customer trafficCustomer Portal → Widget Setup
Staging / previewPre-launch verificationAllowed origins + test domain
AutomationServer-side webhooks & APIsCustomer JWT from portal login

Authentication

Protected API requests must include a tenant-scoped credential. Keep private keys server-side and never expose them in browser code.

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.

Example request 
curl https://www.askbob.cool/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.

StatusMeaning
401Missing or invalid credential
403Credential is valid but lacks permission
429Rate limit exceeded
POST /api/customer/auth/login

Customer Portal login. Returns JWT for authenticated integration calls.

POST /api/auth/login

Mission Control operator login (platform administration only).

Chat & Conversations

Bob exposes three chat paths depending on caller context: same-origin anonymous, cross-origin widget, and authenticated Mission Control.

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).

Public same-origin (anonymous) 
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();

Widget Installation

Install the widget on your site when you want Bob available directly to visitors. Use tenant-specific configuration from Customer Portal → Widget Setup.

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.

HTML 
<!-- Tenant-scoped bundle from Customer Portal → Widget Setup -->
<script src="https://www.askbob.cool/widget/YOUR_TENANT_UUID/widget.js" async></script>
ItemPurposeExample
Tenant UUID in script pathIdentifies your widget bundleFrom Widget Setup
Publishable widget keyAuthenticates cross-origin chatpk_live_… (configured in portal, not in HTML)
Allowed originsDomains permitted to call widget chathttps://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).

Dashboard Webhooks

Use outbound webhooks to receive updates when conversations, handoffs, leads, or workflow events change in your tenant.

Inbound provider webhooks (Stripe, telephony carriers, etc.) are platform infrastructure—not covered here. This section documents your outbound subscription endpoints only.
EventDescription
conversation.escalatedHuman handoff requested
conversation.takeover.startedAgent took live control
conversation.takeover.releasedReturned to Bob
lead.createdNew intake captured
appointment.bookedScheduling confirmation
billing.payment_failedAccount risk signal
billing.payment_recoveredPayment restored
webhook.testConnectivity 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.

JSON body 
{
  "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.

Delivery payload (illustrative) 
{
  "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.

Persona Automation

Persona automation controls how Bob represents your business, when to escalate, and how to handle boundaries.

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.

Plans & Pricing APIs

Published pricebook endpoints power marketing surfaces and checkout. Billing management APIs are not public.

FeatureStarterProEnterprise
List price (USD/mo)$79$249$899
Included AI credits / mo15,00075,000250,000
Team seatsUp to 3Up to 10Unlimited
Standard integrations1310
SupportEmailPriorityDedicated
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.

Health & Status

Use health and status information to verify availability, monitor upstream dependencies, and troubleshoot integration issues.

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 →

Integration Examples

Practical starting points for common integration patterns.

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 →
Cross-origin widget fetch 
const response = await fetch('https://www.askbob.cool/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 })
});

Architecture Overview

Ask Bob is a browser-based governed front office: Customer Portal for operators, Mission Control for platform administration, and public integration surfaces for your stack.

Website / App
Widget or API Client
Ask Bob 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.