Ir al contenido
Dashboard

Guías por recurso

Conversaciones

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

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.

Método Ruta Scope
GET /conversations conversations:read
GET /conversations/{leadId}/messages conversations:read

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

Terminal window
curl "https://app.whatsetter.com/api/v1/conversations?campaign_id=acme-espana-1-ab12&limit=25" \
-H "Authorization: Bearer ws_live_…"
{
"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

Sección titulada «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).
agent_active El agente responde a esta conversación ahora. false tras tomar el control, 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.

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

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

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.

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

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.