Onboarding do tenant

Colocar um cliente no ar são cinco passos: credencial na Allbound IA, dados do
plataforma, registro do tenant, webhook de ingestão e o menu personalizado.

Pré-requisito: a conta na Allbound IA precisa ter o recurso de análise
conversacional habilitado. Sem isso, a sessão é criada e as chamadas de Insights
respondem 403.

🚧

Todo este procedimento é de administrador

Ele envolve credenciais que dão acesso aos dados do cliente. Os valores dos
exemplos são placeholders — nunca reaproveite um segredo de outro tenant.

1. Credencial na Allbound IA

Como ADMIN ou MANAGER da conta, crie um cliente externo:

curl -X POST https://app.allbound.ia.br/api/v1/external-clients \
  -H "Authorization: Bearer <jwt-admin>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Insights — Cliente X"}'

{
  "clientId": "ext_9dK2mPq7XrT4vBnW",
  "clientSecret": "<secret em texto puro>"
}

O clientId (ext_…) é público — vai aparecer na URL do iframe. O
clientSecret aparece só nesta resposta e nunca mais; guarde em cofre.

2. Dados da plataforma

Você precisa de três valores:

O segredo do webhook é seu, não vem da plataforma. Ele é distinto do
clientSecret do passo 1 — não reaproveite um como o outro.

3. Registrar o tenant

Os quatro valores entram no registry de tenants do Insights, indexados pelo
clientId:

{
  "ext_9dK2mPq7XrT4vBnW": {
    "clientSecret":         "<do passo 1>",
    "partnerCrmAccountId":  "<id da conta na plataforma>",
    "partnerCrmApiToken":   "<token da API da plataforma>",
    "webhookSecret":        "<o que você gerou>"
  }
}

Em produção isso vive em gerenciador de segredos e o serviço precisa reiniciar
para reler. Os quatro campos são obrigatórios: faltando qualquer um, o tenant é
descartado na carga e todas as sessões dele falham.

4. Webhook de ingestão

Na plataforma: Ajustes → Integrações → Webhooks → nova assinatura com o evento
Atendimento concluído, apontando para:

https://ext.allbound.ia.br/webhooks/partner-crm?client_id=ext_9dK2mPq7XrT4vBnW&token=<segredo do webhook>

É isto que alimenta o Insights — sem essa assinatura, ele fica no ar e vazio, porque
nenhuma conversa chega para análise. Detalhes em Webhooks.

❗️

Essa URL inteira é uma credencial

Quem a tiver consegue injetar eventos na conta do cliente. Não coloque em
repositório, ticket ou captura de tela. Se vazar, gere outro segredo, atualize
o registry e refaça a assinatura.

5. Menu personalizado (o iframe)

Na plataforma: Admin → Ações e menus personalizados → Novo menu
personalizado.

• Exibição: página interna (iframe).
• URL:

https://ext.allbound.ia.br/?cid=ext_9dK2mPq7XrT4vBnW&hu={{id_do_usuario}}&ha={{id_da_conta}}

As duas chaves entre {{ }} são interpoladas pela plataforma no momento em que
o usuário abre o menu — não as substitua por valores fixos. O cid é o único
valor literal.

A plataforma valida, ao salvar, se o Insights permite ser embutido no domínio dele.
Se o menu não salvar, é aí que olhar.

Conferindo

Abra o menu com um usuário real da plataforma. O esperado é a página de
Insights carregar já autenticada.

Se aparecer erro de conta não encontrada, a causa está em um destes três, nesta
ordem de probabilidade: o cid não está no registry, o id da conta não bate com
o partnerCrmAccountId registrado, ou o usuário não existe naquela conta da
plataforma. A resposta da API é genérica de propósito — o motivo real fica no log
do Insights. Ver Erros e limites.