Conversas da API v2

Use esses endpoints para ler o histórico de conversas e trabalhar com mensagens da API v2. Todo endpoint desta página exige Authorization: Bearer YOUR_API_KEY e acesso a {agentId}.

Escopo da Conversa

Os endpoints de conversas somente leitura 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 ficam 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.

Objetos de Resposta

Os resumos de conversa contêm:

Os objetos de mensagem contêm:

Linhas de mensagens do tipo tool são omitidas das transcrições de conversas e das listas de mensagens.

Listar Conversas

Caminho: /api/v2/agents/{agentId}/conversations

GET /api/v2/agents/{agentId}/conversations

Autenticação: Chave de API Bearer com acesso a {agentId}.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations?source=all&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Sucesso: 200 OK

{
  "data": [
    {
      "id": "b2mD4kL8pQ1sT6vX",
      "title": "Where is my order?",
      "createdAt": 1784332800,
      "updatedAt": 1784332860,
      "userId": "customer_123",
      "source": "api_v2",
      "status": "ongoing"
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Limites inválidos, cursores, valores de source e parâmetros de source duplicados retornam 400 VALIDATION_INVALID_BODY.

Exportar Conversas

Caminho: /api/v2/agents/{agentId}/conversations/export

GET /api/v2/agents/{agentId}/conversations/export

Autenticação: Chave de API Bearer com acesso a {agentId}.

A exportação usa a mesma ordenação de conversas e o mesmo contrato de cursor do endpoint de listagem, mas limita cada página a 20 conversas. Cada conversa inclui todas as mensagens não-tool, ordenadas da mais antiga para a mais recente.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/export?source=api_v2' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Sucesso: 200 OK

{
  "data": [
    {
      "id": "b2mD4kL8pQ1sT6vX",
      "title": "Where is my order?",
      "createdAt": 1784332800,
      "updatedAt": 1784332860,
      "userId": "customer_123",
      "source": "api_v2",
      "status": "ongoing",
      "messages": [
        {
          "id": "122",
          "role": "user",
          "parts": [{ "type": "text", "text": "Where is my order?" }],
          "createdAt": 1784332800,
          "feedback": null,
          "metadata": null
        }
      ]
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Obter uma Conversa

Caminho: /api/v2/agents/{agentId}/conversations/{conversationId}

GET /api/v2/agents/{agentId}/conversations/{conversationId}

Autenticação: Chave de API Bearer com acesso a {agentId}.

A resposta inclui toda a transcrição não-tool, ordenada da mais antiga para a mais recente. Este endpoint não é paginado por cursor; use o endpoint de listagem de mensagens para acesso paginado às mensagens da API v2.

Sucesso: 200 OK

{
  "data": {
    "id": "b2mD4kL8pQ1sT6vX",
    "title": "Where is my order?",
    "createdAt": 1784332800,
    "updatedAt": 1784332860,
    "userId": "customer_123",
    "source": "api_v2",
    "status": "ongoing",
    "messages": [
      {
        "id": "122",
        "role": "user",
        "parts": [{ "type": "text", "text": "Where is my order?" }],
        "createdAt": 1784332800,
        "feedback": null,
        "metadata": null
      }
    ]
  },
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Uma conversa ausente dentro da fonte selecionada retorna 404 RESOURCE_NOT_FOUND.

Listar Mensagens

Caminho: /api/v2/agents/{agentId}/conversations/{conversationId}/messages

GET /api/v2/agents/{agentId}/conversations/{conversationId}/messages

Autenticação: Chave de API Bearer com acesso a {agentId}. A conversa deve ser uma conversa da API v2.

Os cursores de mensagem são o único cursor de paginação v2 cujo componente de ID do lado do servidor é validado como uma string numérica, porque as mensagens usam IDs bigint. Todo outro recurso v2 paginado valida IDs UUID. Trate ambas as formas como opacas; nunca construa ou decodifique cursores. As mensagens dentro de cada página retornada são ordenadas da mais antiga para a mais recente.

Sucesso: 200 OK

{
  "data": [
    {
      "id": "122",
      "role": "user",
      "parts": [{ "type": "text", "text": "Where is my order?" }],
      "createdAt": 1784332800,
      "feedback": null,
      "metadata": null
    },
    {
      "id": "123",
      "role": "assistant",
      "parts": [{ "type": "text", "text": "Please share your order number." }],
      "createdAt": 1784332860,
      "feedback": "positive",
      "metadata": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 2
  }
}

Uma conversa da API v2 ausente retorna 404 RESOURCE_NOT_FOUND; limites e cursores inválidos retornam 400 VALIDATION_INVALID_BODY.

Reenviar uma Resposta do Assistente

Caminho: /api/v2/agents/{agentId}/conversations/{conversationId}/retry

POST /api/v2/agents/{agentId}/conversations/{conversationId}/retry

Autenticação: Chave de API Bearer com acesso a {agentId}. A conversa deve ser uma conversa da API v2.

O retry exclui a mensagem do usuário anterior, a resposta do assistente selecionada e todas as mensagens posteriores, e então reproduz esse texto do usuário para regenerar a resposta. Se a regeneração falhar ao persistir, as linhas excluídas são restauradas.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/b2mD4kL8pQ1sT6vX/retry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"messageId":"123","stream":false}'

Sucesso: 200 OK. Com stream: true, a resposta é um stream de Server-Sent Events usando o mesmo formato de evento que chat. Com stream: false, a resposta é:

{
  "data": {
    "id": "124",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "Here is a regenerated answer." }],
    "metadata": {
      "conversationId": "b2mD4kL8pQ1sT6vX",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

JSON malformado retorna 400 VALIDATION_INVALID_JSON. Corpos inválidos retornam 400 VALIDATION_INVALID_BODY. Veja CHAT_RETRY_MESSAGE_NOT_FOUND, CHAT_RETRY_NO_USER_MESSAGE, RESOURCE_NOT_FOUND, e INTERNAL_SERVER_ERROR no catálogo de erros.

Enviar um Resultado de Ferramenta

Caminho: /api/v2/agents/{agentId}/conversations/{conversationId}/tool-result

POST /api/v2/agents/{agentId}/conversations/{conversationId}/tool-result

Autenticação: Chave de API Bearer com acesso a {agentId}.

{
  "toolCallId": "call_123",
  "output": { "available": true }
}

Resposta: Uma ação pendente correspondente é reivindicada uma única vez e a continuação é retornada como text/event-stream. Chamadas desconhecidas ou expiradas retornam 404; resultados concorrentes ou conflitantes retornam 409.

Definir ou Limpar o Feedback de uma Mensagem

Caminho: /api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

PATCH /api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

Autenticação: Chave de API Bearer com acesso a {agentId}. A conversa deve ser uma conversa da API v2.

{messageId} deve se converter em um inteiro positivo e deve identificar uma mensagem do assistente de IA na conversa especificada.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/b2mD4kL8pQ1sT6vX/messages/123/feedback' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"feedback":"positive"}'

Sucesso: 200 OK

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "Please share your order number." }],
    "createdAt": 1784332860,
    "feedback": "positive",
    "metadata": null
  }
}

JSON malformado retorna 400 VALIDATION_INVALID_JSON; um corpo inválido retorna 400 VALIDATION_INVALID_BODY; uma conversa ausente retorna 404 RESOURCE_NOT_FOUND; uma mensagem ausente retorna 404 RESOURCE_MESSAGE_NOT_FOUND; e um destino que não seja do assistente de IA retorna 422 RESOURCE_MESSAGE_NOT_ASSISTANT.

Listar Conversas de um Usuário

Caminho: /api/v2/agents/{agentId}/users/{userId}/conversations

GET /api/v2/agents/{agentId}/users/{userId}/conversations

Autenticação: Chave de API Bearer com acesso a {agentId}.

{userId} deve ter de 1 a 128 caracteres e pode conter apenas letras, números, ., _, e -.

Apenas o chat da API v2 grava userId, então este endpoint retorna somente conversas da API v2. Sua resposta de sucesso é o mesmo envelope paginado de resumos de conversa usado em Listar Conversas.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/users/customer_123/conversations' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Sucesso: 200 OK. IDs de usuário, limites, cursores ou uso de source inválidos retornam 400 VALIDATION_INVALID_BODY.

Referências Relacionadas

• Visão geral e chat da API v2
• Catálogo de erros da API v2
• Contatos e identidade verificada