Conversaciones de la API v2

Usa estos endpoints para leer el historial de conversaciones y trabajar con los mensajes de la API v2. Todos los endpoints de esta página requieren Authorization: Bearer YOUR_API_KEY y acceso a {agentId}.

Alcance de las conversaciones

Los endpoints de conversaciones de solo lectura usan source=api_v2 de forma predeterminada. Configura source=widget para devolver conversaciones del widget y del Playground; las filas del Playground se almacenan con el origen widget. Configura source=all para devolver conversaciones de la API v2, del widget y del Playground. Los resultados siempre se limitan al agente de la cuenta autenticada. Un valor de source inválido o más de un parámetro de consulta source devuelve 400 VALIDATION_INVALID_BODY. La continuación de chat, los reintentos, los comentarios, el listado de mensajes y las lecturas por usuario siguen limitados a las conversaciones de la API v2.

Objetos de respuesta

Los resúmenes de conversación contienen:

Los objetos de mensaje contienen:

Las filas de mensajes de tipo herramienta se omiten de las transcripciones de conversación y de los listados de mensajes.

Listar conversaciones

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

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

Autenticación: Clave de API bearer con acceso 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'

Éxito: 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
  }
}

Los límites, cursores, valores de source inválidos y los parámetros de source duplicados devuelven 400 VALIDATION_INVALID_BODY.

Exportar conversaciones

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

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

Autenticación: Clave de API bearer con acceso a {agentId}.

La exportación usa el mismo orden de conversaciones y el mismo contrato de cursor que el endpoint de listado, pero limita cada página a 20 conversaciones. Cada conversación incluye todos los mensajes que no son de herramientas, ordenados de más antiguo a más reciente.

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

Éxito: 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
  }
}

Obtener una conversación

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

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

Autenticación: Clave de API bearer con acceso a {agentId}.

La respuesta incluye toda la transcripción que no es de herramientas, ordenada de más antigua a más reciente. Este endpoint no usa paginación por cursor; usa el endpoint de listado de mensajes para el acceso paginado a los mensajes de la API v2.

Éxito: 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
  }
}

Una conversación faltante dentro del origen seleccionado devuelve 404 RESOURCE_NOT_FOUND.

Listar mensajes

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

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

Autenticación: Clave de API bearer con acceso a {agentId}. La conversación debe ser una conversación de la API v2.

Los cursores de mensajes son el único cursor de paginación de v2 cuyo componente de ID en el servidor se valida como un string numérico, porque los mensajes usan ID de tipo bigint. Todos los demás recursos paginados de v2 validan ID de tipo UUID. Trata ambas formas como opacas; nunca construyas ni decodifiques los cursores. Dentro de cada página devuelta, los mensajes se ordenan de más antiguo a más reciente.

Éxito: 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
  }
}

Una conversación de la API v2 faltante devuelve 404 RESOURCE_NOT_FOUND; los límites y cursores inválidos devuelven 400 VALIDATION_INVALID_BODY.

Reintentar una respuesta del asistente

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

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

Autenticación: Clave de API bearer con acceso a {agentId}. La conversación debe ser una conversación de la API v2.

El reintento elimina el mensaje de usuario anterior, la respuesta del asistente seleccionada y todos los mensajes posteriores, y luego reproduce ese texto de usuario para regenerar la respuesta. Si la regeneración no logra persistirse, se restauran las filas eliminadas.

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}'

Éxito: 200 OK. Con stream: true, la respuesta es un stream de Server-Sent Events que usa el mismo formato de eventos que chat. Con stream: false, la respuesta es:

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

El JSON con formato incorrecto devuelve 400 VALIDATION_INVALID_JSON. Los cuerpos inválidos devuelven 400 VALIDATION_INVALID_BODY. Consulta CHAT_RETRY_MESSAGE_NOT_FOUND, CHAT_RETRY_NO_USER_MESSAGE, RESOURCE_NOT_FOUND e INTERNAL_SERVER_ERROR en el catálogo de errores.

Enviar un resultado de herramienta

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

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

Autenticación: Clave de API bearer con acceso a {agentId}.

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

Respuesta: Una acción pendiente coincidente se reclama una sola vez y la continuación se devuelve como text/event-stream. Las llamadas desconocidas o caducadas devuelven 404; los resultados en conflicto devuelven 409.

Establecer o borrar los comentarios de un mensaje

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

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

Autenticación: Clave de API bearer con acceso a {agentId}. La conversación debe ser una conversación de la API v2.

{messageId} debe convertirse en un entero positivo y debe identificar un mensaje del asistente de IA en la conversación 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"}'

Éxito: 200 OK

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

El JSON con formato incorrecto devuelve 400 VALIDATION_INVALID_JSON; un cuerpo inválido devuelve 400 VALIDATION_INVALID_BODY; una conversación faltante devuelve 404 RESOURCE_NOT_FOUND; un mensaje faltante devuelve 404 RESOURCE_MESSAGE_NOT_FOUND; y un objetivo que no es un mensaje del asistente de IA devuelve 422 RESOURCE_MESSAGE_NOT_ASSISTANT.

Listar conversaciones de un usuario

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

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

Autenticación: Clave de API bearer con acceso a {agentId}.

{userId} debe tener de 1 a 128 caracteres y solo puede contener letras, números, ., _ y -.

Solo el chat de la API v2 escribe userId, por lo que este endpoint solo devuelve conversaciones de la API v2. Su respuesta de éxito usa el mismo envoltorio paginado de resumen de conversación que Listar conversaciones.

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

Éxito: 200 OK. Los ID de usuario, límites, cursores o usos de source inválidos devuelven 400 VALIDATION_INVALID_BODY.

Referencia relacionada

• Descripción general y chat de la API v2
• Catálogo de errores de la API v2
• Contactos e identidad verificada