Documentation API

Guide d'intégration

Connectez votre site web, vos applications, vos flux de travail et vos conversations clients à Bob grâce à des API régulés, des widgets, des webhooks et de l'automatisation en front-office.

Démarrage rapide

Connectez Bob à votre site web ou à votre flux de travail en front-office en quelques étapes guidées.

1

Créer ou sélectionner un locataire

Choisissez le locataire qui possède le site web, le widget et les API identifiants pour cette intégration.

2

Générez des identifiants

Créez une clé de widget spécifique au locataire depuis le Portail Client → Configuration du Widget, ou utilisez un JWT client pour l'automatisation côté serveur.

3

Installez le widget ou appelez le API

Utilisez le widget du site web pour le chat frontal ou le API pour les workflows côté serveur.

4

Test avec preuve de navigateur

Vérifiez l'intégration depuis le navigateur en direct, pas seulement une demande fictive.

Intégration de widget (depuis le Portail Client) 
<!-- Tenant-scoped bundle — replace YOUR_TENANT_UUID after onboarding -->
<script src="https://office16852.com/widget/YOUR_TENANT_UUID/widget.js" async></script>
Prêt lorsque vérifié : After embed, open your site in a real browser and confirm Bob loads. Use État du système si le chat ne parvient pas à se connecter.

Configuration

Complétez ces prérequis avant d'appeler les API protégés ou de publier le widget sur des domaines de production.

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

  • Tenant created
  • Business profile completed
  • Website or channel configured
  • API credentials generated
  • Allowed origins configured
  • Test conversation completed
EnvironnementObjectifOù configurer
ProductionTrafic client en directPortail Client → Configuration du Widget
Mise en scène / aperçuVérification pré-lancementOrigines autorisées + domaine de test
AutomatisationWebhooks côté serveur & APIsJWT client depuis la connexion au portail

Authentification

Les demandes API protégées doivent inclure un identifiant d'utilisateur spécifique au locataire. Gardez les clés privées côté serveur et ne les exposez jamais dans le code du navigateur.

Important : Ne jamais exposer les clés API des locataires ou les JWT des clients dans le code côté client. Utilisez des appels côté serveur pour les demandes protégées API.
1

Générez des identifiants

requis

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

2

Envoyer l'en-tête d'autorisation

Server-to-server automation uses Authorization: Bearer <token> avec des corps JSON.

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

Gérer les erreurs d'authentification

Retournez des erreurs structurées à votre couche d'intégration et réessayez uniquement lorsque cela est approprié.

StatutSens
401Identifiant manquant ou invalide
403Le certificat est valide mais manque de permissions.
429Limite de taux dépassée
POST /api/customer/auth/login

Connexion au portail client. Renvoie un JWT pour les appels d'intégration authentifiés.

POST /api/auth/login

Connexion opérateur Mission Control (administration de la plateforme uniquement).

Chat et Conversations

Bob expose trois chemins de chat en fonction du contexte de l'appelant : anonyme de même origine, widget cross-origin et Mission Control authentifié.

Trois chemins : (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 (nécessite chat.manage; pas pour une récupération publique anonyme).
POST /api/chat

Chat public anonyme sur votre propre domaine. Corps : message, session_id, business_id optionnel.

POST /api/widget/chat

Widget de chat cross-origin. En-têtes : X-Widget-Key, Content-Type. L'origine doit être sur la liste blanche.

POST /api/widget/chat/audio

Transcription vocale pour l'entrée vocale des widgets. Même règles de clé et d'origine que pour le chat.

POST /api/chat/session

Créer une session lors de la connexion à Mission Control (RBAC + CSRF pour les cookies).

POST /api/chat/message

L'interface utilisateur admin authentifiée envoie (chat.manage). Renvoie 401 si appelée anonymement.

GET /api/chat/history/:session_id

Historique des conversations (authentifié).

Même origine public (anonyme) 
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();

Installation de Widget

Installez le widget sur votre site lorsque vous souhaitez que Bob soit disponible directement pour les visiteurs. Utilisez la configuration spécifique au locataire depuis le Portail Client → Configuration du Widget.

After onboarding, your embed code is in the Customer Portal under Configuration du widget. The publishable widget key (pk_live_…) est configuré là-bas—pas intégré dans du HTML statique.

HTML 
<!-- Tenant-scoped bundle from Customer Portal → Widget Setup -->
<script src="https://office16852.com/widget/YOUR_TENANT_UUID/widget.js" async></script>
ArticleObjectifExemple
UUID de locataire dans le chemin du scriptIdentifie votre ensemble de widgetsDepuis la configuration du Widget
Clé de widget publiableAuthentifie le chat inter-domainespk_live_… (configuré dans le portail, pas dans le HTML)
Origines autoriséesDomaines autorisés à appeler le chat widgethttps://your-site.com
Résistant aux navigateurs : Vérifiez le widget dans un vrai navigateur sur chaque origine autorisée avant le lancement en production.
GET /api/customer-portal/widget-code

Renvoie le code d'intégration prêt à être collé. Nécessite le JWT du client (config.read).

Webhooks de tableau de bord

Utilisez des webhooks sortants pour recevoir des mises à jour lorsque des conversations, des transferts, des prospects ou des événements de flux de travail changent dans votre locataire.

Webhooks fournisseurs entrants (Stripe, telephony carriers, etc.) are platform infrastructure—not covered here. This section documents vos points de terminaison d'abonnement sortants uniquement.
ÉvénementDescription
conversation.escalatedTransfert humain demandé
conversation.takeover.startedL'agent a pris le contrôle en direct
conversation.takeover.releasedRendu à Bob
lead.createdNouvelle capture d'intake
appointment.bookedConfirmation de planification
billing.payment_failedSignal de risque de compte
billing.payment_recoveredPaiement rétabli
webhook.testVérification de la connectivité depuis le portail
*Tous les événements ci-dessus
1

Créer un abonnement

Utilisez un JWT d'administrateur du portail client. POST l'URL, les événements et la description à /api/webhooks/subscriptions.

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

Vérifiez les signatures

Vérifiez les signatures des webhooks côté serveur avant de faire confiance à la charge utile.

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

Lister les abonnements (les secrets ne sont jamais renvoyés).

POST /api/webhooks/subscriptions

Créer un abonnement. Le secret de signature est affiché une seule fois dans la réponse.

DELETE /api/webhooks/subscriptions/:id

Supprimer un abonnement.

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

Mettre en file d'attente la livraison du webhook.test.

GET /api/webhooks/deliveries

Journal des livraisons incluant les dead-letter.

Automatisation des Personas

L'automatisation des personas contrôle comment Bob représente votre entreprise, quand escalader et comment gérer les limites.

La plupart des clients configurent la voix et le ton de Bob dans le Portail client. API routes below require an authenticated token with persona.manage.

Voix d'entreprise

Ton, style de salutation et réponses alignées sur la marque.

Comportement d'escalade

Lorsque Bob passe la main aux humains ou crée des tâches.

Limites des sujets

Sujets approuvés et modèles de refus sécurisés.

Préférences de flux de travail

Routage des départements et automatisation des déclencheurs.

GET /api/personas

Liste des personas pour le locataire authentifié.

GET /api/personas/:id

Obtenir une persona par id.

POST /api/personas

Créer un persona avec nom, tonalité, champs, systemPrompt, etc.

PUT /api/personas/:id

Mettre à jour une persona existante.

Les paramètres de persona doivent être testés avant les modifications de production. Utilisez la preuve du navigateur et les conversations examinées pour valider le comportement.

Plans et Tarifs APIs

Les points de terminaison du pricebook publié alimentent les surfaces marketing et le processus de paiement. Les APIs de gestion de la facturation ne sont pas publics.

FonctionnalitéStarterProPlan Enterprise
Prix catalogue (USD/mois)$79$249$899
Crédits IA inclus / mois15,00075,000250,000
Sièges d'équipeJusqu'à 3Jusqu'à 10Illimité
Intégrations standard1310
SupportE-mailPrioritaireDédié
GET /api/pricing/marketing-cards

Cartes d'offre pour marketing et checkout (public, sans auth).

GET /api/pricing/snapshot

Instantané publique sécurisée du tarif (sans champs de coût fournisseur).

La gestion des plans et de la facturation APIs est privée et disponible uniquement via des intégrations approuvées - non documentée dans ce guide public.

Health & Status

Utilisez les informations de santé et de statut pour vérifier la disponibilité, surveiller les dépendances en amont et résoudre les problèmes d'intégration.

GET /api/health

Sonde de santé légère pour moniteurs et load balancers.

GET /api/health/public

Charge utile de statut public consommée par la page de statut du système.

Voir l'état du système →

Exemples d'intégration

Points de départ pratiques pour des modèles d'intégration courants.

HTML

Widget de chat sur le site web

Ajoutez Bob à un site marketing ou à un portail client.

Voir l'exemple →
JavaScript

Conversation côté serveur API

Chat anonyme de même origine depuis votre application.

Voir l'exemple →
Node.js

Écouteur de webhook

Vérifiez les signatures et traitez lead.created.

Voir l'exemple →
Flux de travail

flux de transfert CRM

Réagissez aux événements d'escalade de conversation.

Voir l'exemple →
Automatisation

Flux de capture de leads

Abonnez-vous à lead.created pour l'intégration.

Voir l'exemple →
Support

Escalade de support

Surveillez les escalades et les événements de prise de contrôle.

Voir l'exemple →
Récupération de widget cross-origin 
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 })
});

Aperçu de l'architecture

Office 168/52 est un front office gouverné basé sur un navigateur : Portail Client pour les opérateurs, Mission Control pour l'administration de la plateforme, et surfaces d'intégration publiques pour votre stack.

Site Web / Application
Widget ou API Client
Office 168/52 Passerelle
Contexte du locataire
Bob Agent Runtime
Connaissance & Formation
Transfert Humain / Tableau de Bord
Webhooks / Systèmes externes

Customer Portal and Mission Control APIs are session-backed UI routes—not published here. For a concise platform diagram, see aperçu de l'architecture et centre de preuves.