Construa sobre a iNTELIGENCIA VIVA
A API pública é o ponto de extensão para qualquer coisa que um desenvolvedor queira construir sobre um workspace: rotear conversas para um sistema próprio, dar a um agente de IA uma ferramenta que consulta o ERP de um cliente, sincronizar contatos com um CRM, ou transmitir eventos ao vivo para o seu próprio painel. É REST, versionada como v1, e todo recurso do modelo de dados do produto é acessível através dela.
Autenticação
Cada solicitação é autenticada com uma chave de API emitida a partir do painel do workspace, enviada como `Authorization: Bearer sk_live_...`.
Cada chave tem seu próprio escopo de permissões configurável — uma chave pode ficar limitada a acesso somente leitura, a recursos específicos, ou receber acesso completo de leitura e escrita, independente de qualquer outra chave emitida para o mesmo workspace.
As chaves são exibidas por completo apenas uma vez, no momento em que são criadas; depois disso, só o titular pode vê-las de novo, e qualquer chave pode ser revogada imediatamente no painel sem afetar as demais.
Authorization: Bearer sk_live_...Recursos
Todo recurso do modelo de dados subjacente está disponível através da API:
| Workspace | Configuração geral, idioma padrão, canais habilitados. |
| Contact | Criação, busca e consulta dos clientes finais que escrevem. |
| Conversation | Listar, criar, encerrar e reatribuir conversas. |
| Message | Enviar e ler mensagens dentro de uma conversa. |
| Department | Gestão de equipes e suas regras de roteamento. |
| Agent | Gestão de usuários humanos, papéis e pertencimento a departamentos. |
| AIAgent | Criar e configurar agentes de IA: instruções, base de conhecimento, ferramentas invocáveis. |
| KnowledgeSource | Enviar e gerenciar documentos e URLs para RAG. |
| Channel | Configurar canais e suas credenciais. |
| Webhook | Assinar eventos de saída, assinados com HMAC. |
| APIKey | Emitir e revogar chaves. |
Eventos de webhook
Assine um `WebhookEndpoint` para qualquer um destes eventos; cada entrega é assinada com HMAC usando o segredo associado a esse endpoint, para que você possa verificar que veio de nós antes de confiar no conteúdo:
| conversation.created | Uma nova conversa começou em qualquer canal. |
| conversation.assigned | Uma conversa foi atribuída a um agente humano ou departamento. |
| conversation.resolved | Uma conversa foi encerrada, pela IA ou por um humano. |
| message.received | Chegou uma nova mensagem recebida de um contato. |
| message.sent | Uma mensagem foi enviada a um contato, pela IA ou por um agente. |
| handoff.requested | A confiança da IA caiu abaixo do limite do workspace e ela pediu um humano. |
| ai_agent.tool_call | Um agente de IA chamou uma de suas ferramentas configuradas, incluindo ferramentas que você mesmo registrou. |
As entregas são reenviadas em caso de falha e não há garantia de exatamente-uma-vez — projete seu manipulador de webhook para ser idempotente. A semântica completa de entrega e reenvio está documentada nos Termos da API para Desenvolvedores.
Streaming em tempo real
Para integrações que precisem consumir eventos ao vivo em vez de, ou além de, webhooks, cada workspace expõe um endpoint de streaming via WebSocket:
wss://api.inteligenciaviva.com/v1/workspaces/{id}/streamLimites de taxa e uso justo
O acesso à API está sujeito a limites de taxa vinculados ao plano do seu workspace; uma solicitação que excede o limite é sinalizada com HTTP 429 e os cabeçalhos de limite de taxa vigentes, para que você possa implementar um backoff correto. Os limites exatos e os termos plenamente vinculantes do uso da API — incluindo o que você pode e não pode fazer com os dados que obtém — estão definidos nos Termos da API para Desenvolvedores, com link a partir da página Legal.