Leer conversaciones

Cada mensaje que envías con la API queda registrado en una conversación. Estos endpoints te dejan leer ese historial: listar las conversaciones de tu cuenta y abrir cualquiera de ellas para ver todos sus mensajes. Son de solo lectura — no modifican nada.

Autenticación

Todas las peticiones se autentican con tu API key pública en la cabecera X-API-Key. Solo puedes ver las conversaciones de tu propia cuenta.

Listar conversaciones

Ruta base: /v1/public/v1/conversations

Método	Ruta	Propósito
GET	/conversations	Listar las conversaciones recientes.

Parámetros de consulta

Parámetro	Tipo	Por defecto	Descripción
limit	entero	20	Cuántas conversaciones devolver. Entre 1 y 100.
status	string	—	Filtra por estado, por ejemplo active o closed.

Petición

GET /v1/public/v1/conversations?limit=20&status=active
X-API-Key: <tu-api-key>

Respuesta (200 OK)

[
  {
    "id": "a3f1c2e0-1b2c-4d5e-8f90-1a2b3c4d5e6f",
    "user_ref": "cliente@example.com",
    "status": "active",
    "message_count": 4,
    "started_at": "2026-07-29T12:30:00Z",
    "last_message_at": "2026-07-29T12:34:56Z"
  }
]

Campo	Tipo	Descripción
id	UUID	Id único de la conversación. Úsalo para leer su detalle.
user_ref	string	La referencia que pasaste como user_ref, o una generada automáticamente.
status	string	Estado de la conversación, por ejemplo active o closed.
message_count	entero	Total de mensajes intercambiados.
started_at	fecha-hora	Cuándo se creó la conversación (ISO-8601, UTC).
last_message_at	fecha-hora	Fecha del último mensaje, si lo hay.

Leer una conversación

Método	Ruta	Propósito
GET	/conversations/{id}	Recuperar una conversación con todos sus mensajes.

Devuelve los mismos campos que el resumen anterior más messages, con el historial de la conversación (hasta los 200 mensajes más recientes).

Petición

GET /v1/public/v1/conversations/a3f1c2e0-1b2c-4d5e-8f90-1a2b3c4d5e6f
X-API-Key: <tu-api-key>

Respuesta (200 OK)

{
  "id": "a3f1c2e0-1b2c-4d5e-8f90-1a2b3c4d5e6f",
  "user_ref": "cliente@example.com",
  "status": "active",
  "message_count": 4,
  "started_at": "2026-07-29T12:30:00Z",
  "last_message_at": "2026-07-29T12:34:56Z",
  "messages": [
    { "role": "user", "content": "¿Cuál es el horario?", "created_at": "2026-07-29T12:30:00Z" },
    { "role": "assistant", "content": "Atendemos de lunes a viernes de 9 a 18h.", "created_at": "2026-07-29T12:30:02Z" }
  ]
}

Cada elemento de messages tiene role (user o assistant), content y created_at.

Errores

Código	Significado
401	Falta la cabecera X-API-Key o la clave no es válida.
403	Tu plan no incluye acceso a la API pública.
404	La conversación no existe o no pertenece a tu cuenta.