API disponível

Com uma sessão válida, o Insights repassa três famílias de
rotas da API da Allbound IA — e nada mais.

Prefixo	O que é
`/api/v1/analytics/**`	Insights: perguntas em linguagem natural, análises de atendimento, sessões do chat, relatórios
`/api/ai-agents/**`	Configuração dos agentes de IA
`/api/v1/playbooks/**`	Critérios de avaliação das conversas

Tudo com o header x-ext-session. A forma de cada endpoint é a da API da
Allbound IA — o Insights não altera corpo nem parâmetros, só troca a credencial.

curl -X POST https://ext.allbound.ia.br/api/v1/analytics/ask \
  -H "x-ext-session: <sessionToken>" \
  -H "Content-Type: application/json" \
  -d '{"question":"Quais foram os principais motivos de contato na última semana?"}'

Qualquer outra rota responde 404

{ "error": "Rota não disponível na aplicação externa" }

Mesmo com sessão válida. Não é rota faltando: é allowlist. O Insights carrega a
credencial do tenant, então liberar /api/campaigns ou /api/contacts aqui
significaria que qualquer um com uma sessão do embed poderia disparar campanha
ou exportar a base de contatos do cliente. O 404 é a superfície de ataque que
não existe.

Se você precisa dessas rotas, o caminho é a API da Allbound IA direto, com
credencial própria — não o Insights.

Consumo de mensagens

GET /api/usage

O único endpoint próprio do Insights sob /api. Devolve o consumo do período
corrente do tenant:

curl https://ext.allbound.ia.br/api/usage \
  -H "x-ext-session: <sessionToken>"

{
  "messageLimit": 10000,
  "usageRenewalDay": 15,
  "periodStart": "2026-08-15T00:00:00.000Z",
  "usage": {
    "conversationCount": 412,
    "totalMessages": 3877,
    "activeMessages": 2903,
    "templateMessages": 974
  },
  "usagePercent": 38.8,
  "updatedAt": "2026-08-27T02:41:18.221Z"
}

Campo	Significado
`messageLimit`	Teto de mensagens contratado no período
`usageRenewalDay`	Dia do mês em que o período reinicia
`periodStart`	Início do período corrente
`usage.conversationCount`	Atendimentos concluídos contabilizados
`usage.totalMessages`	Soma de `activeMessages` e `templateMessages`
`usage.activeMessages`	Mensagens de conversa ativa
`usage.templateMessages`	Mensagens de modelo (HSM)
`usagePercent`	`totalMessages` sobre `messageLimit`, com uma casa decimal
`updatedAt`	Quando o número foi atualizado pela última vez

A resposta é cacheada por 1 hora por tenant. Para forçar recálculo:

curl "https://ext.allbound.ia.br/api/usage?refresh=1" -H "x-ext-session: <sessionToken>"

Use o refresh=1 com parcimônia — ele consulta a API da plataforma. Para um
painel que atualiza sozinho, o cache é o comportamento desejado.

Se as dependências não responderem, o endpoint devolve
502 {"error":"usage_unavailable"}. É falha transitória: repita mais tarde, com
backoff.

O que o contador conta

Só atendimentos concluídos. Uma conversa em andamento ainda não entrou no
número, e o valor sobe conforme os atendimentos fecham ao longo do período — não
de forma contínua a cada mensagem trocada.