Conceitos

Antes das rotas, três palavras. Elas aparecem em todo lugar da API, e a hierarquia entre elas explica por que a chave alcança o que alcança.

Conta

É quem paga. A assinatura mora aqui, e a chave de API é da Conta.

Uma chave alcança todas as empresas da conta que a emitiu. Se você é uma agência, é isso que permite provisionar dez clientes com uma credencial só.

Empresa

É o agrupador. Uma agência costuma ter uma empresa por cliente; alguém com dois negócios tem uma para cada.

Empresa não custa nada e não há limite de quantas criar. No painel ela só aparece quando existe mais de uma.

Agente

É quem atende, e é a unidade que entra na fatura. Um agente pode responder no site, no WhatsApp e pela API ao mesmo tempo.

Conta            paga, tem uma assinatura, é dona da chave
  └── Empresa    agrupa, é de graça, quantas quiser
        └── Agente    atende, e é o que se cobra

O que isso significa na prática

Toda requisição acontece dentro da conta da chave. Você escolhe qual empresa quer alcançar pela URL, nunca por um campo no corpo:

GET /v1/workspaces/{workspaceId}/agents

Pedir uma empresa que não é da sua conta devolve 404, o mesmo que pedir uma empresa inexistente. Isso é deliberado: um 403 confirmaria que o recurso existe em outro lugar.

Um fluxo completo

Provisionar um cliente novo, do zero:

# 1. a empresa do cliente
curl -X POST https://api.intelibot.com.br/v1/workspaces \
  -H "Authorization: Bearer $INTELIBOT_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"nome":"Clínica Sorriso"}'

# 2. o agente dentro dela
curl -X POST https://api.intelibot.com.br/v1/workspaces/$EMPRESA/agents \
  -H "Authorization: Bearer $INTELIBOT_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"nome":"Recepção"}'

# 3. o conhecimento
curl -X POST https://api.intelibot.com.br/v1/agents/$AGENTE/sources \
  -H "Authorization: Bearer $INTELIBOT_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"tipo":"website","titulo":"Site da clínica","url":"https://exemplo.com.br"}'

# 4. conversar
curl -X POST https://api.intelibot.com.br/v1/agents/$AGENTE/chat \
  -H "Authorization: Bearer $INTELIBOT_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"mensagem":"Vocês atendem aos sábados?"}'

O que a API não faz

Conectar o Google Agenda. O Google exige que uma pessoa autorize no navegador, e não existe fluxo de servidor para servidor que substitua esse clique. O mesmo vale para conectar o WhatsApp, que passa pelo fluxo da Meta.

Você provisiona todo o resto por aqui e encaminha esses dois passos ao cliente.