Canal API

O canal API publica o agente como um endpoint HTTP que qualquer sistema externo pode chamar — sites, apps, automações ou backends próprios. A autenticação é feita com um token de aplicação (Bearer), gerado na própria tela de Publicar.

Ativar e obter o token

Abra o canal API

Em Agent Studio → Publicar, clique no canal API.

Gere o token

Clique em Gerar token. O endpoint e o token aparecem prontos para copiar.

O token é exibido uma única vez. Copie e guarde em local seguro — depois dele só mostramos um preview mascarado (faa_…últimos4). Se perder, regenere (o anterior é revogado na hora).

Use endpoint + token nas requisições

Envie o token no header Authorization: Bearer <token> para o endpoint exibido.

Rotacionar e revogar

Regenerar token emite um novo e revoga o anterior imediatamente — atualize suas integrações.
Revogar invalida o token e desativa o canal. Chamadas com o token antigo passam a retornar 401.

O endpoint

POST {endpoint}

O {endpoint} é o que aparece na tela, no formato …/api/agent-api/v1/agents/<uuid-do-agente>/messages. Headers

Header	Valor
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`message`	string	Sim	Mensagem do usuário.
`conversationId`	string	Não	UUID de uma conversa existente para continuar. Omita para iniciar uma nova.
`stream`	boolean	Não	`true` → resposta em SSE; `false`/omitido → JSON (padrão).

O fluxo de conversa

A conversa é identificada por um UUID (nunca um id numérico sequencial — isso evita que terceiros adivinhem conversas de outros).

Primeira mensagem (sem conversationId)

Não envie conversationId. O sistema cria uma nova conversa e devolve o conversationId (UUID) na resposta.

Mensagens seguintes (com conversationId)

Reenvie o conversationId recebido para continuar a mesma conversa, mantendo o contexto. Sem ele, uma nova conversa é criada a cada chamada.

Exemplos

curl -X POST "https://SEU_ENDPOINT/api/agent-api/v1/agents/<uuid>/messages" \
  -H "Authorization: Bearer faa_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{"message":"Qual o horário de atendimento?"}'

{
  "conversationId": "b3f1c2a4-5d6e-4f70-8a91-2c3d4e5f6a7b",
  "answer": "Atendemos de segunda a sexta, das 9h às 18h."
}

curl -X POST "https://SEU_ENDPOINT/api/agent-api/v1/agents/<uuid>/messages" \
  -H "Authorization: Bearer faa_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{"message":"E nos feriados?","conversationId":"b3f1c2a4-5d6e-4f70-8a91-2c3d4e5f6a7b"}'

curl -N -X POST "https://SEU_ENDPOINT/api/agent-api/v1/agents/<uuid>/messages" \
  -H "Authorization: Bearer faa_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{"message":"Me conte sobre os planos","stream":true}'

No modo streaming, o corpo emite eventos data: {"type":"text-delta","delta":"..."} seguidos de data: [DONE], e o conversationId volta no header X-Conversation-Id.

Listar mensagens de uma conversa

Recupere o histórico de uma conversa (mensagens do usuário e do agente), de forma paginada e em ordem cronológica.

GET {endpoint-base}/v1/agents/<uuid-do-agente>/conversations/<conversationId>/messages?page=1&limit=20

Query	Tipo	Descrição
`page`	número	Página (1-based). Opcional.
`limit`	número	Itens por página. Opcional.

curl "https://SEU_ENDPOINT/v1/agents/<uuid>/conversations/<conversationId>/messages?page=1&limit=20" \
  -H "Authorization: Bearer faa_seu_token_aqui"

{
  "data": [
    { "role": "USER", "content": "Qual o horário de atendimento?", "createdAt": "2026-06-11T12:00:00.000Z" },
    { "role": "ASSISTANT", "content": "Atendemos de segunda a sexta, das 9h às 18h.", "createdAt": "2026-06-11T12:00:01.000Z" }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1 }
}

Erros

Status	Quando acontece
`401`	Token ausente, inválido, expirado ou revogado.
`403`	O token não pertence ao agente da URL.
`404`	`conversationId` informado não existe para esse agente.
`422`	`message` ausente ou vazio.

Cada token é vinculado a um agente e isolado por organização. Use tokens diferentes por integração para conseguir revogar uma sem afetar as demais.

Começando

Aurora Produtividade

Agent Studio

Acompanhamento

Ativar e obter o token

Rotacionar e revogar

O endpoint

O fluxo de conversa

Exemplos

Listar mensagens de uma conversa

Erros

​Ativar e obter o token

​Rotacionar e revogar

​O endpoint

​O fluxo de conversa

​Exemplos

​Listar mensagens de uma conversa

​Erros

Ativar e obter o token

Rotacionar e revogar

O endpoint

O fluxo de conversa

Exemplos

Listar mensagens de uma conversa

Erros