> ## Documentation Index
> Fetch the complete documentation index at: https://docs.horneross.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtener mensajes

> Obtener los mensajes de una conversación específica con paginación.

## Endpoint

```
GET /api/v2/conversations/{id}/messages
```

## Path Parameters

<ParamField path="id" type="string" required>
  ID de la conversación
</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token con tu API key de organización.
</ParamField>

<ParamField header="X-Visitor-Id" type="string">
  Alternativa al query param `visitorId` para identificar al visitante.
</ParamField>

## Query Parameters

<ParamField query="limit" type="number" default="100">
  Mensajes por página. Máximo recomendado: 100.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Número de mensajes a saltar para paginación.
</ParamField>

<ParamField query="before" type="string">
  ID del mensaje para scroll infinito hacia arriba. Obtiene mensajes anteriores a este ID.
</ParamField>

<ParamField query="visitorId" type="string">
  ID del visitante (requerido para agentes públicos sin autenticación).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.horneross.com/api/v2/conversations/conv_abc123/messages?limit=50" \
    -H "Authorization: Bearer sk_live_xxx"
  ```

  ```javascript JavaScript theme={null}
  async function getMessages(conversationId, options = {}) {
    const params = new URLSearchParams(options);
    const response = await fetch(
      `https://app.horneross.com/api/v2/conversations/${conversationId}/messages?${params}`,
      {
        headers: {
          'Authorization': 'Bearer sk_live_xxx',
        },
      }
    );
    return response.json();
  }

  const result = await getMessages('conv_abc123', { limit: 50 });

  for (const msg of result.messages) {
    console.log(`[${msg.role}] ${msg.content}`);
  }
  ```

  ```python Python theme={null}
  import requests

  def get_messages(conversation_id, limit=100, offset=0):
      response = requests.get(
          f'https://app.horneross.com/api/v2/conversations/{conversation_id}/messages',
          headers={'Authorization': 'Bearer sk_live_xxx'},
          params={'limit': limit, 'offset': offset}
      )
      return response.json()

  result = get_messages('conv_abc123', limit=50)
  for msg in result['messages']:
      print(f"[{msg['role']}] {msg['content']}")
  ```
</RequestExample>

## Response

<ResponseField name="messages" type="array" required>
  Array de mensajes

  <Expandable title="Propiedades de cada mensaje">
    <ResponseField name="messages[].id" type="string" required>
      ID único del mensaje
    </ResponseField>

    <ResponseField name="messages[].role" type="string" required>
      Rol del mensaje: `user`, `assistant`, `system`
    </ResponseField>

    <ResponseField name="messages[].content" type="string" required>
      Contenido del mensaje
    </ResponseField>

    <ResponseField name="messages[].from" type="string" required>
      Origen: `human`, `agent`, `system`
    </ResponseField>

    <ResponseField name="messages[].type" type="string" required>
      Tipo: `TEXT`, `ACTION`, `TOOL_CALL`
    </ResponseField>

    <ResponseField name="messages[].eval" type="string">
      Evaluación del mensaje: `good`, `bad`, o `null`
    </ResponseField>

    <ResponseField name="messages[].metadata" type="object">
      Metadata adicional del mensaje
    </ResponseField>

    <ResponseField name="messages[].attachments" type="array">
      Archivos adjuntos

      <Expandable title="Propiedades de attachment">
        <ResponseField name="messages[].attachments[].name" type="string">
          Nombre del archivo
        </ResponseField>

        <ResponseField name="messages[].attachments[].url" type="string">
          URL del archivo
        </ResponseField>

        <ResponseField name="messages[].attachments[].size" type="number">
          Tamaño en bytes
        </ResponseField>

        <ResponseField name="messages[].attachments[].mimeType" type="string">
          MIME type del archivo
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messages[].createdAt" type="string">
      Fecha de creación (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conversation" type="object">
  Información de la conversación

  <Expandable title="Propiedades de conversation">
    <ResponseField name="conversation.id" type="string">
      ID de la conversación
    </ResponseField>

    <ResponseField name="conversation.title" type="string">
      Título
    </ResponseField>

    <ResponseField name="conversation.channel" type="string">
      Canal de origen
    </ResponseField>

    <ResponseField name="conversation.status" type="string">
      Estado actual
    </ResponseField>

    <ResponseField name="conversation.agentId" type="string">
      ID del agente
    </ResponseField>

    <ResponseField name="conversation.agent" type="object">
      Información del agente incluyendo configuración actual
    </ResponseField>

    <ResponseField name="conversation.metadata" type="object">
      Metadata de la conversación
    </ResponseField>

    <ResponseField name="conversation.createdAt" type="string">
      Fecha de creación
    </ResponseField>

    <ResponseField name="conversation.updatedAt" type="string">
      Última actualización
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Información de paginación

  <Expandable title="Propiedades de pagination">
    <ResponseField name="pagination.limit" type="number">
      Límite por página
    </ResponseField>

    <ResponseField name="pagination.offset" type="number">
      Offset actual
    </ResponseField>

    <ResponseField name="pagination.total" type="number">
      Total de mensajes en la conversación
    </ResponseField>

    <ResponseField name="pagination.hasMore" type="boolean">
      Si hay más mensajes disponibles
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "messages": [
      {
        "id": "msg_001",
        "role": "user",
        "content": "Hola, necesito ayuda con mi pedido",
        "from": "human",
        "type": "TEXT",
        "eval": null,
        "createdAt": "2024-01-21T10:00:00Z"
      },
      {
        "id": "msg_002",
        "role": "assistant",
        "content": "¡Hola! Con gusto te ayudo. ¿Podrías darme el número de pedido?",
        "from": "agent",
        "type": "TEXT",
        "eval": "good",
        "metadata": {
          "model": "gpt-4o",
          "sources": ["FAQ Pedidos"]
        },
        "createdAt": "2024-01-21T10:00:05Z"
      },
      {
        "id": "msg_003",
        "role": "user",
        "content": "Mi pedido es #12345",
        "from": "human",
        "type": "TEXT",
        "attachments": [
          {
            "name": "captura.png",
            "url": "https://storage.horneross.com/files/captura.png",
            "size": 45000,
            "mimeType": "image/png"
          }
        ],
        "createdAt": "2024-01-21T10:01:00Z"
      }
    ],
    "conversation": {
      "id": "conv_abc123",
      "title": "Consulta de pedido",
      "channel": "website",
      "status": "UNRESOLVED",
      "agentId": "ag_xyz789",
      "agent": {
        "id": "ag_xyz789",
        "name": "Agente de Soporte",
        "iconUrl": "https://storage.horneross.com/icons/support.png",
        "description": "Agente especializado en soporte",
        "currentVersion": {
          "id": "ver_001",
          "modelName": "gpt-4o",
          "temperature": 0.7
        }
      },
      "metadata": {},
      "createdAt": "2024-01-21T10:00:00Z",
      "updatedAt": "2024-01-21T10:01:00Z"
    },
    "pagination": {
      "limit": 100,
      "offset": 0,
      "total": 3,
      "hasMore": false
    }
  }
  ```

  ```json 403 - Organization Mismatch theme={null}
  {
    "error": "conversation_org_mismatch"
  }
  ```
</ResponseExample>