Visão geral da API

As interfaces programáticas do Take Sales: API HTTP do agente, WebSocket, webhooks, SDK e central de ajuda.

O que existe hoje

O Take Sales expõe cinco caminhos para integrar com sistemas:

Caminho	Para quê	Autenticação
API HTTP do agente	Conversar com um agente a partir do seu backend, mensagem a mensagem	Chave do agente (Bearer)
WebSocket / SDK	Construir sua própria interface de chat ou voz	`agentId` + origem permitida
Webhooks	Receber eventos de conversa no seu sistema	Assinatura HMAC opcional
Widget	Colocar o chat pronto no site, sem código	`agentId` + origem permitida
Central de ajuda	Ler os artigos publicados da base de conhecimento	Pública (só leitura)

ℹ️

Não existe hoje uma API REST pública de administração (criar agentes, listar conversas, editar base de conhecimento por token). A API que o painel consome usa o JWT da sessão do usuário e não é publicada como produto. Precisa de algo assim? Fale com o suporte.

API HTTP do agente

O jeito mais simples de colocar um agente dentro de um sistema seu: você manda uma mensagem, ele devolve a resposta.

POST https://api-agent.takesales.ai/api/agent/{agentId}/messages
Authorization: Bearer SUA_CHAVE_DO_AGENTE
Content-Type: application/json

{
  "message": "Quero saber o status do meu pedido",
  "conversationId": "opcional-para-continuar-uma-conversa",
  "visitor": { "email": "joao@empresa.com", "name": "João", "phone": "+5511999999999" },
  "clientVariables": { "plano": "premium" }
}

Resposta:

{
  "conversationId": "b1e5…",
  "reply": "Seu pedido #1234 saiu para entrega ontem.",
  "tokenUsage": 908,
  "toolCalls": [{ "name": "consultar_pedido", "args": { "id": "1234" } }],
  "richContent": [],
  "handoffRequested": false,
  "status": "active"
}

Campo	Descrição
`conversationId`	Guarde e reenvie para continuar a mesma conversa
`reply`	Texto da resposta do agente
`tokenUsage`	Total de tokens consumidos no turno
`toolCalls`	Ferramentas executadas no turno
`richContent`	Conteúdo estruturado devolvido pelo agente (carrossel, botões)
`handoffRequested`	`true` quando o agente pediu atendimento humano
`status`	`active` ou `escalated`

Detalhes de autenticação, limites e erros em Autenticação.

WebSocket e SDK

O widget e o modo de voz falam WebSocket com o serviço de agente. Para construir uma interface própria reaproveitando esse protocolo, use o SDK JavaScript.

💡

Recursos que só existem no WebSocket: variáveis de página, eventos de tracking e ferramentas executadas no navegador do visitante. Se o seu caso depende deles, use o widget ou o SDK — não a API HTTP.

Central de ajuda pública

Os itens da base de conhecimento marcados como publicados na central de ajuda ficam disponíveis, sem autenticação, em três rotas de leitura. São as mesmas que alimentam a aba de ajuda do widget e a página /ajuda/{agentId}.

GET https://api-agent.takesales.ai/api/agent/{agentId}/help
GET https://api-agent.takesales.ai/api/agent/{agentId}/help/articles?source={sourceId}&q={busca}
GET https://api-agent.takesales.ai/api/agent/{agentId}/help/articles/{itemId}

Rota	Devolve
`/help`	`{ "data": { "collections": [{ "id", "name", "count" }] } }` — fontes com ao menos um artigo publicado
`/help/articles`	`{ "data": { "articles": [{ "id", "sourceId", "title", "excerpt" }] } }` — até 50, mais recentes primeiro; `source` filtra por fonte e `q` (até 100 caracteres) busca no título e no conteúdo
`/help/articles/{itemId}`	`{ "data": { "id", "sourceId", "sourceName", "title", "content", "updatedAt" } }`

Só entram itens publicados e ativos de fontes ligadas ao agente; o agente precisa estar ativo.
Item inexistente e item não publicado respondem igual: 404 Not found.
Limite de 30 requisições por minuto por IP e agente (429).
As respostas vão com Cache-Control: private, max-age=30: despublicar um item tira ele do ar em até 30 segundos.

Formato de respostas

As respostas de erro seguem o formato:

{ "error": "Mensagem curta", "details": "Detalhe opcional" }

Código	Significado
`200`	Sucesso
`400`	Requisição inválida (campo faltando, formato errado)
`401`	Token ausente ou inválido
`402`	Franquia mensal de conversas ou tokens de texto esgotada, ou limite de uso atingido
`403`	Recurso desabilitado para esse agente
`404`	Agente ou conversa não encontrada
`429`	Limite de requisições excedido
`500`	Erro interno

Boas práticas

Verifique o status antes de usar o corpo da resposta
Não repita requisições em 400/401 — corrija o payload ou o token
Em 429, aplique backoff (1s, 2s, 4s) — o limite da API do agente é por agente e por minuto
Em 402, avise a operação — o problema é a franquia de texto (conversas/tokens) do mês ou limite de uso, não a integração
Guarde o conversationId por sessão do seu sistema, para manter o contexto

Próximos passos

Autenticação — Habilitar a API e gerar a chave do agente
Webhooks — Receber eventos das conversas
SDK JavaScript — Interface própria por WebSocket
Custom Tools — Dar ao agente acesso às suas APIs
Base de conhecimento — Publicar itens na central de ajuda