# Conversaciones

> Leer tu bandeja de entrada y la transcripción completa de un lead, paginar los mensajes y tratar los datos personales que contienen.

Source: https://docs.whatsetter.com/es/developers/guides/conversations/

Una conversación es el hilo entre tu agente y un lead. La API te da la bandeja de entrada (los leads con actividad) y la transcripción de cada lead, en solo lectura.

## Endpoints

| Método | Ruta | Scope |
|---|---|---|
| GET | [`/conversations`](/api-reference/operations/listconversations/) | `conversations:read` |
| GET | [`/conversations/{leadId}/messages`](/api-reference/operations/listconversationmessages/) | `conversations:read` |

## Listar conversaciones

La bandeja de entrada: cada lead que intercambió al menos un mensaje, actividad más reciente primero.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/conversations?campaign_id=acme-espana-1-ab12&limit=25" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/conversations?campaign_id=acme-espana-1-ab12&limit=25',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/conversations",
    params={"campaign_id": "acme-espana-1-ab12", "limit": 25},
    headers={"Authorization": "Bearer ws_live_…"},
)
data = r.json()["data"]
```

```json
{
  "data": [
    {
      "lead_id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "phone": "34612345678",
      "whatsapp_id": "34612345678@c.us",
      "name": "Julien",
      "status": "in_progress",
      "qualified": false,
      "replied": true,
      "campaign_id": "acme-espana-1-ab12",
      "messages_count": 6,
      "last_message_at": "2026-09-18T16:42:05.000Z",
      "last_message_direction": "inbound"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0d1" }
}
```

`campaign_id` acepta el slug de la campaña o su `id`. Sin él, las conversaciones de las campañas de grupo quedan fuera, igual que en el dashboard. `last_message_direction: "inbound"` significa que el lead habló el último.

### Canales, quién responde, qué espera una respuesta

La bandeja de entrada cubre WhatsApp, Instagram y Messenger. Cada conversación dice además:

| Campo | Significado |
|---|---|
| `channel` | `whatsapp`, `instagram` o `facebook` (Messenger). En Instagram y Messenger `phone` y `whatsapp_id` son `null`. |
| `ig_username`, `account_id` | Instagram: el usuario de la persona, y la cuenta en la que vive el hilo ([`GET /instagram/accounts`](/es/developers/guides/instagram/)). |
| `agent_active` | El agente responde a esta conversación ahora. `false` tras [tomar el control](/es/developers/guides/leads/), o mientras la respuesta de una persona lo pone en pausa (`agent_paused_until`). |
| `needs_reply` | Una persona le debe una respuesta: la vista **Pendientes** del dashboard. Un mensaje sin respuesta (enviado en las últimas 48 horas, sin respuesta tras 30 minutos), o una siguiente acción atrasada. |
| `triage_verdict` | Instagram y Messenger, cuando el agente responde a todos los mensajes privados: lo que leyó la clasificación (**Lo que el agente deja de lado** en el dashboard) en el último mensaje. `collab` y `support` se te dejan a ti; `personal`, `spam`, `friend`, `no_text` y `blocked` no reciben respuesta. |

Filtra con `channel=instagram`, `needs_reply=true` (solo las conversaciones que te esperan) o `triage=collab`. Para responder, [`POST /messages`](/es/developers/guides/messages/#instagram-y-messenger).

## Leer los mensajes de un lead

`leadId` es el `id` del lead que viene de `/leads` o `/conversations`. Los mensajes llegan del más reciente al más antiguo.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/conversations/66f1a2b3c4d5e6f7a8b9c0d1/messages?limit=50" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/conversations/66f1a2b3c4d5e6f7a8b9c0d1/messages?limit=50',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data: messages, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/conversations/66f1a2b3c4d5e6f7a8b9c0d1/messages",
    params={"limit": 50},
    headers={"Authorization": "Bearer ws_live_…"},
)
messages = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e6",
      "direction": "inbound",
      "text": "Sí, a las 14h me va bien.",
      "type": "USER_MESSAGE",
      "variant": null,
      "has_media": false,
      "sent_at": "2026-09-18T16:42:05.000Z"
    },
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e5",
      "direction": "outbound",
      "text": "¿Confirmamos mañana a las 14h?",
      "type": "MANUAL_RESPONSE",
      "variant": null,
      "has_media": false,
      "sent_at": "2026-09-18T16:40:10.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0e5" }
}
```

| Campo | Significado |
|---|---|
| `direction` | `inbound` cuando escribió el lead, `outbound` cuando escribió el agente, un compañero o la API. |
| `text` | El texto del mensaje, o `null` para un mensaje que solo contiene un archivo. |
| `type` | Tipo de interacción interno, por ejemplo `USER_MESSAGE`, `AI_RESPONSE`, `LEAD_WELCOME`, `FOLLOWUP`, `MANUAL_RESPONSE`. Trata los valores desconocidos como opacos. |
| `variant` | La variante de prompt que escribió el mensaje, de `A` a `D`: el prompt de primer mensaje para un `LEAD_WELCOME`, el prompt de conversación para un `AI_RESPONSE`. `null` en los mensajes que ningún prompt escribió. Mira [Prompts de los agentes](/es/developers/guides/prompts/). |
| `has_media` | `true` cuando el mensaje llevaba una imagen, un audio o un documento. El archivo en sí nunca se enlaza. |
| `sent_at` | ISO 8601, UTC. |

## Paginación

Los dos endpoints devuelven `pagination.has_more` y `pagination.next_cursor`. Pasa `cursor=<next_cursor>` para la página siguiente; `limit` va de 1 a 100, 25 por defecto. Un cursor que apunta a una fila borrada responde `422 validation_error` con «Invalid or expired cursor»: vuelve a empezar desde la primera página.

Para sincronizar una bandeja de entrada, consulta `GET /conversations` y recupera solo la transcripción de los leads cuyo `last_message_at` haya cambiado. Para tiempo real, prefiere los [webhooks](/es/developers/webhooks/).

## Datos personales

Las transcripciones contienen números de teléfono, nombres y todo lo que la persona escribió. Trátalos como datos personales: guarda solo lo que tu caso de uso necesita, respeta tu política de retención y nunca los muestres a alguien que no podría abrir la bandeja de entrada de WhatSetter. `phone` son solo dígitos, sin el `+`.

## Errores que encontrarás

| HTTP | `code` | Cuándo |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clave ausente, desconocida o revocada. |
| 403 | `insufficient_scope` | La clave no tiene `conversations:read`. |
| 404 | `not_found` | Lead desconocido, o lead de otro espacio de trabajo. |
| 422 | `validation_error` | `limit` fuera de 1 a 100, cursor inválido o caducado. |
| 429 | `rate_limited` | Demasiadas peticiones este minuto. Respeta `Retry-After`. |

## Relacionado

- [Mensajes: responder a un lead](/es/developers/guides/messages/)
- [Leads](/es/developers/guides/leads/)
- [Conversaciones en el dashboard](/es/dashboard/conversations/)
- [Webhooks firmados](/es/developers/webhooks/)
