API v2

A API v2 é uma API REST estruturada para gerenciar agentes e construir experiências de chat personalizadas. Ela adiciona gerenciamento de agentes, chat com streaming, histórico de conversas, feedback de mensagens, contatos, leads, fontes, configurações e endpoints de treinamento.

O acesso à API requer um plano Hobby ou superior com faturamento ativo.

URL Base

https://your-domain.com/api/v2

Autenticação

Exceto para a verificação de saúde, envie a chave de API da sua área de trabalho como um bearer token:

Authorization: Bearer YOUR_API_KEY

Crie e revogue chaves de API em Configurações > Chaves de API.

Formato de Resposta

A maioria das respostas bem-sucedidas retorna um objeto de recurso ou um envelope data:

{
  "data": []
}

Os endpoints de listagem incluem paginação por cursor:

{
  "data": [],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 0
  }
}

Os erros usam um objeto error estruturado:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Toda resposta da v2 inclui um cabeçalho x-request-id. Inclua-o ao entrar em contato com o suporte sobre uma requisição de API.

Escopo de Conversa

Os endpoints somente leitura de conversas usam por padrão source=api_v2. Defina source=widget para retornar conversas do widget e do Playground; as linhas do Playground são armazenadas com a fonte widget. Defina source=all para retornar conversas da API v2, do widget e do Playground. Os resultados sempre permanecem limitados ao agente da conta autenticada. Um valor de source inválido ou mais de um parâmetro de consulta source retorna 400 VALIDATION_INVALID_BODY. A continuação de chat, retry, feedback, listagem de mensagens e leituras por usuário permanecem restritas às conversas da API v2.

Saúde

GET /api/v2/health

A verificação de saúde não requer autenticação.

Sucesso: 200 OK

{
  "status": "ok",
  "timestamp": 1784332800
}

timestamp é o timestamp Unix atual em segundos.

Chat

POST /api/v2/agents/{agentId}/chat

Requisição:

{
  "message": "What plans do you offer?",
  "conversationId": "optional-existing-conversation-id",
  "userId": "optional-user-id",
  "stream": true
}

As respostas com streaming usam Server-Sent Events. O stream inclui os eventos message-start, text-start, text-delta, text-end, message-metadata, finish e [DONE]. Uma falha no stream ou no hook de conclusão emite um evento error com error.code definido como CHAT_STREAMING_ERROR; esse código de protocolo exclusivo do SSE é separado do catálogo de erros estruturado da REST. message-metadata contém o ID da mensagem do assistente quando a persistência é bem-sucedida, além do ID da conversa, ID do usuário, motivo de finalização e uso. Seu messageId é null quando nenhuma mensagem do assistente foi persistida. Quando a resposta pausa em uma ação do lado do cliente, o stream também emite um evento tool-call com { "id", "name", "arguments" }; envie o resultado para o endpoint de tool-result para retomar a conversa — a resposta a essa requisição transmite a continuação.

As respostas sem streaming retornam:

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "..." }],
    "pendingToolCall": null,
    "metadata": {
      "userMessageId": "122",
      "conversationId": "abc123",
      "userId": "user_123",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

Os valores data.id e metadata.userMessageId sem streaming são IDs numéricos de mensagem serializados como strings, ou null quando a mensagem correspondente não foi persistida. metadata.userId é o ID de usuário fornecido/armazenado ou null. pendingToolCall é null, a menos que a resposta tenha pausado em uma chamada de ferramenta no lado do cliente; nesse caso, contém { "id", "name", "arguments" } para o endpoint de resultado de ferramenta.

Resumo dos Endpoints

Feedback

Use o feedback para marcar mensagens do assistente da API v2 como positive, negative ou null. Consulte Conversas, mensagens e feedback para o esquema da requisição, a resposta e o comportamento de erro.

Paginação

Trate os cursores como tokens opacos retornados pela API. Reenvie o valor de pagination.cursor sem alterações na próxima requisição; não o construa nem o decodifique.

Contatos também aceitam search. Leads aceitam filtros de data/hora ISO 8601 inclusivos createdAfter e createdBefore. Fontes aceitam sourceType com web_crawl, file_upload, text_snippet ou qna_entry.

Os formatos de cursor são um detalhe interno de implementação. Os clientes devem tratar todo cursor como opaco e reenviá-lo sem alterações, sem construí-lo nem decodificá-lo.

Erros Comuns

Consulte o catálogo completo de erros da API v2 para todos os 27 códigos declarados, status HTTP, gatilhos e códigos reservados.

Referência

• Catálogo de erros
• Agentes e configurações
• Conversas, mensagens, retries e feedback
• Fontes e treinamento
• Contatos e leads
• Canal do Instagram

Próximos Passos

• Crie uma chave de API
• Configure a verificação de identidade
• Revise os erros da API v2
• Gerencie agentes e configurações
• Trabalhe com conversas
• Gerencie fontes e treinamento
• Gerencie contatos e leads
• Gerencie o canal do Instagram