Contactos bloqueados

Un contacto bloqueado es un número, o un prefijo, que el agente debe ignorar: spam, competidores, países que no atiendes. La API gestiona las mismas reglas que la sección Números que el agente ignora del dashboard.

Endpoints

Método	Ruta	Scope
GET	/blocked-contacts	blocklist:manage
POST	/blocked-contacts	blocklist:manage
DELETE	/blocked-contacts/{id}	blocklist:manage

Qué hace un bloqueo

• El agente deja de responder al contacto y deja de hacerle seguimiento.
• Los mensajes entrantes se siguen guardando y son visibles en la conversación: tu equipo ve lo que pasa y puede seguir respondiendo a mano.
• No es un bloqueo a nivel de WhatsApp: la persona puede seguir escribiendo al número.

Una regla se aplica a todo el espacio de trabajo, todas las campañas. Las reglas creadas desde una conversación en el dashboard pueden limitarse a una campaña; esas muestran el slug de esa campaña en campaign_id.

Listar reglas

cURL

curl "https://app.whatsetter.com/api/v1/blocked-contacts?kind=prefix&limit=50" \
  -H "Authorization: Bearer ws_live_…"

JavaScript

const res = await fetch('https://app.whatsetter.com/api/v1/blocked-contacts?kind=prefix&limit=50', {
  headers: { Authorization: 'Bearer ws_live_…' },
});
const { data: rules, pagination } = await res.json();

Python

import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/blocked-contacts",
    params={"kind": "prefix", "limit": 50},
    headers={"Authorization": "Bearer ws_live_…"},
)
rules = r.json()["data"]

{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c141",
      "kind": "number",
      "value": "34612345678",
      "phone": "+34612345678",
      "label": "Spammer",
      "reason": null,
      "campaign_id": null,
      "created_at": "2026-09-15T12:00:00.000Z"
    },
    {
      "id": "66f1a2b3c4d5e6f7a8b9c142",
      "kind": "prefix",
      "value": "91",
      "phone": null,
      "label": "India",
      "reason": "Fuera de mercado",
      "campaign_id": null,
      "created_at": "2026-09-15T12:01:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}

kind filtra por number o prefix; limit va de 1 a 100, 50 por defecto. phone es el número con + para una regla number sobre un teléfono real, null para un prefijo o un identificador de WhatsApp enmascarado.

Bloquear un número

cURL

curl -X POST "https://app.whatsetter.com/api/v1/blocked-contacts" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -d '{"kind":"number","phone":"+34 612 34 56 78","label":"Spammer","reason":"Envía anuncios cada día"}'

JavaScript

const res = await fetch('https://app.whatsetter.com/api/v1/blocked-contacts', {
  method: 'POST',
  headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' },
  body: JSON.stringify({ kind: 'number', phone: '+34 612 34 56 78', label: 'Spammer', reason: 'Envía anuncios cada día' }),
});
const { data: rule } = await res.json(); // 201

Python

import requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/blocked-contacts",
    headers={"Authorization": "Bearer ws_live_…"},
    json={"kind": "number", "phone": "+34 612 34 56 78", "label": "Spammer", "reason": "Envía anuncios cada día"},
)
rule = r.json()["data"]  # 201

{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c141",
    "kind": "number",
    "value": "34612345678",
    "phone": "+34612345678",
    "label": "Spammer",
    "reason": "Envía anuncios cada día",
    "campaign_id": null,
    "created_at": "2026-09-19T08:12:00.000Z"
  }
}

phone acepta cualquier formato internacional; espacios y puntuación se ignoran. label (hasta 80 caracteres) y reason (hasta 500) son opcionales.

Bloquear un prefijo

{ "kind": "prefix", "prefix": "+91", "label": "India", "reason": "Fuera de mercado" }

prefix tiene de 1 a 4 dígitos, con o sin el +. Envíalo al mismo POST /blocked-contacts; la respuesta tiene la misma forma, con kind: "prefix" y phone: null.

Eliminar una regla

cURL

curl -X DELETE "https://app.whatsetter.com/api/v1/blocked-contacts/66f1a2b3c4d5e6f7a8b9c141" \
  -H "Authorization: Bearer ws_live_…"

JavaScript

await fetch('https://app.whatsetter.com/api/v1/blocked-contacts/66f1a2b3c4d5e6f7a8b9c141', {
  method: 'DELETE',
  headers: { Authorization: 'Bearer ws_live_…' },
}); // 204

Python

import requests

requests.delete(
    "https://app.whatsetter.com/api/v1/blocked-contacts/66f1a2b3c4d5e6f7a8b9c141",
    headers={"Authorization": "Bearer ws_live_…"},
)  # 204

204 sin cuerpo. El agente vuelve a responder al contacto desde el siguiente mensaje.

La regla de coincidencia

• Una regla number coincide con el identificador de WhatsApp exacto: 34612345678 bloquea +34612345678 y nada más.
• Una regla prefix coincide con todo número que empiece por esos dígitos: 91 bloquea toda la India. Solo se aplica a números de teléfono reales: un identificador de WhatsApp enmascarado o un hilo de Instagram no tiene país y nunca lo alcanza un prefijo.
• Los hilos de grupo nunca se bloquean con estas reglas.

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 blocklist:manage.
404	not_found	Regla desconocida, o regla de otro espacio de trabajo.
409	already_blocked	El mismo número o prefijo ya está bloqueado.
422	validation_error	kind desconocido, phone o prefix inutilizable, label o reason demasiado largo.
429	quota_exceeded	El espacio de trabajo ya tiene 500 reglas.
429	rate_limited	Demasiadas peticiones este minuto. Respeta Retry-After.

Relacionado

• Conversaciones
• Leads
• Números bloqueados en el dashboard