Guías por recurso
Leads
Listar, filtrar y actualizar tus leads, añadir notas, pasar una conversación a una persona y enlazar cada lead con tu CRM.
Un lead es una persona con la que habla tu setter IA. La API expone la misma ficha que la pestaña Leads del dashboard: etapa (status), etiquetas (tags), responsable, próxima acción, resultado comercial y notas.
Endpoints
Sección titulada «Endpoints»| Método | Ruta | Scope |
|---|---|---|
| GET | /leads |
leads:read |
| GET | /leads/{id} |
leads:read |
| PATCH | /leads/{id} |
leads:write |
| GET | /leads/{id}/notes |
leads:read |
| POST | /leads/{id}/notes |
leads:write |
| POST | /leads/{id}/handoff |
leads:write |
| POST | /leads/{id}/resume |
leads:write |
Lo que cambia lo que hace el agente
Sección titulada «Lo que cambia lo que hace el agente»Un lead lleva una etapa (status) y etiquetas (tags). Solo la etapa guía
al agente.
| Campo | Efecto en el agente |
|---|---|
status |
La etapa con la que trabaja el agente. La pone él mismo, según lo que dice su prompt, y respeta una etapa puesta por una persona o por tus herramientas: qualified, deja de cualificar; not_interested y stopped, ya no escribe; cold, deja de insistir; in_progress, retoma. |
tags |
Ninguno. Una etiqueta nunca detiene al agente, nunca cualifica un lead y nunca le hace proponer una cita. Las etiquetas sirven para ordenar: filtros, exportación, avisos, seguimientos limitados a algunas etiquetas, tu CRM. |
handoff, resume |
Detienen al agente en este lead, y luego lo dejan responder de nuevo. Mira más abajo. |
Una etiqueta con el nombre de una etapa, por ejemplo "qualified" en tags,
no cualifica al lead: envía "status": "qualified". Para cambiar cuándo el
agente cualifica sus leads por sí solo, edita su prompt: mira
Decidir cuándo un lead está cualificado.
Listar y filtrar leads
Sección titulada «Listar y filtrar leads»Los leads llegan del más recientemente activo al más antiguo, 25 por página por defecto.
curl "https://app.whatsetter.com/api/v1/leads?status=qualified&campaign_id=acme-espana-1-ab12&limit=25" \ -H "Authorization: Bearer ws_live_…"const res = await fetch( 'https://app.whatsetter.com/api/v1/leads?status=qualified&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/leads", params={"status": "qualified", "campaign_id": "acme-espana-1-ab12", "limit": 25}, headers={"Authorization": "Bearer ws_live_…"},)data = r.json()["data"]{ "data": [ { "id": "66f1a2b3c4d5e6f7a8b9c0d1", "phone": "34612345678", "whatsapp_id": "34612345678@c.us", "name": "Julien", "status": "qualified", "qualified": true, "qualified_at": "2026-09-12T10:04:31.000Z", "replied": true, "campaign_id": "acme-espana-1-ab12", "list_id": null, "channel": "whatsapp", "ig_username": null, "external_reference": "4471", "source": "api", "source_confidence": null, "tracked_link_id": null, "email": "julien@example.com", "tags": ["hot", "demo"], "messages_count": 14, "booking_status": "booked", "first_contact_at": "2026-09-10T08:00:12.000Z", "last_message_at": "2026-09-18T16:42:05.000Z", "last_message_direction": "inbound", "assigned_to": "66a1b2c3d4e5f6a7b8c9d0e1", "stage": "booked", "deal_status": "open", "lost_reason": null, "next_action_at": "2026-09-22T09:00:00.000Z", "next_action_label": "Volver a llamar", "created_at": "2026-09-10T07:59:58.000Z", "updated_at": "2026-09-18T16:42:05.000Z" } ], "pagination": { "has_more": true, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0d1" }}phone son solo dígitos, sin el +. Pasa cursor=next_cursor para obtener la página siguiente.
Filtros
Sección titulada «Filtros»| Parámetro | Qué hace |
|---|---|
status |
Uno de los estados de abajo. qualified devuelve todos los leads calificados en algún momento (su fecha de calificación está rellena). |
campaign_id |
El slug campaign_id de la campaña o su id, ambos vienen de GET /campaigns. |
phone |
Búsqueda exacta, formato internacional (+34612345678). |
external_reference |
Búsqueda exacta sobre el identificador que enviaste con POST /campaigns/{id}/leads. |
source |
De dónde viene el lead: instagram, facebook, tiktok, youtube, linkedin, x, snapchat, pinterest, google, website, email, sms, qr, ads, other, direct, list, api, webhook, inbound, manual, messenger (escribió a una página de Facebook en Messenger). |
tracked_link_id |
Solo los leads traídos por este enlace rastreado. |
channel |
whatsapp, instagram o facebook (Messenger, a través de una página de Facebook). |
since |
Solo los leads activos después de esta fecha ISO 8601 (sobre last_message_at). |
limit, cursor |
Paginación, de 1 a 100 por página. |
Valores de estado
Sección titulada «Valores de estado»status |
Significado |
|---|---|
queued |
Importado, esperando su primer mensaje. |
pending |
Aún sin contactar: el primer mensaje del lead se retuvo y nunca salió. No hay conversación, y nadie tiene que hacer nada. |
in_progress |
La conversación está en marcha. |
qualified |
El agente validó el interés, o lo fijaste desde la API. |
not_interested |
Perfil equivocado o rechazo explícito. |
cold |
El agente escribió primero y el lead aún no ha respondido. Con su primera respuesta, pasa a in_progress. También se pone cuando una persona marca el lead sin respuesta. |
stopped |
La conversación se detuvo. |
unknown |
Un valor interno que la API pública no nombra. |
Leer un lead
Sección titulada «Leer un lead»curl "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1" \ -H "Authorization: Bearer ws_live_…"const res = await fetch('https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1', { headers: { Authorization: 'Bearer ws_live_…' },});const { data: lead } = await res.json();import requests
r = requests.get( "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1", headers={"Authorization": "Bearer ws_live_…"},)lead = r.json()["data"]La respuesta es { "data": lead } con el mismo objeto de arriba. Un lead de otro espacio de trabajo responde 404, nunca 403.
Actualizar un lead
Sección titulada «Actualizar un lead»Envía solo los campos que cambias. Se necesita al menos uno.
curl -X PATCH "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1" \ -H "Authorization: Bearer ws_live_…" \ -H "Content-Type: application/json" \ -d '{ "status": "qualified", "tags": ["hot", "demo"], "assigned_to": "66a1b2c3d4e5f6a7b8c9d0e1", "next_action_at": "2026-09-22T09:00:00.000Z", "next_action_label": "Volver a llamar" }'const res = await fetch('https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1', { method: 'PATCH', headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' }, body: JSON.stringify({ status: 'qualified', tags: ['hot', 'demo'], assigned_to: '66a1b2c3d4e5f6a7b8c9d0e1', next_action_at: '2026-09-22T09:00:00.000Z', next_action_label: 'Volver a llamar', }),});const { data: lead } = await res.json();import requests
r = requests.patch( "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1", headers={"Authorization": "Bearer ws_live_…"}, json={ "status": "qualified", "tags": ["hot", "demo"], "assigned_to": "66a1b2c3d4e5f6a7b8c9d0e1", "next_action_at": "2026-09-22T09:00:00.000Z", "next_action_label": "Volver a llamar", },)lead = r.json()["data"]La respuesta es el lead actualizado, 200.
| Campo | Reglas |
|---|---|
status |
qualified, in_progress, not_interested, cold, pending, stopped o queued. Fijar qualified rellena qualified_at una sola vez. |
tags |
Array de hasta 20 cadenas, 40 caracteres cada una. Sustituye toda la lista. Las etiquetas vacías o demasiado largas se descartan, los duplicados se eliminan. Nunca cambia lo que hace el agente: mira las etiquetas del agente más abajo. |
assigned_to |
Un id de miembro de GET /team/members, o null para quitar el responsable. Id desconocido: 422. |
next_action_at |
Fecha ISO 8601, o null. |
next_action_label |
Hasta 80 caracteres, o null. Necesita una fecha next_action_at (422 si falta). Borrar la fecha borra el texto. |
deal_status |
open, won o lost. |
lost_reason |
Uno de price, timing, unqualified, competitor, unreachable, other. Obligatorio con deal_status: "lost", se borra con open y won. |
Cada cambio escribe el historial del lead, los mismos eventos que escribe el dashboard (owner, next_action, outcome), con el nombre de tu clave API como autor.
tags y las etiquetas del agente
Sección titulada «tags y las etiquetas del agente»Cuando el agente del lead tiene sus etiquetas activadas, pone él mismo
algunas etiquetas (mira Etiquetas del agente).
tags las contiene junto con las que ponen las personas. Un PATCH con
tags cuenta como un cambio a mano, como en el dashboard:
- quitar una de las etiquetas del agente, o añadir una de sus etiquetas, pasa las etiquetas de este lead a las personas: el agente deja de cambiarlas. Devuélveselas en el dashboard con Devolver al agente;
- una etiqueta tuya, como
"VIP", no cambia nada para el agente; - el nombre de una de las etiquetas del agente se guarda con la ortografía del agente, sea cual sea la mayúscula que envíes. Con Una etiqueta principal, la etiqueta principal que añades sustituye a la anterior del lead.
Si no se pueden leer los ajustes de etiquetas del agente, la llamada responde
503 tag_rules_unavailable y no se escribe nada: inténtalo de nuevo en un
momento.
Las notas son los textos libres que tu equipo ve en la ficha del lead.
curl -X POST "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/notes" \ -H "Authorization: Bearer ws_live_…" \ -H "Content-Type: application/json" \ -d '{"text":"Le devolví la llamada, quiere un presupuesto antes del viernes."}'const res = await fetch('https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/notes', { method: 'POST', headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' }, body: JSON.stringify({ text: 'Le devolví la llamada, quiere un presupuesto antes del viernes.' }),});const { data: note } = await res.json();import requests
r = requests.post( "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/notes", headers={"Authorization": "Bearer ws_live_…"}, json={"text": "Le devolví la llamada, quiere un presupuesto antes del viernes."},)note = r.json()["data"]{ "data": { "id": "66f1a2b3c4d5e6f7a8b9c0e2", "text": "Le devolví la llamada, quiere un presupuesto antes del viernes.", "author": "API · Mi CRM", "created_at": "2026-09-19T08:12:00.000Z" }}text tiene de 1 a 2000 caracteres. El autor es API · <nombre de la clave> para las notas que creas, o el nombre del compañero para las notas escritas en el dashboard. GET /leads/{id}/notes devuelve { "data": [ ...notas ] }, las más recientes primero, hasta 100.
Pasar una conversación a una persona y devolverla
Sección titulada «Pasar una conversación a una persona y devolverla»POST /leads/{id}/handoff detiene al agente IA en este lead. Se queda en silencio hasta que llames a POST /leads/{id}/resume. Es el mismo interruptor que la toma de control del dashboard, así que los dos nunca se contradicen.
curl -X POST "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/handoff" \ -H "Authorization: Bearer ws_live_…"const res = await fetch('https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/handoff', { method: 'POST', headers: { Authorization: 'Bearer ws_live_…' },});const { data: control } = await res.json();import requests
r = requests.post( "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/handoff", headers={"Authorization": "Bearer ws_live_…"},)control = r.json()["data"]{ "data": { "id": "66f1a2b3c4d5e6f7a8b9c0d1", "external_reference": "4471", "agent_active": false, "manual_override": true, "status": "in_progress", "dashboard_synced": true, "updated_at": "2026-09-19T08:12:00.000Z" }}- El
statusdel lead se conserva: tomar el control nunca marca un lead como detenido o calificado. - Las dos llamadas son idempotentes: un segundo handoff sobre un lead ya tomado responde
200. dashboard_synced: falsesignifica que el agente está detenido pero la lista de Leads puede ir con retraso. La vista de conversación siempre es correcta.- La regla de estado: handoff y resume solo se aplican a leads con los que el agente ya ha hablado (
in_progress,stopped,cold,qualified,not_interested). Un leadqueuedopendingno tiene conversación que pasar y responde409 invalid_state. - En Instagram y Messenger el interruptor se escribe en el propio lead, donde lo leen sus motores, igual que Tomar el control en el dashboard.
resumetambién termina la pausa abierta por la respuesta de una persona (agent_paused_untilenGET /conversations).
El campo stage
Sección titulada «El campo stage»stage es de solo lectura y se deriva del lead exactamente como el embudo del dashboard. Responde en una palabra a «¿dónde está esta persona comercialmente?», mientras que status es el vocabulario propio de la IA.
stage |
Cuándo |
|---|---|
contacted |
Aún sin respuesta contada, y no cold: por ejemplo una persona que escribió primero y aún no tiene respuesta. |
conversation |
El lead respondió, la IA o una persona le está hablando. |
waiting |
Aún sin contactar: el primer mensaje se retuvo y nunca salió (status: pending). |
qualified |
Interés validado (status: qualified). |
booked |
Hay una reunión en el calendario, o ya se celebró. Gana a cualquier otro valor. |
not_interested |
Perfil equivocado o rechazo. |
cold |
El agente escribió primero, aún sin respuesta (status: cold). |
stopped |
La conversación se detuvo. |
Enlazar con tu CRM
Sección titulada «Enlazar con tu CRM»Envía el identificador de tu propia ficha en external_reference cuando empujes un lead opt-in con POST /campaigns/{id}/leads. WhatSetter lo guarda tal cual, lo devuelve en cada lead y cada webhook, y te deja buscarlo:
curl "https://app.whatsetter.com/api/v1/leads?external_reference=4471" \ -H "Authorization: Bearer ws_live_…"external_reference es null para los leads que no vienen de ti (importaciones CSV, importaciones de lista, formularios de página de venta). Para esos, compara por phone: solo dígitos en ambos lados.
Errores que encontrarás
Sección titulada «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 leads:read o leads:write. |
| 404 | not_found |
Lead desconocido, o lead de otro espacio de trabajo. |
| 409 | invalid_state |
Handoff o resume sobre un lead nunca contactado. |
| 422 | validation_error |
Estado desconocido, teléfono inválido, id de miembro desconocido, cuerpo vacío, cursor inválido o caducado. |
| 503 | tag_rules_unavailable |
Un cambio de tags mientras no se podían leer los ajustes de etiquetas del agente. No se escribió nada. Puedes reintentar. |
| 429 | rate_limited |
Demasiadas peticiones este minuto. Respeta Retry-After. |
| 502 | upstream_error |
El flujo de control del agente no estaba disponible. Puedes reintentar. |