Conversaciones

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`	`conversations:read`
GET	`/conversations/{leadId}/messages`	`conversations:read`

Listar conversaciones

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

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

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();

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"]

{
  "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: es tu señal de «pendiente de respuesta».

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 "https://app.whatsetter.com/api/v1/conversations/66f1a2b3c4d5e6f7a8b9c0d1/messages?limit=50" \
  -H "Authorization: Bearer ws_live_…"

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();

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"]

{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e6",
      "direction": "inbound",
      "text": "Sí, a las 14h me va bien.",
      "type": "USER_MESSAGE",
      "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",
      "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.
`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.

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