Guia de Integração

1

Crie ou selecione um inquilino

Escolha o locatário que possui o site, widget e credenciais API para esta integração.

2

Gerar credenciais

Crie uma chave de widget com escopo de inquilino a partir do Portal do Cliente → Configuração do Widget, ou use um JWT de cliente para automação do lado do servidor.

3

Instale o widget ou ligue para o API

Use o widget do site para chat no front-end ou o API para fluxos de trabalho no lado do servidor.

4

Teste com prova de navegador

Verifique a integração a partir do navegador ao vivo, não apenas uma solicitação simulada.

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

Pronto quando verificado: After embed, open your site in a real browser and confirm Bob loads. Use Status do sistema se o chat não conseguir se conectar.

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

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

Ambiente	Propósito	Onde configurar
Produção	Tráfego de clientes ao vivo	Portal do Cliente → Configuração do Widget
Estágio / pré-visualização	Verificação pré-lançamento	Origens permitidas + domínio de teste
Automação	Webhooks do lado do servidor e APIs	JWT do cliente a partir do login no portal

Importante: Nunca exponha as chaves API do inquilino ou os JWTs do cliente no código do lado do cliente. Use chamadas do lado do servidor para solicitações protegidas de API.

1

Gerar credenciais

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 automação.

2

Envie o cabeçalho de autorização

Server-to-server automation uses Authorization: Bearer <token> com corpos JSON.

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

3

Gerencie erros de autenticação

Retorne erros estruturados para sua camada de integração e tente novamente apenas quando apropriado.

Status	Significado
401	Credencial ausente ou inválida
403	As credenciais são válidas, mas não possuem permissão.
429	Limite de taxa excedido

POST /api/customer/auth/login

Login do Portal do Cliente. Retorna JWT para chamadas de integração autenticadas.

POST /api/auth/login

Login do operador do Mission Control (apenas administração da plataforma).

Três caminhos: (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 (requer chat.manage; não para busca pública anônima).

POST /api/chat

Chat anônimo público no seu próprio domínio. Corpo: mensagem, session_id, business_id opcional.

POST /api/widget/chat

Chat de widget de origem cruzada. Cabeçalhos: X-Widget-Key, Content-Type. A origem deve estar na lista de permissões.

POST /api/widget/chat/audio

Transcrição de voz para texto para entrada de voz do widget. As mesmas regras de chave e origem se aplicam ao chat.

POST /api/chat/session

Crie uma sessão ao fazer login no Mission Control (RBAC + CSRF para cookies).

POST /api/chat/message

A interface de administração autenticada envia (chat.manage). Retorna 401 se chamada anonimamente.

GET /api/chat/history/:session_id

Histórico de conversas (autenticado).

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 Configuração do widget. The publishable widget key (pk_live_…) está configurado lá—não incorporado em HTML estático.

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

Item	Propósito	Exemplo
UUID do inquilino no caminho do script	Identifica seu pacote de widgets	Da Configuração do Widget
Chave do widget publicável	Autentica chat entre origens diferentes	pk_live_… (configurado no portal, não no HTML)
Origens permitidas	Domínios permitidos para chamar o widget de chat	https://your-site.com

À prova de navegador: Verifique o widget em um navegador real em cada origem permitida antes do lançamento em produção.

GET /api/customer-portal/widget-code

Retorna a marcação de incorporação pronta para colar. Requer JWT do cliente (config.read).

Webhooks de provedores de entrada (Stripe, telephony carriers, etc.) are platform infrastructure—not covered here. This section documents seu apenas endpoints de assinatura outbound.

Evento	Descrição
conversation.escalated	Transferência humana solicitada
conversation.takeover.started	Agente assumiu controle ao vivo
conversation.takeover.released	Devolvido ao Bob
lead.created	Nova captura de intake
appointment.booked	Confirmação de agendamento
billing.payment_failed	Sinal de risco de conta
billing.payment_recovered	Pagamento restaurado
webhook.test	Verificação de conectividade a partir do portal
*	Todos os eventos acima

1

Criar uma assinatura

Use um JWT de administrador do Portal do Cliente. POST url, eventos e descrição para /api/webhooks/subscriptions.

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

2

Verifique assinaturas

Verifique as assinaturas do webhook no lado do servidor antes de confiar na carga útil.

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

GET /api/webhooks/subscriptions

Listar assinaturas (segredos nunca são retornados).

POST /api/webhooks/subscriptions

Criar assinatura. Segredo de assinatura mostrado uma vez na resposta.

DELETE /api/webhooks/subscriptions/:id

Remover uma assinatura.

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

Enfileirar entrega de webhook.test.

GET /api/webhooks/deliveries

Log de entregas incluindo dead-letter.

A maioria dos clientes configura voz e tom do Bob no Portal do cliente. API routes below require an authenticated token with persona.manage.

Voz empresarial

Tom, estilo de saudação e respostas alinhadas à marca.

Comportamento de escalonamento

Quando Bob passa para humanos ou cria tarefas.

Limites de tópicos

Tópicos aprovados e padrões seguros de recusa.

Preferências de fluxo de trabalho

Roteamento de departamentos e ganchos de automação.

GET /api/personas

Liste as personas para o inquilino autenticado.

GET /api/personas/:id

Obter uma persona por id.

POST /api/personas

Crie uma persona com nome, campos de tom, systemPrompt, etc.

PUT /api/personas/:id

Atualizar uma persona existente.

As configurações de persona devem ser testadas antes de alterações na produção. Use provas de navegador e conversas revisadas para validar o comportamento.

Recurso	Starter	Pro	Plan Enterprise
Preço de tabela (USD/mês)	$79	$249	$899
Créditos de IA incluídos / mês	15,000	75,000	250,000
Assentos de equipe	Até 3	Até 10	Ilimitado
Integrações padrão	1	3	10
Suporte	E-mail	Prioritário	Dedicado

GET /api/pricing/marketing-cards

Cartões de plano para marketing e checkout (público, sem auth).

GET /api/pricing/snapshot

Snapshot público seguro do pricebook (sem campos de custo de provedor).

O gerenciamento de planos e faturamento APIs é privado e disponível apenas através de integrações aprovadas—não documentado neste guia público.

GET /api/health

Sonda de saúde leve para monitores e balanceadores.

GET /api/health/public

Carga útil de status público consumida pela página de Status do Sistema.

Ver Status do Sistema →

HTML

Widget de chat do site

Adicione Bob a um site de marketing ou portal do cliente.

Veja o exemplo →

JavaScript

Conversa do lado do servidor API

Chat anônimo de mesma origem do seu aplicativo.

Veja o exemplo →

Node.js

Ouvinte de Webhook

Verifique assinaturas e processe lead.created.

Veja o exemplo →

Fluxo de Trabalho

fluxo de transferência CRM

Reaja a eventos de conversa escalonados.

Veja o exemplo →

Automação

Fluxo de captura de leads

Inscreva-se em lead.created para captação.

Veja o exemplo →

Suporte

Escalonamento de suporte

Monitore escalonamentos e eventos de tomada de controle.

Veja o exemplo →

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

Website / App

Widget ou API Cliente

Office 168/52 Gateway

Contexto do Inquilino

Bob Tempo de Execução do Agente

Conhecimento & Treinamento

Transfer Humano / Painel de Controle

Webhooks / Sistemas Externos

Customer Portal and Mission Control APIs are session-backed UI routes—not published here. For a concise platform diagram, see visão geral da arquitetura e centro de provas.

Início Rápido

Crie ou selecione um inquilino

Gerar credenciais

Instale o widget ou ligue para o API

Teste com prova de navegador

Configuração

Autenticação

Gerar credenciais

Envie o cabeçalho de autorização

Gerencie erros de autenticação

Chat e Conversas

Instalação do Widget

Webhooks do Painel

Criar uma assinatura

Verifique assinaturas

Automação de Persona

Voz empresarial

Comportamento de escalonamento

Limites de tópicos

Preferências de fluxo de trabalho

Planos e Preços APIs

Health & Status

Exemplos de Integração

Widget de chat do site

Conversa do lado do servidor API

Ouvinte de Webhook

fluxo de transferência CRM

Fluxo de captura de leads

Escalonamento de suporte

Visão Geral da Arquitetura