Enviar mensagem — POST /v1/agents/:id/chat

Envia uma mensagem para um agente e recebe a resposta — a mesma rota serve tanto integrações comuns (token chat) quanto o widget incorporável (token widget).

Requisição

POST /v1/agents/:id/chat
Authorization: Bearer f2a_live_...
Content-Type: application/json

{
  "message": "texto da mensagem",
  "conversation_id": "uuid (opcional — omita para começar uma conversa nova)"
}

Um token de widget aceita três campos adicionais, todos opcionais e específicos desse contexto: visitor_id (identifica o visitante para o limite de mensagens por minuto), embed_origin (a origem do site que incorporou o widget, para a checagem de allowed_origins) e turnstile_token (a prova anti-bot, exigida apenas ao iniciar uma conversa nova — veja Proteção contra bots). Uma integração de API comum nunca precisa enviar nenhum desses três.

Resposta síncrona (padrão)

{
  "conversation_id": "uuid",
  "message_id": "uuid",
  "content": "resposta do agente",
  "credits_charged": 2,
  "balance": 87,
  "interrupted": false
}

Essa é a resposta usada pela maioria das integrações não-navegador (scripts, n8n, backends) — uma única chamada que só retorna depois que o turno inteiro termina.

Resposta em streaming (SSE)

Enviando o cabeçalho Accept: text/event-stream, a resposta chega como eventos incrementais em vez de um JSON único:

• meta — conversation_id, message_id e o modelo resolvido, logo no início.
• delta — pedaços de texto conforme o modelo gera a resposta.
• done — tokens consumidos, créditos debitados e saldo final.

Erros comuns

• 402 INSUFFICIENT_CREDITS — saldo insuficiente para esta mensagem.
• 422 GUARDRAIL_BLOCKED — mensagem bloqueada pelo Guardrail do agente; o corpo do erro inclui conversation_id mesmo nesse caso.
• 429 RATE_LIMITED — só para tokens de widget, ao exceder o limite por visitante.
• 403 — origem não autorizada (widget) ou tentativa de usar um token de widget contra um agente diferente do que ele está vinculado.