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

# Listar Conversaciones

> Obtén todas las conversaciones con filtros y paginación

## Parámetros de Query

<ParamField query="status" type="string" default="all">
  Filtrar por estado: `all`, `active`, `closed`, `archived`
</ParamField>

<ParamField query="search" type="string">
  Buscar por nombre de contacto, teléfono o email
</ParamField>

<ParamField query="limit" type="number" default="20">
  Número de resultados (máximo 100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Offset para paginación
</ParamField>

<ParamField query="filters" type="string">
  Filtros avanzados en formato JSON (ver ejemplos abajo)
</ParamField>

## Filtros avanzados

El parámetro `filters` acepta un JSON URL-encoded con las siguientes opciones:

```json theme={null}
{
  "statusFilter": "unread",        // unread, ai-paused, ai-active, needs-attention
  "stageId": "uuid",               // Etapa del funnel
  "tags": ["vip", "nuevo"],        // Tags del contacto (OR)
  "assignedTo": "me",              // "me", "none", o UUID de agente
  "updatedFilter": "today",        // today, week, month
  "inactiveDays": 7                // Días sin actividad
}
```

| Filtro          | Valores                                               | Descripción                  |
| --------------- | ----------------------------------------------------- | ---------------------------- |
| `statusFilter`  | `unread`, `ai-paused`, `ai-active`, `needs-attention` | Estado de la conversación    |
| `stageId`       | UUID                                                  | Etapa del funnel de ventas   |
| `tags`          | Array de strings                                      | Tags del contacto (match OR) |
| `assignedTo`    | `me`, `none`, UUID                                    | Asignación del agente        |
| `updatedFilter` | `today`, `week`, `month`                              | Filtro de tiempo             |
| `inactiveDays`  | 1-365                                                 | Días de inactividad          |

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.whaapy.com/conversations/v1?status=active&limit=10" \
    -H "Authorization: Bearer wha_xxxxx"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.whaapy.com/conversations/v1?status=active&limit=10',
    {
      headers: {
        'Authorization': 'Bearer wha_xxxxx'
      }
    }
  );
  const data = await response.json();
  ```

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

  response = requests.get(
      'https://api.whaapy.com/conversations/v1',
      params={'status': 'active', 'limit': 10},
      headers={'Authorization': 'Bearer wha_xxxxx'}
  )
  data = response.json()
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.whaapy.com/conversations/v1?status=active&limit=10",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer wha_xxxxx"
    ],
  ]);

  $response = curl_exec($curl);
  $data = json_decode($response, true);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "phoneNumber": "+5215512345678",
        "contactName": "Juan Pérez",
        "profilePictureUrl": "https://...",
        "lastMessageAt": "2026-01-29T10:30:00Z",
        "lastMessagePreview": "Hola, ¿tienen disponibilidad?",
        "unreadCount": 2,
        "status": "active",
        "contact": {
          "id": "uuid",
          "name": "Juan Pérez",
          "email": "juan@ejemplo.com",
          "tags": ["cliente-nuevo"],
          "funnelStage": {
            "id": "uuid",
            "name": "Interesado",
            "color": "#3B82F6"
          }
        },
        "settings": {
          "aiEnabled": true,
          "aiPausedUntil": null
        },
        "assignedTo": {
          "agentId": "uuid",
          "agentName": "María García"
        },
        "createdAt": "2026-01-28T08:00:00Z"
      }
    ],
    "meta": {
      "total": 150,
      "limit": 10,
      "offset": 0,
      "hasMore": true
    }
  }
  ```
</ResponseExample>

## Campos de respuesta

| Campo                | Tipo    | Descripción                                |
| -------------------- | ------- | ------------------------------------------ |
| `id`                 | string  | UUID de la conversación                    |
| `phoneNumber`        | string  | Número de WhatsApp del contacto            |
| `contactName`        | string  | Nombre del contacto                        |
| `lastMessageAt`      | string  | Fecha del último mensaje (ISO 8601)        |
| `lastMessagePreview` | string  | Preview del último mensaje (truncado)      |
| `unreadCount`        | number  | Mensajes no leídos                         |
| `status`             | string  | Estado: `active`, `closed`, `archived`     |
| `contact`            | object  | Datos del contacto asociado                |
| `settings`           | object  | Configuración de IA para esta conversación |
| `assignedTo`         | object  | Agente asignado (si aplica)                |
| `meta.total`         | number  | Total de conversaciones que coinciden      |
| `meta.hasMore`       | boolean | Si hay más páginas disponibles             |

<Tip>
  Usa `filters` con `assignedTo: "none"` para encontrar conversaciones sin asignar que necesitan atención.
</Tip>

## Errores comunes

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Missing API Key",
    "message": "Authorization header required. Format: \"Bearer wha_xxxxx\""
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 403 Forbidden theme={null}
  {
    "error": "Insufficient permissions",
    "message": "This API Key does not have the required scope: conversations:read"
  }
  ```
</ResponseExample>