Documentación de API

Guía de Integración

Conecta tu sitio web, aplicaciones, flujos de trabajo y conversaciones con clientes a Bob a través de APIs, widgets, webhooks y automatización de front-office.

Inicio Rápido

Conecta Bob a tu sitio web o flujo de trabajo de front-office en unos pocos pasos guiados.

1

Crear o seleccionar un inquilino

Elige el inquilino que posee el sitio web, el widget y las credenciales de API para esta integración.

2

Generar credenciales

Crea una clave de widget con alcance de inquilino desde el Portal del Cliente → Configuración del Widget, o utiliza un JWT de cliente para la automatización del lado del servidor.

3

Instala el widget o llama al API

Utiliza el widget del sitio web para chat en el front-end o el API para flujos de trabajo del lado del servidor.

4

Prueba con navegador a prueba.

Verifica la integración desde el navegador en vivo, no solo una solicitud simulada.

Integración de widget (desde el Portal del Cliente) 
<!-- Tenant-scoped bundle — replace YOUR_TENANT_UUID after onboarding -->
<script src="https://office16852.com/widget/YOUR_TENANT_UUID/widget.js" async></script>
Listo cuando esté verificado: After embed, open your site in a real browser and confirm Bob loads. Use Estado del sistema si el chat no se conecta.

Configuración

Complete estos requisitos previos antes de llamar a APIs protegidos o publicar el widget en dominios de producción.

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

  • Tenant created
  • Business profile completed
  • Website or channel configured
  • API credentials generated
  • Allowed origins configured
  • Test conversation completed
EntornoPropósitoDónde configurar
ProducciónTráfico de clientes en vivoPortal del Cliente → Configuración del Widget
Etapa / vista previaVerificación previa al lanzamientoOrígenes permitidos + dominio de prueba
AutomatizaciónWebhooks del lado del servidor y APIsJWT del cliente desde el inicio de sesión del portal

Autenticación

Las solicitudes protegidas API deben incluir una credencial con alcance de inquilino. Mantenga las claves privadas del lado del servidor y nunca las exponga en el código del navegador.

Importante: Nunca expongas las claves de inquilino API o los JWT de clientes en el código del lado del cliente. Utiliza llamadas del lado del servidor para solicitudes protegidas de API.
1

Generar credenciales

requerido

Sign in to the Customer Portal and create widget keys in Widget Setup, or obtain a customer JWT via POST /api/customer/auth/login para la automatización.

2

Enviar encabezado de autorización

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

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

Manejar errores de autenticación

Devuelve errores estructurados a tu capa de integración y vuelve a intentar solo cuando sea apropiado.

EstadoSignificado
401Credencial faltante o inválida
403La credencial es válida pero carece de permiso.
429Límite de tasa excedido
POST /api/customer/auth/login

Inicio de sesión del Portal del Cliente. Devuelve JWT para llamadas de integración autenticadas.

POST /api/auth/login

Inicio de sesión del operador de Mission Control (solo para administración de la plataforma).

Chat y Conversaciones

Bob expone tres rutas de chat dependiendo del contexto del llamador: anónimo de mismo origen, widget de origen cruzado y Control de Misión autenticado.

Tres rutas: (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 (requiere chat.manage; no para la búsqueda pública anónima).
POST /api/chat

Chat anónimo público en tu propio dominio. Cuerpo: mensaje, session_id, business_id opcional.

POST /api/widget/chat

Chat de widget de origen cruzado. Encabezados: X-Widget-Key, Content-Type. El origen debe estar en la lista permitida.

POST /api/widget/chat/audio

Transcripción de voz a texto para entrada de voz de widget. Las mismas reglas de clave y origen que el chat.

POST /api/chat/session

Crea una sesión cuando estés conectado a Mission Control (RBAC + CSRF para cookies).

POST /api/chat/message

La interfaz de usuario de administrador autenticada envía (chat.manage). Devuelve 401 si se llama de forma anónima.

GET /api/chat/history/:session_id

Historial de conversación (autenticado).

Mismo origen público (anónimo) 
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();

Instalación del Widget

Instala el widget en tu sitio cuando quieras que Bob esté disponible directamente para los visitantes. Utiliza la configuración específica del inquilino desde el Portal del Cliente → Configuración del Widget.

After onboarding, your embed code is in the Customer Portal under Configuración del widget. The publishable widget key (pk_live_…) está configurado allí—no incrustado en HTML estático.

HTML 
<!-- Tenant-scoped bundle from Customer Portal → Widget Setup -->
<script src="https://office16852.com/widget/YOUR_TENANT_UUID/widget.js" async></script>
ArtículoPropósitoEjemplo
UUID de inquilino en la ruta del scriptIdentifica tu paquete de widgetsDesde la Configuración del Widget
Clave del widget publicableAutentica el chat de origen cruzadopk_live_… (configurado en el portal, no en HTML)
Orígenes permitidosDominios permitidos para llamar al chat del widgethttps://your-site.com
A prueba de navegadores: Verifica el widget en un navegador real en cada origen permitido antes del lanzamiento a producción.
GET /api/customer-portal/widget-code

Devuelve el código de incrustación listo para pegar. Requiere JWT del cliente (config.read).

Webhooks del Panel de Control

Utiliza webhooks salientes para recibir actualizaciones cuando las conversaciones, transferencias, leads o eventos de flujo de trabajo cambien en tu inquilino.

Webhooks de proveedores entrantes (Stripe, telephony carriers, etc.) are platform infrastructure—not covered here. This section documents su puntos de suscripción salientes solamente.
EventoDescripción
conversation.escalatedTransferencia humana solicitada
conversation.takeover.startedEl agente tomó control en vivo
conversation.takeover.releasedDevuelto a Bob
lead.createdNueva captura de intake
appointment.bookedConfirmación de programación
billing.payment_failedSeñal de riesgo de cuenta
billing.payment_recoveredPago restaurado
webhook.testVerificación de conectividad desde el portal
*Todos los eventos anteriores
1

Crear una suscripción

Utiliza un JWT de administrador del Portal del Cliente. Envía una solicitud POST a la URL, eventos y descripción a /api/webhooks/subscriptions.

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

Verificar firmas

Verifica las firmas de webhook del lado del servidor antes de confiar en la carga útil.

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

Listar suscripciones (los secretos nunca se devuelven).

POST /api/webhooks/subscriptions

Crear suscripción. Se muestra el secreto de firma una vez en la respuesta.

DELETE /api/webhooks/subscriptions/:id

Eliminar una suscripción.

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

Cola la entrega de webhook.test.

GET /api/webhooks/deliveries

Registro de entregas incluyendo filas de carta muerta.

Automatización de Personas

La automatización de personas controla cómo Bob representa tu negocio, cuándo escalar y cómo manejar los límites.

La mayoría de clientes configuran la voz y el tono de Bob en el Portal del cliente. API routes below require an authenticated token with persona.manage.

Voz empresarial

Tono, estilo de saludo y respuestas alineadas con la marca.

Comportamiento de escalada

Cuando Bob pasa a manos humanas o crea tareas.

Límites de tema

Temas aprobados y patrones de rechazo seguros.

Preferencias de flujo de trabajo

Enrutamiento de departamentos y ganchos de automatización.

GET /api/personas

Lista de personas para el inquilino autenticado.

GET /api/personas/:id

Obtener una persona por id.

POST /api/personas

Crea una persona con nombre, campos de tono, systemPrompt, etc.

PUT /api/personas/:id

Actualizar una persona existente.

Las configuraciones de persona deben ser probadas antes de realizar cambios en producción. Utiliza pruebas en el navegador y conversaciones revisadas para validar el comportamiento.

Planes y Precios APIs

Los endpoints del libro de precios publicados potencian las superficies de marketing y el proceso de pago. La gestión de facturación API no es pública.

FunciónStarterProPlan Enterprise
Precio de lista (USD/mes)$79$249$899
Créditos de IA incluidos / mes15,00075,000250,000
Puestos de equipoHasta 3Hasta 10Ilimitado
Integraciones estándar1310
SoporteCorreoPrioritarioDedicado
GET /api/pricing/marketing-cards

Tarjetas de plan para marketing y checkout (público, sin auth).

GET /api/pricing/snapshot

Instantánea pública segura del libro de precios (sin campos de coste de proveedor).

La gestión de planes y facturación APIs es privada y está disponible solo a través de integraciones aprobadas—no documentadas en esta guía pública.

Health & Status

Utiliza información de salud y estado para verificar la disponibilidad, monitorear dependencias ascendentes y solucionar problemas de integración.

GET /api/health

Sonda de salud ligera para monitores y balanceadores de carga.

GET /api/health/public

Carga útil de estado público consumida por la página de Estado del Sistema.

Ver el estado del sistema →

Ejemplos de Integración

Puntos de partida prácticos para patrones de integración comunes.

HTML

Widget de chat para el sitio web

Agrega Bob a un sitio de marketing o portal de clientes.

Ver ejemplo →
JavaScript

Conversación del lado del servidor API

Chat anónimo de mismo origen desde tu aplicación.

Ver ejemplo →
Node.js

Escuchador de Webhook

Verifica firmas y procesa lead.created.

Ver ejemplo →
Flujo de trabajo

flujo de entrega CRM

Reacciona a eventos de conversación escalados.

Ver ejemplo →
Automatización

Flujo de captura de leads

Suscríbete a lead.created para la recepción.

Ver ejemplo →
Soporte

Escalación de soporte

Monitorea las escalaciones y eventos de toma de control.

Ver ejemplo →
Obtención de widget de origen cruzado 
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 })
});

Descripción de la Arquitectura

Office 168/52 es una oficina frontal gobernada basada en navegador: Portal del Cliente para operadores, Mando de Misión para la administración de la plataforma y superficies de integración públicas para tu pila.

Sitio web / Aplicación
Widget o API Cliente
Office 168/52 Gateway
Contexto del Inquilino
Bob Tiempo de Ejecución del Agente
Conocimiento y Capacitación
Transferencia Humana / Tablero
Webhooks / Sistemas Externos

Customer Portal and Mission Control APIs are session-backed UI routes—not published here. For a concise platform diagram, see resumen de arquitectura y centro de pruebas.