Visão geral

A Allbound IA tem duas camadas, com APIs e autenticações diferentes. Saber em
qual você está resolve quase toda dúvida de integração.

1. A plataforma

Contatos, conversas, funil, mensagens, chatbots, campanhas. É o que você chama de
servidor, com um token permanente.

API	Base	Cobre
Core	`api.hub.allbound.ia.br/core`	Contatos, etiquetas, campos, equipes, carteiras, usuários, webhooks
CRM	`api.hub.allbound.ia.br/crm`	Painéis e cards do funil
Chat	`api.hub.allbound.ia.br/chat`	Conversas, mensagens, envio, modelos, agendadas, sequências, chatbots

Autenticação: Authorization: Bearer pn_… — ver Autenticação.

2. Insights

A camada de análise que roda embutida na plataforma, como menu. Quem usa não
faz login: abre o menu e já está autenticado, porque a identificação vem da
própria plataforma.

Ela entrega três coisas:

Insights — perguntas em linguagem natural sobre os atendimentos, com
gráficos e relatórios.
Agentes de IA — configuração dos agentes que respondem automaticamente.
Playbooks — os critérios com que as conversas são avaliadas.

Autenticação: header x-ext-session, não Bearer — ver
Sessão do embed.

📘
Qual das duas você quer?
Se está escrevendo código que roda no seu servidor e mexe em contatos,
conversas ou funil, é a plataforma. Se está lidando com a página de análise
embutida, é o Insights. O token de uma não vale na outra.

O restante desta página descreve a camada de Insights.

Como funciona por baixo

plataforma (menu personalizado)
        │  iframe: /?cid=…&hu={{id_do_usuario}}&ha={{id_da_conta}}
        ▼
   Insights (frontend)
        │  POST /session   { cid, hu, ha }
        ▼
   Insights (proxy)  ──valida cid/ha no registry, hu na API da plataforma──▶ plataforma
        │  ◀── sessionToken (JWT, 1 h)
        │
        │  GET/POST /api/…   header x-ext-session
        ▼
   Insights (proxy)  ──injeta o Bearer do tenant──▶  API da Allbound IA

Três características que explicam quase todo o comportamento da API:

Nenhum segredo trafega pelo browser. A URL do iframe carrega só
identificadores públicos. As credenciais que falam com a Allbound IA e com a plataforma
ficam no servidor do Insights, indexadas pelo cid.

A sessão é do embed, não do usuário. Não há cadastro, senha ou recuperação de
acesso. Quem controla quem entra é a plataforma: se a pessoa vê o menu, ela
tem sessão.

O Insights é um proxy com allowlist. Ele repassa três famílias de rotas da API da
Allbound IA e nada mais. Qualquer outro caminho responde 404, mesmo com sessão
válida — a credencial do tenant não pode ser usada para alcançar campanhas,
contatos ou disparos.

Multi-tenant, um único deploy

Uma mesma instalação atende vários clientes. O cid da URL identifica o tenant e resolve,
no servidor, qual credencial da Allbound IA e qual token da plataforma usar.
Contas diferentes nunca se enxergam.

De onde vêm as conversas

O Insights analisa as conversas da plataforma, ingeridas por webhook quando
o atendimento é concluído. Ele não enxerga conversas de outras aplicações da
Allbound IA, e elas não enxergam as suas.

Por onde começar

Onboarding do tenant — colocar um cliente no ar.
Sessão do embed — como autenticar as chamadas.
API disponível — o que dá para chamar.
Webhooks — como as conversas chegam.