> ## 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.

# Listar conversaciones

> Lista todas las conversaciones de tu organización con filtrado por canal y paginación.

## Endpoint

```
GET /api/v2/conversations
```

## Headers

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

## Query Parameters

<ParamField query="channel" type="string" default="all">
  Filtrar por canal. Valores: `api`, `website`, `whatsapp`, `widget`, `dashboard`, `agent_builder`, `instagram`, `telegram`, `all`
</ParamField>

<ParamField query="limit" type="number" default="20">
  Resultados por página. Máximo 100.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor para paginación. Usar el ID de la última conversación de la página anterior.
</ParamField>

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

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

  const result = await listConversations({
    channel: 'website',
    limit: 10
  });

  console.log(result.conversations);
  console.log('Has more:', result.pagination.hasMore);
  ```

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

  def list_conversations(channel='all', limit=20, cursor=None):
      params = {'channel': channel, 'limit': limit}
      if cursor:
          params['cursor'] = cursor

      response = requests.get(
          'https://app.horneross.com/api/v2/conversations',
          headers={'Authorization': 'Bearer sk_live_xxx'},
          params=params
      )
      return response.json()

  result = list_conversations(channel='website', limit=10)
  for conv in result['conversations']:
      print(f"{conv['id']}: {conv['title']}")
  ```
</RequestExample>

## Response

<ResponseField name="conversations" type="array" required>
  Array de conversaciones

  <Expandable title="Propiedades de cada conversación">
    <ResponseField name="conversations[].id" type="string" required>
      ID único de la conversación
    </ResponseField>

    <ResponseField name="conversations[].title" type="string">
      Título de la conversación
    </ResponseField>

    <ResponseField name="conversations[].channel" type="string" required>
      Canal de origen: `api`, `website`, `whatsapp`, `dashboard`, etc.
    </ResponseField>

    <ResponseField name="conversations[].status" type="string" required>
      Estado: `UNRESOLVED`, `RESOLVED`, `HUMAN_REQUESTED`
    </ResponseField>

    <ResponseField name="conversations[].agentId" type="string">
      ID del agente asociado
    </ResponseField>

    <ResponseField name="conversations[].messageCount" type="number">
      Cantidad de mensajes en la conversación
    </ResponseField>

    <ResponseField name="conversations[].agent" type="object">
      Datos del agente

      <Expandable title="Propiedades de agent">
        <ResponseField name="conversations[].agent.id" type="string">
          ID del agente
        </ResponseField>

        <ResponseField name="conversations[].agent.name" type="string">
          Nombre del agente
        </ResponseField>

        <ResponseField name="conversations[].agent.iconUrl" type="string">
          URL del icono del agente
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="conversations[].lastMessage" type="object">
      Último mensaje de la conversación

      <Expandable title="Propiedades de lastMessage">
        <ResponseField name="conversations[].lastMessage.id" type="string">
          ID del mensaje
        </ResponseField>

        <ResponseField name="conversations[].lastMessage.text" type="string">
          Contenido del mensaje
        </ResponseField>

        <ResponseField name="conversations[].lastMessage.from" type="string">
          Origen: `human` o `agent`
        </ResponseField>

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

    <ResponseField name="conversations[].metadata" type="object">
      Metadata personalizada de la conversación
    </ResponseField>

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

    <ResponseField name="conversations[].updatedAt" type="string">
      Última actualización (ISO 8601)
    </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 de resultados por página
    </ResponseField>

    <ResponseField name="pagination.cursor" type="string">
      Cursor para la siguiente página (null si no hay más)
    </ResponseField>

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

<ResponseField name="filters" type="object">
  Filtros aplicados

  <Expandable title="Propiedades de filters">
    <ResponseField name="filters.channel" type="string">
      Canal filtrado actual
    </ResponseField>

    <ResponseField name="filters.availableChannels" type="string[]">
      Lista de todos los canales disponibles
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "conversations": [
      {
        "id": "conv_abc123",
        "title": "Consulta sobre productos",
        "channel": "website",
        "status": "UNRESOLVED",
        "agentId": "ag_xyz789",
        "messageCount": 8,
        "agent": {
          "id": "ag_xyz789",
          "name": "Agente de Ventas",
          "iconUrl": "https://storage.horneross.com/icons/agent.png"
        },
        "lastMessage": {
          "id": "msg_001",
          "text": "Gracias por la información",
          "from": "human",
          "createdAt": "2024-01-21T15:30:00Z"
        },
        "metadata": {
          "source": "landing_page"
        },
        "createdAt": "2024-01-21T10:00:00Z",
        "updatedAt": "2024-01-21T15:30:00Z"
      }
    ],
    "pagination": {
      "limit": 20,
      "cursor": "conv_abc123",
      "hasMore": true
    },
    "filters": {
      "channel": "all",
      "availableChannels": ["website", "whatsapp", "api", "dashboard", "agent_builder"]
    }
  }
  ```

  ```json 400 - Invalid Channel theme={null}
  {
    "error": "invalid_channel",
    "validChannels": ["api", "website", "whatsapp", "dashboard", "agent_builder", "instagram", "telegram"]
  }
  ```
</ResponseExample>