Documentação da API — REST v1, webhooks e streaming

Quickstart: sua primeira requisição em 60 segundos

Crie uma chave de API no seu workspace, exporte-a e liste suas conversas. As chaves têm escopo por workspace e podem ser somente leitura ou leitura e escrita.

curl https://api.inteligenciaviva.com/v1/workspaces/WORKSPACE_ID/conversations \
  -H "Authorization: Bearer sk_live_..."

Toda resposta é JSON. Endpoints de coleção devolvem arrays `data`; erros devolvem um objeto `error` com `code` e `message` e o status HTTP correspondente.

A API gratuita — sem conta, sem chave

A camada gratuita também fala API. `POST /v1/free/widget-snippet` recebe exatamente a mesma configuração que o gerador visual da página Grátis monta e devolve o snippet HTML pronto para colar — sem autenticação, sem cadastro. Use-a para gerar widgets em lote para sites de clientes, regenerar embeds a partir do CI quando os horários mudam, ou simplesmente para tocar a API antes de pagar um centavo.

curl -X POST https://api.inteligenciaviva.com/v1/free/widget-snippet \
  -H "Content-Type: application/json" \
  -d @widget-config.json
# → { "snippet": "<link rel=\"stylesheet\" ..." }

Autenticação

Toda requisição leva uma chave de API no cabeçalho `Authorization` como token Bearer. As chaves são criadas e revogadas pela própria API ou pelo painel, por workspace — revogar uma chave corta o acesso imediatamente.

Os endpoints de sessão no nível da conta (registro, login, acesso com Google, troca de ticket, perfil e exclusão de conta sob `/v1/auth`) alimentam nossos próprios apps; para integrações servidor-a-servidor, prefira sempre chaves de API de workspace a sessões de usuário.

Authorization: Bearer sk_live_...

Referência de recursos

Todas as rotas abaixo pendem de `https://api.inteligenciaviva.com/v1/workspaces/{workspaceId}`, salvo indicação em contrário. Esta é a superfície real montada do backend atual — não aspiracional.

Caixa combinada `/inbox`

GET	/conversations	Todas as conversas de TODOS os espaços que a credencial atende, numa lista única ordenada por atividade.
GET	/conversations/{id}	Uma conversa procurada em todos os seus espaços, sem saber em qual está. Devolve o workspace_id.
GET	/workspaces	Os espaços que esta credencial pode atender, com o papel em cada um.

Conversas `/conversations`

GET	/	Listar conversas, filtráveis por estado.
GET	/{id}	Uma conversa com seu estado, canal, contato e atribuição.
GET	/{id}/messages	Histórico de mensagens (visitante, agente humano, IA, sistema).
POST	/{id}/messages	Enviar uma mensagem à conversa como agente.
POST	/{id}/assign	Atribuir a conversa a um agente humano ou a um departamento.
POST	/{id}/resolve	Fechar a conversa. Se a IA a fechou sozinha, conta como resolução faturável.
POST	/	Abrir uma conversa fora do widget (por exemplo, para migrar um tópico existente).
GET	/{id}/ai-turns	«De onde tirou isso?» — o registro de cada turno de IA: em que se apoiou, com qual modelo, quanto demorou e por que transferiu.
GET	/{id}/portal-case	Estado do caso que esta conversa abriu no painel de suporte do Portal, com suas respostas. Consultado ao vivo: o estado muda no outro painel.
POST	/{id}/read	Marcar a conversa como lida pela equipe (contador de não lidas).
POST	/{id}/reopen	Reabrir uma conversa fechada, mantendo o histórico. Sem isso, um fechamento por engano não tinha volta.
POST	/{id}/archive	Arquivar ou desarquivar. Sai da caixa sem ser fechada nem perder nada; o corpo é {valor:true\|false}.
POST	/{id}/pin	Fixar no topo ou soltar. As fixadas encabeçam a primeira página da caixa. Corpo: {valor:true\|false}.
POST	/{id}/mute	Silenciar os avisos por N horas, ou {horas:null} para voltar a ouvi-la.
POST	/{id}/unread	Deixá-la como não lida: recua a marca de leitura para trás da última mensagem do cliente.

Contatos `/contacts`

GET	/	Listar contatos.
GET	/{id}	Um contato com suas identidades e seu histórico de conversas.

Agentes de IA `/ai-agents`

GET	/	Listar os agentes de IA do workspace.
POST	/	Criar um agente de IA: instruções, departamento, limiar de confiança.
PATCH	/{id}	Atualizar instruções, limiar ou departamento.
GET	/{id}/knowledge-sources	Fontes de conhecimento associadas a este agente.
POST	/{id}/knowledge-sources	Associar uma fonte de conhecimento a este agente.
GET	/{aiAgentId}	Um agente de IA: instruções, limiar de confiança, ferramentas e departamento.

Conhecimento (RAG) `/knowledge-sources`

POST	/document	Indexar um documento como conhecimento fundamentado.
POST	/url	Indexar uma URL.
GET	/{id}	Status e metadados da fonte.
DELETE	/{id}	Remover uma fonte e seus vetores.
POST	/{id}/reindex	Reler uma fonte de URL sem apagá-la: se o download falhar, nada é alterado.
GET	/	Listar as fontes de conhecimento com seu estado de indexação.

Canais `/channels`

GET	/	Listar canais. Vivos hoje: chat web e API; mais canais se conectam à medida que forem lançados.
PUT	/{id}/credentials	Definir as credenciais de um canal.
PUT	/{id}/status	Habilitar ou desabilitar um canal.
POST	/	Criar um canal.
GET	/{channelId}	Um canal com seu tipo, estado e configurações.
GET	/{channelId}/snippet	A linha única que o cliente cola no site. Todo o resto se configura aqui.
GET	/{channelId}/config	A configuração do chat: o publicado (`config`) e o que este canal sobrescreve (`settings`). São diferentes.
PUT	/{channelId}/config	Salvar a configuração. Salvar e publicar são o mesmo passo: se a CDN falhar, o PUT falha.
POST	/{channelId}/config/publish	Republicar a configuração na CDN sem alterá-la.
POST	/{channelId}/avatar	Enviar o rosto do assistente (≤512 KB). Vai para o R2 e é servido pela CDN.
POST	/republicar-todos	Republicar todos os canais do workspace. O cron faz isso quando o pacote de textos muda; isto é para não esperar.

Agentes humanos e departamentos `/agents · /departments`

GET	/agents	Listar os agentes humanos do workspace.
POST	/agents/{userId}/departments	Colocar um agente em um departamento.
GET	/departments	Listar departamentos.
PUT	/departments/{id}/routing-rules	Definir regras de roteamento para conversas recebidas.
POST	/agents	Convidar uma pessoa para o workspace, com papel e departamentos.
GET	/agents/{userId}	Uma pessoa da equipe.
POST	/departments	Criar um departamento com suas regras de roteamento.
GET	/departments/{id}	Um departamento.

Webhooks, chaves, faturamento, análises `/webhooks · /api-keys · /billing · /analytics`

POST	/webhooks	Registrar um endpoint; você recebe o segredo de assinatura uma única vez.
DELETE	/webhooks/{id}	Remover um endpoint.
POST	/api-keys	Criar uma chave (somente leitura ou leitura e escrita).
DELETE	/api-keys/{id}	Revogar uma chave imediatamente.
GET	/billing/subscription	Plano, resoluções de IA incluídas e uso do período.
GET	/analytics	Métricas agregadas do workspace.
GET	/webhooks	Listar os endpoints de webhook.
GET	/webhooks/{id}/deliveries	Histórico de entregas de um webhook, com retentativas. É o que diz se a falha é sua ou nossa.
GET	/api-keys	Listar as chaves. O segredo nunca é devolvido: só o prefixo.

Ferramentas do agente `/conversations/{id} · /canned-responses · /tags · /presence`

GET	/conversations/{id}/notes	Notas internas da conversa. O visitante nunca as vê.
POST	/conversations/{id}/notes	Adicionar uma nota interna.
DELETE	/conversations/{id}/notes/{noteId}	Excluir uma nota interna.
GET	/canned-responses	Respostas prontas do workspace, com seu atalho.
POST	/canned-responses	Criar uma resposta pronta.
PATCH	/canned-responses/{cannedId}	Editar uma resposta pronta.
DELETE	/canned-responses/{cannedId}	Excluir uma resposta pronta.
POST	/presence	Batimento de presença: declara que há uma pessoa atendendo. Somente com sessão — uma chave de API que pulsa não é alguém olhando a tela, e é rejeitada com 400.
GET	/presence	Há alguém on-line agora? É o que decide se uma transferência espera ou é desviada.
GET	/ai-usage	Consumo de inferência do workspace por dia e as conversas que mais gastam.
GET	/tags	Etiquetas do workspace.
GET	/conversations/{id}/tags	Etiquetas de uma conversa.
POST	/conversations/{id}/tags	Etiquetar uma conversa. Cria a etiqueta se não existia.
DELETE	/conversations/{id}/tags/{tagId}	Remover uma etiqueta da conversa.
POST	/conversations/{id}/transfer	Transferir a conversa para um departamento. Prevalece sobre as regras de roteamento: uma transferência manual não se desfaz sozinha.
POST	/contacts/{contactId}/block	Bloquear um contato. Recebe 403 sem detalhes: a quem abusa não se explica como foi detectado.

Anexos, dispositivos e workspaces `/conversations/{id}/attachments · /devices · /workspaces`

POST	/conversations/{id}/attachments	Enviar um anexo como agente. Lista branca estrita e 10 MB: nada que um navegador possa executar entra.
GET	/conversations/{id}/attachments	Anexos de uma conversa.
GET	/attachments/{attachmentId}	Baixar um anexo. Servido com cabeçalhos rígidos e `nosniff`; só imagens e áudio aparecem embutidos.
POST	/devices/register	Registrar o token push de um dispositivo, para avisar uma pessoa quando a IA transferir. Fora do prefixo de workspace: `/v1/devices/register`.
POST	/workspaces	Criar um workspace. Fora do prefixo: `/v1/workspaces`.

Exemplos reais

Enviar uma mensagem de agente (curl)

curl -X POST \
  https://api.inteligenciaviva.com/v1/workspaces/$WS/conversations/$CONV/messages \
  -H "Authorization: Bearer $IV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hi! I checked your order — it ships tomorrow."}'

Listar conversas (JavaScript)

const res = await fetch(
  `https://api.inteligenciaviva.com/v1/workspaces/${WS}/conversations`,
  { headers: { Authorization: `Bearer ${process.env.IV_KEY}` } }
);
const { data } = await res.json();

Verificar a assinatura de um webhook (Node)

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, rawBody, header, toleranceSec = 300) {
  const { t, v1 } = Object.fromEntries(
    header.split(",").map((p) => p.split("="))
  );
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Webhooks

Registre um endpoint HTTPS e enviamos cada evento por POST, assinado. O cabeçalho é `iv-signature: t=<unix>,v1=<hex>`, onde `v1` é o HMAC-SHA256 de `<timestamp>.<corpo bruto>` com o segredo do seu endpoint — rejeite qualquer coisa com mais de 5 minutos (proteção contra replay). Entregas com falha são reenviadas automaticamente com assinatura nova, em até 5 tentativas.

conversation.created	Uma nova conversa começou em qualquer canal.
message.created	Chegou uma mensagem (visitante, humano, IA ou sistema).
handoff.requested	A IA decidiu que precisa de um humano — o momento exato, com o resumo.
conversation.resolved	Uma conversa foi fechada; informa se a IA a fechou sozinha.

Cada entrega e seu status ficam registrados — um webhook em que você não pode confiar é pior do que nenhum.

Streaming em tempo real

Para interfaces ao vivo, abra um WebSocket contra o stream do workspace e receba os eventos de conversa conforme acontecem — o mesmo canal que nossos próprios apps de agente usam.

wss://api.inteligenciaviva.com/v1/workspaces/{workspaceId}/stream

Erros e limites

Os erros são HTTP convencional: `400` requisição malformada, `401` chave ausente ou inválida, `403` chave sem escopo, `404` recurso que não está neste workspace, `429` limite de taxa (espere e tente de novo com jitter), `5xx` culpa nossa — repita as requisições idempotentes. O corpo sempre traz um `error.code` e um `error.message` humano. Os limites de taxa são por chave e generosos para integrações reais.

Perguntas frequentes

Esta documentação é aspiracional ou a superfície real?

Real. Foi escrita contra as rotas montadas do backend atual. Quando algo aqui diz "em breve", é porque ainda não existe — não documentamos fumaça.

Preciso de um plano pago para usar a API?

Sim — a API faz parte da plataforma paga (o Pro a inclui). O Widget gratuito e o plugin de WordPress são client-side e não precisam de API nenhuma.

Qual é a diferença entre chaves somente leitura e de leitura e escrita?

As somente leitura podem listar e consultar, mas nunca mutar — ideais para dashboards e BI. As de leitura e escrita podem criar mensagens, contatos, agentes de IA e configuração.

Como fico sabendo de mensagens novas — polling ou webhooks?

Webhooks (`message.created`) para servidores, o stream por WebSocket para interfaces ao vivo. Polling funciona, mas você vai esbarrar nos limites de taxa antes de conseguir tempo real.

Como verifico exatamente que um webhook veio de vocês?

Recalcule o HMAC-SHA256 de `<t>.<corpo bruto>` com o segredo do seu endpoint e compare em tempo constante com o valor `v1` do cabeçalho `iv-signature`; rejeite se `t` tiver mais de 300 segundos. O código funcional está nesta página.

O que acontece se meu endpoint de webhooks estiver fora do ar?

Registramos a entrega com falha e tentamos de novo automaticamente com timestamp e assinatura novos, em até 5 tentativas. Se o endpoint tiver sido removido ou desabilitado nesse meio-tempo, as tentativas param de forma limpa.

A IA pode escalar para o meu próprio sistema?

Sim — é exatamente para isso que existe `handoff.requested`. Ele dispara no momento em que a confiança da IA cai abaixo do limiar do workspace, levando o resumo da conversa, para que você acione uma pessoa ou abra um ticket em outro sistema.

Quais canais posso controlar pela API hoje?

O chat web está vivo de ponta a ponta, e tudo nesta referência funciona hoje. Telegram e outros canais de mensagens se conectam ao mesmo modelo de conversa à medida que forem lançados — sua integração não muda.

Existe SDK?

Um SDK Flutter alimenta nosso próprio app de agente e é a base do SDK white-label do Enterprise. Para servidores, a superfície REST é deliberadamente simples — qualquer cliente HTTP funciona sem wrapper.

Onde reporto um bug da API ou uma lacuna nesta documentação?

Escreva para l@inteligenciaviva.com. Documentação que mente também é bug — tratamos com a mesma seriedade.

Construa sobre a mesma API sobre a qual nós construímos

Quickstart: sua primeira requisição em 60 segundos

A API gratuita — sem conta, sem chave

Autenticação

Referência de recursos

Caixa combinada /inbox

Conversas /conversations

Contatos /contacts

Agentes de IA /ai-agents

Conhecimento (RAG) /knowledge-sources

Canais /channels

Agentes humanos e departamentos /agents · /departments

Webhooks, chaves, faturamento, análises /webhooks · /api-keys · /billing · /analytics

Ferramentas do agente /conversations/{id} · /canned-responses · /tags · /presence

Anexos, dispositivos e workspaces /conversations/{id}/attachments · /devices · /workspaces