API-Dokumentation

Integrationsleitfaden

Verbinden Sie Ihre Website, Apps, Workflows und Kundenkonversationen mit Bob durch gesteuerte APIs, Widgets, Webhooks und Front-Office-Automatisierung.

Schnellstart

Verbinden Sie Bob in wenigen einfachen Schritten mit Ihrer Website oder Ihrem Front-Office-Workflow.

1

Erstellen oder wählen Sie einen Mandanten aus

Wählen Sie den Mandanten aus, der die Website, das Widget und die API-Anmeldeinformationen für diese Integration besitzt.

2

Zugangsdaten generieren

Erstellen Sie einen tenant-spezifischen Widget-Schlüssel im Customer Portal → Widget Setup oder verwenden Sie ein Kunden-JWT für serverseitige Automatisierung.

3

Installieren Sie das Widget oder rufen Sie die API an.

Verwenden Sie das Website-Widget für Front-End-Chat oder die API für serverseitige Workflows.

4

Test mit browserproof

Überprüfen Sie die Integration im Live-Browser, nicht nur mit einer Mock-Anfrage.

Widget-Embed (aus dem Kundenportal) 
<!-- Tenant-scoped bundle — replace YOUR_TENANT_UUID after onboarding -->
<script src="https://office16852.com/widget/YOUR_TENANT_UUID/widget.js" async></script>
Bereit, wenn verifiziert: After embed, open your site in a real browser and confirm Bob loads. Use Systemstatus wenn der Chat nicht verbunden werden kann.

Einrichtung

Erfüllen Sie diese Voraussetzungen, bevor Sie geschützte APIs anrufen oder das Widget auf Produktionsdomänen veröffentlichen.

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

  • Tenant created
  • Business profile completed
  • Website or channel configured
  • API credentials generated
  • Allowed origins configured
  • Test conversation completed
UmweltZweckWo man konfigurieren kann
ProduktionEchtzeit-KundenverkehrKundenportal → Widget-Einrichtung
Bühne / VorschauVorab-ÜberprüfungErlaubte Ursprünge + Testdomain
AutomatisierungServer-seitige Webhooks & APIsKunden-JWT vom Portal-Login

Authentifizierung

Geschützte API-Anfragen müssen ein mandantenbezogenes Credential enthalten. Halten Sie private Schlüssel serverseitig und geben Sie sie niemals im Browser-Code preis.

Wichtig: Geben Sie niemals API-Schlüssel oder Kunden-JWTs im Client-Code preis. Verwenden Sie serverseitige Aufrufe für geschützte API-Anfragen.
1

Zugangsdaten generieren

erforderlich

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

2

Senden Sie den Autorisierungsheader

Server-to-server automation uses Authorization: Bearer <token> mit JSON-Körpern.

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

Authentifizierungsfehler behandeln

Geben Sie strukturierte Fehler an Ihre Integrationsschicht zurück und versuchen Sie es nur dann erneut, wenn es angemessen ist.

StatusBedeutung
401Fehlende oder ungültige Anmeldeinformationen
403Die Anmeldeinformationen sind gültig, aber es fehlt die Berechtigung.
429Rate-Limit überschritten
POST /api/customer/auth/login

Kundenportal-Login. Gibt JWT für authentifizierte Integrationsaufrufe zurück.

POST /api/auth/login

Mission Control Betreiberanmeldung (nur Plattformadministration).

Chat & Gespräche

Bob bietet drei Chat-Pfade je nach Kontext des Anrufers: anonym mit derselben Herkunft, Cross-Origin-Widget und authentifiziertes Mission Control.

Drei Pfade: (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 (erfordert chat.manage; nicht für anonyme öffentliche Abrufe).
POST /api/chat

Öffentlicher anonymer Chat auf Ihrer eigenen Domain. Body: Nachricht, Sitzungs-ID, optional Geschäfts-ID.

POST /api/widget/chat

Cross-Origin-Widget-Chat. Header: X-Widget-Key, Content-Type. Der Ursprung muss auf der erlaubten Liste stehen.

POST /api/widget/chat/audio

Spracherkennung für Widget-Sprachinput. Dieselben Schlüssel- und Ursprungsregeln wie im Chat.

POST /api/chat/session

Erstellen Sie eine Sitzung, wenn Sie in Mission Control angemeldet sind (RBAC + CSRF für Cookies).

POST /api/chat/message

Authentifizierte Admin-Benutzeroberfläche senden (chat.manage). Gibt 401 zurück, wenn anonym aufgerufen.

GET /api/chat/history/:session_id

Konversationsverlauf (authentifiziert).

Öffentlich Same-Origin (anonym) 
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

Installieren Sie das Widget auf Ihrer Website, wenn Sie Bob direkt für Besucher verfügbar machen möchten. Verwenden Sie die tenant-spezifische Konfiguration im Customer Portal → Widget Setup.

After onboarding, your embed code is in the Customer Portal under Widget-Einrichtung. The publishable widget key (pk_live_…) ist dort konfiguriert—nicht in statischem HTML eingebettet.

HTML 
<!-- Tenant-scoped bundle from Customer Portal → Widget Setup -->
<script src="https://office16852.com/widget/YOUR_TENANT_UUID/widget.js" async></script>
ArtikelZweckBeispiel
Mieter-UUID im SkriptpfadIdentifiziert Ihr Widget-BundleVon der Widget-Einrichtung
Veröffentlichbarer Widget-SchlüsselAuthentifiziert plattformübergreifenden Chatpk_live_… (im Portal konfiguriert, nicht in HTML)
Erlaubte UrsprüngeDomains, die berechtigt sind, das Widget-Chat zu nutzenhttps://your-site.com
Browser-sicher: Überprüfen Sie das Widget in einem echten Browser auf jeder erlaubten Herkunft vor dem Produktionsstart.
GET /api/customer-portal/widget-code

Gibt bereit zum Einfügen markierte Einbettung zurück. Erfordert Kunden-JWT (config.read).

Dashboard Webhooks

Verwenden Sie ausgehende Webhooks, um Updates zu erhalten, wenn sich Gespräche, Übergaben, Leads oder Workflow-Ereignisse in Ihrem Mandanten ändern.

Eingehende Provider-Webhooks (Stripe, telephony carriers, etc.) are platform infrastructure—not covered here. This section documents Ihre nur ausgehende Abonnement-Endpunkte.
EreignisBeschreibung
conversation.escalatedMenschliche Übergabe angefordert
conversation.takeover.startedAgent übernahm Live-Kontrolle
conversation.takeover.releasedAn Bob zurückgegeben
lead.createdNeue Intake-Erfassung
appointment.bookedTerminbestätigung
billing.payment_failedKontorisikosignal
billing.payment_recoveredZahlung wiederhergestellt
webhook.testVerbindungsprüfung vom Portal
*Alle obigen Ereignisse
1

Ein Abonnement erstellen

Verwenden Sie ein Customer Portal Admin JWT. POST-URL, Ereignisse und Beschreibung an /api/webhooks/subscriptions.

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

Signaturen überprüfen

Überprüfen Sie die Webhook-Signaturen serverseitig, bevor Sie das Payload vertrauen.

Lieferpayload (veranschaulichend) 
{
  "event": "lead.created",
  "tenantId": "tenant_...",
  "conversationId": "conv_...",
  "createdAt": "2026-06-19T12:00:00Z",
  "data": {}
}
GET /api/webhooks/subscriptions

Abonnements auflisten (Geheimnisse werden nie zurückgegeben).

POST /api/webhooks/subscriptions

Abonnement erstellen. Der Anmeldeschlüssel wird einmal in der Antwort angezeigt.

DELETE /api/webhooks/subscriptions/:id

Abonnement entfernen.

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

Webhook.test-Zustellung in die Warteschlange stellen.

GET /api/webhooks/deliveries

Zustellungslog inkl. Dead-Letter-Zeilen.

Persona Automation

Die Persona-Automatisierung steuert, wie Bob Ihr Unternehmen repräsentiert, wann eskaliert werden soll und wie mit Grenzen umgegangen wird.

Die meisten Kunden konfigurieren Bobs Stimme und Ton im Kundenportal. API routes below require an authenticated token with persona.manage.

Geschäftliche Stimme

Ton, Begrüßungsstil und markenkonforme Antworten.

Eskalationsverhalten

Wenn Bob an Menschen übergibt oder Aufgaben erstellt.

Themengrenzen

Genehmigte Themen und sichere Ablehnungsmuster.

Workflow-Einstellungen

Abteilungsrouting und Automatisierungs-Hooks.

GET /api/personas

Liste der Personas für den authentifizierten Mandanten.

GET /api/personas/:id

Eine Persona per ID abrufen.

POST /api/personas

Erstellen Sie eine Persona mit Namen, Tonfeldern, Systemaufforderung usw.

PUT /api/personas/:id

Bestehende Persona aktualisieren.

Die Persona-Einstellungen sollten vor Produktionsänderungen getestet werden. Verwenden Sie browserbasierte Nachweise und überprüfte Gespräche, um das Verhalten zu validieren.

Pläne & Preise APIs

Veröffentlichte Preisbuch-Endpunkte unterstützen Marketing-Oberflächen und den Checkout. Die Abrechnungsmanagement APIs sind nicht öffentlich.

FunktionStarterProPlan Enterprise
Listenpreis (USD/Monat)$79$249$899
Enthaltene KI-Credits / Monat15,00075,000250,000
Team-SitzeBis zu 3Bis zu 10Unbegrenzt
Standard-Integrationen1310
SupportE-MailPrioritätDediziert
GET /api/pricing/marketing-cards

Plankarten für Marketing und Checkout (öffentlich, ohne Auth).

GET /api/pricing/snapshot

Öffentlich sicherer Preisbuch-Snapshot (ohne Provider-Kostenfelder).

Plan- und Abrechnungsmanagement APIs sind privat und nur über genehmigte Integrationen verfügbar – nicht in diesem öffentlichen Leitfaden dokumentiert.

Health & Status

Verwenden Sie Gesundheits- und Statusinformationen, um die Verfügbarkeit zu überprüfen, upstream-Abhängigkeiten zu überwachen und Integrationsprobleme zu beheben.

GET /api/health

Leichtgewichtiger Health-Probe für Monitore und Load Balancer.

GET /api/health/public

Öffentliche Statusdaten, die von der Systemstatusseite verarbeitet werden.

Systemstatus anzeigen →

Integrationsbeispiele

Praktische Ausgangspunkte für gängige Integrationsmuster.

HTML

Website-Chat-Widget

Fügen Sie Bob zu einer Marketing-Website oder einem Kundenportal hinzu.

Beispiel ansehen →
JavaScript

Server-seitige Konversation API

Anonymer Chat mit derselben Herkunft aus Ihrer App.

Beispiel ansehen →
Node.js

Webhook-Listener

Überprüfen Sie Unterschriften und verarbeiten Sie lead.created.

Beispiel ansehen →
Automatisierung

Lead-Erfassungs-Workflow

Abonnieren Sie lead.created für die Aufnahme.

Beispiel ansehen →
Support

Support-Eskalation

Überwachen Sie Eskalationen und Übernahmeereignisse.

Beispiel ansehen →
Cross-Origin-Widget-Abruf 
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 })
});

Architekturübersicht

Office 168/52 ist ein browserbasiertes, verwaltetes Front Office: Kundenportal für Betreiber, Mission Control für die Plattformverwaltung und öffentliche Integrationsoberflächen für Ihren Stack.

Website / App
Widget oder API Client
Office 168/52 Gateway
Mieter-Kontext
Bob Agent Runtime
Wissen & Schulung
Menschliche Übergabe / Dashboard
Webhooks / Externe Systeme

Customer Portal and Mission Control APIs are session-backed UI routes—not published here. For a concise platform diagram, see Architekturüberblick und Proof Center.