Guida all'integrazione

1

Crea o seleziona un inquilino

Scegli il tenant che possiede il sito web, il widget e le credenziali API per questa integrazione.

2

Genera credenziali

Crea una chiave widget specifica per il tenant da Customer Portal → Widget Setup, oppure utilizza un JWT cliente per l'automazione lato server.

3

Installa il widget o chiama il API

Utilizza il widget del sito web per la chat front-end o il API per i flussi di lavoro lato server.

4

Test con browser proof

Verifica l'integrazione dal browser live, non solo una richiesta simulata.

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

Pronto quando verificato: After embed, open your site in a real browser and confirm Bob loads. Use Stato del sistema se la chat non riesce a connettersi.

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

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

Ambiente	Scopo	Dove configurare
Produzione	Traffico clienti in tempo reale	Portale Clienti → Configurazione Widget
Staging / anteprima	Verifica pre-lancio	Origini consentiti + dominio di test
Automazione	Webhook server-side e APIs	JWT cliente dal login del portale

Importante: Non esporre mai le chiavi API degli inquilini o i JWT dei clienti nel codice lato client. Utilizza chiamate lato server per le richieste protette API.

1

Genera credenziali

richiesto

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

2

Invia l'intestazione di autorizzazione

Server-to-server automation uses Authorization: Bearer <token> con corpi JSON.

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

3

Gestisci gli errori di autenticazione

Restituisci errori strutturati al tuo layer di integrazione e riprova solo quando appropriato.

Stato	Significato
401	Credenziali mancanti o non valide
403	Le credenziali sono valide ma mancano dei permessi.
429	Limite di frequenza superato

POST /api/customer/auth/login

Accesso al portale clienti. Restituisce JWT per chiamate di integrazione autenticate.

POST /api/auth/login

Accesso operatore Mission Control (solo amministrazione della piattaforma).

Tre percorsi: (1) Public same-origin → POST /api/chat. (2) Cross-origin embed → POST /api/widget/chat con X-Widget-Key. (3) Mission Control → POST /api/chat/message (richiede chat.manage; non per il recupero pubblico anonimo).

POST /api/chat

Chat anonimo pubblico sul tuo dominio. Corpo: messaggio, session_id, business_id opzionale.

POST /api/widget/chat

Chat widget cross-origin. Intestazioni: X-Widget-Key, Content-Type. L'origine deve essere autorizzata.

POST /api/widget/chat/audio

Trascrizione vocale per input voce del widget. Stesse regole di chiave e origine come per la chat.

POST /api/chat/session

Crea una sessione quando sei connesso a Mission Control (RBAC + CSRF per i cookie).

POST /api/chat/message

L'interfaccia utente dell'amministratore autenticato invia (chat.manage). Restituisce 401 se chiamata in modo anonimo.

GET /api/chat/history/:session_id

Cronologia conversazioni (autenticata).

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 Configurazione widget. The publishable widget key (pk_live_…) è configurato lì—non incorporato in HTML statico.

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

Articolo	Scopo	Esempio
UUID del locatario nel percorso dello script	Identifica il tuo pacchetto di widget	Dalla Configurazione del Widget
Chiave del widget pubblicabile	Autentica la chat cross-origin	pk_live_… (configurato nel portale, non in HTML)
Origini consentiti	Domini consentiti per chiamare il widget chat	https://your-site.com

Browser proof: Verifica il widget in un browser reale su ogni origine consentita prima del lancio in produzione.

GET /api/customer-portal/widget-code

Restituisce il markup di incorporamento pronto per essere incollato. Richiede il JWT del cliente (config.read).

Webhook provider in entrata (Stripe, telephony carriers, etc.) are platform infrastructure—not covered here. This section documents vostri solo endpoint di abbonamento outbound.

Evento	Descrizione
conversation.escalated	Richiesta di passaggio umano
conversation.takeover.started	L'agente ha preso il controllo live
conversation.takeover.released	Restituito a Bob
lead.created	Nuovo intake acquisito
appointment.booked	Conferma pianificazione
billing.payment_failed	Segnale rischio account
billing.payment_recovered	Pagamento ripristinato
webhook.test	Controllo della connettività dal portale
*	Tutti gli eventi sopra

1

Crea un abbonamento

Utilizza un JWT dell'amministratore del Portale Clienti. Invia una richiesta POST a /api/webhooks/subscriptions con l'URL, gli eventi e la descrizione.

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

2

Verifica le firme

Verifica le firme dei webhook lato server prima di fidarti del payload.

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

GET /api/webhooks/subscriptions

Elenca abbonamenti (i segreti non vengono mai restituiti).

POST /api/webhooks/subscriptions

Crea abbonamento. Il segreto di firma viene mostrato una sola volta nella risposta.

DELETE /api/webhooks/subscriptions/:id

Rimuovi un abbonamento.

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

Metti in coda la consegna del webhook.test.

GET /api/webhooks/deliveries

Log consegne incluse righe dead-letter.

La maggior parte dei clienti configura voce e tono di Bob nel Portale clienti. API routes below require an authenticated token with persona.manage.

Voce aziendale

Tono, stile di saluto e risposte allineate al marchio.

Comportamento di escalation

Quando Bob passa il lavoro agli esseri umani o crea compiti.

Confini tematici

Argomenti approvati e schemi di rifiuto sicuri.

Preferenze del flusso di lavoro

Routing dei dipartimenti e ganci di automazione.

GET /api/personas

Elenca le persone per l'inquilino autenticato.

GET /api/personas/:id

Ottieni una persona per id.

POST /api/personas

Crea una persona con nome, campi di tono, systemPrompt, ecc.

PUT /api/personas/:id

Aggiorna una persona esistente.

Le impostazioni del persona devono essere testate prima delle modifiche in produzione. Utilizza la prova del browser e le conversazioni esaminate per convalidare il comportamento.

Funzione	Starter	Pro	Plan Enterprise
Prezzo di listino (USD/mese)	$79	$249	$899
Crediti AI inclusi / mese	15,000	75,000	250,000
Posti team	Fino a 3	Fino a 10	Illimitato
Integrazioni standard	1	3	10
Supporto	Email	Prioritario	Dedicato

GET /api/pricing/marketing-cards

Schede piano per marketing e checkout (pubblico, senza auth).

GET /api/pricing/snapshot

Snapshot pubblico sicuro del listino (senza campi costo provider).

La gestione dei piani e della fatturazione API è riservata e disponibile solo tramite integrazioni approvate—non documentata in questa guida pubblica.

GET /api/health

Sonda salute leggera per monitor e load balancer.

GET /api/health/public

Payload di stato pubblico consumato dalla pagina di stato del sistema.

Visualizza lo stato del sistema →

HTML

Widget di chat per il sito web

Aggiungi Bob a un sito di marketing o a un portale clienti.

Visualizza esempio →

JavaScript

Conversazione lato server API

Chat anonimo con stessa origine dalla tua app.

Visualizza esempio →

Node.js

Ascoltatore Webhook

Verifica le firme e gestisci lead.created.

Visualizza esempio →

Flusso di lavoro

flusso di passaggio CRM

Reagisci agli eventi di conversazione escalati.

Visualizza esempio →

Automazione

Flusso di acquisizione lead

Iscriviti a lead.created per l'assunzione.

Visualizza esempio →

Supporto

Escalazione del supporto

Monitora le escalationi e gli eventi di takeover.

Visualizza esempio →

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 })
});

Sito web / App

Widget o API Client

Office 168/52 Gateway

Contesto del Locatario

Bob Runtime dell'Agente

Conoscenza e Formazione

Passaggio Umano / Dashboard

Webhook / Sistemi Esterni

Customer Portal and Mission Control APIs are session-backed UI routes—not published here. For a concise platform diagram, see panoramica architettura e centro prove.

Avvio Veloce

Crea o seleziona un inquilino

Genera credenziali

Installa il widget o chiama il API

Test con browser proof

Impostazione

Autenticazione

Genera credenziali

Invia l'intestazione di autorizzazione

Gestisci gli errori di autenticazione

Chat e Conversazioni

Installazione del Widget

Webhook del Dashboard

Crea un abbonamento

Verifica le firme

Automazione dei Persona

Voce aziendale

Comportamento di escalation

Confini tematici

Preferenze del flusso di lavoro

Piani e Prezzi APIs

Health & Status

Esempi di integrazione

Widget di chat per il sito web

Conversazione lato server API

Ascoltatore Webhook

flusso di passaggio CRM

Flusso di acquisizione lead

Escalazione del supporto

Panoramica dell'Architettura