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

# Listar conversaciones de leads — API REST de DeltaLead

> Obtener conversaciones de leads paginadas. Filtrar por ID de lead, canal o estado para ver hilos abiertos, auditar la IA o llevar el historial al CRM.

Permite recuperar todas las conversaciones que DeltaLead registra en cada canal conectado: WhatsApp, Facebook, Instagram, email y teléfono. Cada conversación se vincula a un lead y refleja el estado actual del intercambio: abierta, cerrada o transferida a un asesor humano. Al filtrar por ID de lead se obtiene el historial de conversación de un contacto puntual; al filtrar por estado se pueden monitorear todos los hilos abiertos que requieren atención.

## Endpoint

```text theme={null}
GET https://platform-api.deltalead.ai/v1/conversations
```

## Parámetros de consulta

<ParamField query="limit" type="integer" default="20">
  Cantidad máxima de conversaciones que se devuelven por página. Acepta valores entre `1` y `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor de paginación opaco, tomado del campo `pagination.next_cursor` de la respuesta anterior. Si se omite, la lectura empieza por la primera página.
</ParamField>

<ParamField query="lead_id" type="string">
  Limita las conversaciones a un lead determinado. Se pasa un ID de lead como `lead_abc123` para recuperar todos los hilos de conversación de ese contacto.
</ParamField>

<ParamField query="channel" type="string">
  Filtra por el canal en el que transcurre la conversación. Valores aceptados: `whatsapp`, `facebook`, `instagram`, `email`, `phone`.
</ParamField>

<ParamField query="status" type="string">
  Filtra por estado de la conversación. Valores aceptados: `open`, `closed`, `transferred`.
</ParamField>

## Solicitud de ejemplo

```bash cURL theme={null}
curl 'https://platform-api.deltalead.ai/v1/conversations?lead_id=lead_abc123&status=open' \
  -H "X-API-Key: YOUR_API_KEY"
```

## Respuesta

Una solicitud correcta devuelve `200 OK` con un arreglo `data` de objetos de conversación y un objeto `pagination`.

```json Example response theme={null}
{
  "data": [
    {
      "id": "conv_xyz789",
      "lead_id": "lead_abc123",
      "channel": "whatsapp",
      "status": "open",
      "created_at": "2024-03-10T14:22:05Z",
      "updated_at": "2024-03-11T09:05:33Z",
      "last_message_at": "2024-03-11T09:05:33Z"
    },
    {
      "id": "conv_mno321",
      "lead_id": "lead_abc123",
      "channel": "phone",
      "status": "closed",
      "created_at": "2024-03-09T11:00:00Z",
      "updated_at": "2024-03-09T11:08:42Z",
      "last_message_at": "2024-03-09T11:08:42Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}
```

### Campos de la respuesta

<ResponseField name="data" type="array">
  Arreglo de objetos de conversación que coinciden con los filtros aplicados.
</ResponseField>

<ResponseField name="data[].id" type="string">
  Identificador único de la conversación, con el prefijo `conv_`.
</ResponseField>

<ResponseField name="data[].lead_id" type="string">
  ID del lead al que pertenece la conversación.
</ResponseField>

<ResponseField name="data[].channel" type="string">
  Canal en el que transcurre la conversación. Uno de `whatsapp`, `facebook`, `instagram`, `email`, `phone`.
</ResponseField>

<ResponseField name="data[].status" type="string">
  Estado actual de la conversación. Uno de:

  * `open` — conversación activa, con un agente de IA o una persona interviniendo
  * `closed` — conversación finalizada, no se esperan más mensajes
  * `transferred` — derivada del agente de IA a un asesor de ventas humano
</ResponseField>

<ResponseField name="data[].created_at" type="string">
  Marca de tiempo ISO 8601 del momento en que se abrió la conversación.
</ResponseField>

<ResponseField name="data[].updated_at" type="string">
  Marca de tiempo ISO 8601 del cambio más reciente en el registro de la conversación.
</ResponseField>

<ResponseField name="data[].last_message_at" type="string">
  Marca de tiempo ISO 8601 del mensaje o evento más reciente de esta conversación.
</ResponseField>

<ResponseField name="pagination.total" type="integer">
  Cantidad total de conversaciones que coinciden con los filtros aplicados.
</ResponseField>

<ResponseField name="pagination.has_more" type="boolean">
  `true` si existen páginas adicionales.
</ResponseField>

<ResponseField name="pagination.next_cursor" type="string | null">
  Este valor se pasa como `cursor` para obtener la página siguiente. Es `null` cuando `has_more` es `false`.
</ResponseField>