Inicio rápido

Cinco peticiones, en cURL, JavaScript y Python. Al final tienes una clave, una lista de contactos y un webhook que te avisa cuando un lead queda calificado.

Antes de empezar

• Eres propietario o admin de tu espacio de WhatSetter. La página de la API lo dice: Solo los propietarios y admins pueden gestionar las claves API.
• Tienes curl, Node.js 18 o más reciente, o Python 3 con requests.
• La URL base es https://app.whatsetter.com/api/v1.

1. Crea una clave API

1. Abre Configuración, luego API y MCP.
2. Haz clic en Crear una clave.
3. Rellena Nombre de la clave (por ejemplo Sync CRM) y elige los Permisos: Acceso completo, o Personalizado para marcar los scopes uno a uno.
4. Haz clic en Crear la clave.
5. Copia la clave. El diálogo lo dice: Copia tu clave ahora. No volverá a mostrarse. Luego haz clic en Ya guardé mi clave.

Guárdala en una variable de entorno, nunca en tu código:

export WHATSETTER_API_KEY="ws_live_…"

¿Perdiste la clave?

WhatSetter solo guarda una huella de la clave. Si la pierdes, haz clic en Revocar en esa clave y crea una nueva.

2. Comprueba la clave

GET /me no necesita ningún scope. Te dice qué espacio y qué permisos tiene la clave.

cURL

curl https://app.whatsetter.com/api/v1/me \
  -H "Authorization: Bearer $WHATSETTER_API_KEY"

JavaScript

const res = await fetch('https://app.whatsetter.com/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}` },
});
console.log(await res.json());

Python

import os, requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
)
print(r.json())

{
  "data": {
    "team_id": "6b0c1d2e3f405162738a",
    "key": {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "name": "Sync CRM",
      "scopes": ["leads:read", "leads:write", "lists:write", "webhooks:manage"]
    }
  }
}

Un 401 invalid_api_key significa que la clave está mal copiada o revocada. Un 401 missing_api_key significa que la cabecera no nos llegó.

3. Lista tus leads

GET /leads necesita leads:read. Filtra por status, campaign_id, phone, source o since, y pagina con limit (1 a 100) y cursor.

cURL

curl "https://app.whatsetter.com/api/v1/leads?status=qualified&limit=10" \
  -H "Authorization: Bearer $WHATSETTER_API_KEY"

JavaScript

const url = new URL('https://app.whatsetter.com/api/v1/leads');
url.searchParams.set('status', 'qualified');
url.searchParams.set('limit', '10');

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}` },
});
const { data, pagination } = await res.json();
console.log(data.length, pagination.next_cursor);

Python

import os, requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/leads",
    params={"status": "qualified", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
)
body = r.json()
print(len(body["data"]), body["pagination"]["next_cursor"])

{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "phone": "33612345678",
      "name": "Julien",
      "status": "qualified",
      "qualified": true,
      "qualified_at": "2026-09-18T09:12:41.000Z",
      "campaign_id": "acme-france-1-ab12",
      "source": "list",
      "tags": ["hot"],
      "messages_count": 14,
      "last_message_at": "2026-09-18T09:12:00.000Z",
      "last_message_direction": "inbound"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}

El objeto lead está recortado aquí. Cuando has_more es true, devuelve next_cursor como cursor para obtener la página siguiente.

4. Importa una lista de contactos

Dos llamadas: POST /lists crea una lista vacía y luego POST /lists/{id}/leads sube hasta 500 contactos por llamada. Ambas necesitan lists:write. Los teléfonos se deduplican dentro del lote y contra la lista.

cURL

# 1. Crear la lista
curl -X POST https://app.whatsetter.com/api/v1/lists \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sync CRM, leads calientes"}'

# 2. Subir contactos (sustituye LIST_ID por el id del paso 1)
curl -X POST https://app.whatsetter.com/api/v1/lists/LIST_ID/leads \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"leads":[{"phone":"+34612345678","name":"Julia","custom_variables":{"ciudad":"Madrid"}}]}'

JavaScript

const headers = {
  Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}`,
  'Content-Type': 'application/json',
};

// 1. Crear la lista
const created = await fetch('https://app.whatsetter.com/api/v1/lists', {
  method: 'POST',
  headers,
  body: JSON.stringify({ name: 'Sync CRM, leads calientes' }),
});
const { data: list } = await created.json();

// 2. Subir contactos
const imported = await fetch(`https://app.whatsetter.com/api/v1/lists/${list.id}/leads`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    leads: [{ phone: '+34612345678', name: 'Julia', custom_variables: { ciudad: 'Madrid' } }],
  }),
});
console.log(await imported.json());

Python

import os, requests

headers = {"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"}
base = "https://app.whatsetter.com/api/v1"

# 1. Crear la lista
lst = requests.post(f"{base}/lists", headers=headers,
                    json={"name": "Sync CRM, leads calientes"}).json()["data"]

# 2. Subir contactos
r = requests.post(
    f"{base}/lists/{lst['id']}/leads",
    headers=headers,
    json={"leads": [{"phone": "+34612345678", "name": "Julia",
                     "custom_variables": {"ciudad": "Madrid"}}]},
)
print(r.json())

{
  "data": {
    "imported": 1,
    "duplicates_in_list": 0,
    "rejected": [],
    "lead_ids": ["66f1a2b3c4d5e6f7a8b9c0d2"]
  }
}

Importar todavía no envía ningún mensaje

Una lista es un depósito de contactos. El primer mensaje sale cuando la lista se vincula a una campaña, al ritmo del motor anti-ban. Para añadir un solo lead opt-in y escribirle de inmediato, usa POST /campaigns/{id}/leads.

5. Crea un webhook

POST /webhooks necesita webhooks:manage. El endpoint debe ser HTTPS.

cURL

curl -X POST https://app.whatsetter.com/api/v1/webhooks \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tu-servidor.com/webhooks/whatsetter","events":["contact.qualified","contact.not_qualified"]}'

JavaScript

const res = await fetch('https://app.whatsetter.com/api/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://tu-servidor.com/webhooks/whatsetter',
    events: ['contact.qualified', 'contact.not_qualified'],
  }),
});
const { data } = await res.json();
console.log(data.secret); // whsec_… se muestra una sola vez, guárdalo ahora

Python

import os, requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
    json={"url": "https://tu-servidor.com/webhooks/whatsetter",
          "events": ["contact.qualified", "contact.not_qualified"]},
)
print(r.json()["data"]["secret"])  # whsec_… se muestra una sola vez, guárdalo ahora

{
  "data": {
    "id": "66f1c0ffee00000000000abc",
    "url": "https://tu-servidor.com/webhooks/whatsetter",
    "events": ["contact.qualified", "contact.not_qualified"],
    "active": true,
    "description": null,
    "secret_prefix": "whsec_3f9a",
    "secret": "whsec_3f9a…",
    "last_delivery_at": null,
    "last_delivery_status": null,
    "created_at": "2026-09-19T10:00:00.000Z"
  }
}

El secret solo aparece en esta respuesta. Guárdalo: lo necesitas para verificar la firma de cada entrega. Después envíate un evento de prueba firmado con POST /webhooks/{id}/test.

Siguientes pasos

• Autenticación y permisos: scopes, límites de peticiones, rotación de claves.
• Errores, límites e idempotencia: cada code, y cómo reintentar sin riesgo.
• Guías por recurso: leads, campañas, mensajes, grupos, contactos bloqueados, enlaces.
• Servidor MCP: dale la misma clave a Claude, Cursor o ChatGPT.
• Usar estos docs con asistentes IA: deja que un asistente construya la integración por ti.