# Contactos bloqueados

> Silenciar al agente para un número o todo un prefijo, listar y eliminar tus reglas, y entender qué hace y qué no hace un bloqueo.

Source: https://docs.whatsetter.com/es/developers/guides/blocked-contacts/

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 **Números bloqueados**, en la **Configuración** del dashboard.

## Endpoints

| Método | Ruta | Scope |
|---|---|---|
| GET | [`/blocked-contacts`](/api-reference/operations/listblockedcontacts/) | `blocklist:manage` |
| POST | [`/blocked-contacts`](/api-reference/operations/createblockedcontact/) | `blocklist:manage` |
| DELETE | [`/blocked-contacts/{id}`](/api-reference/operations/deleteblockedcontact/) | `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, a todos los agentes: `campaign_id` es `null`, tanto si la regla se crea aquí como en el dashboard.

## Listar reglas

**cURL**

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

**JavaScript**

```js
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**

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

```json
{
  "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**

```bash
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**

```js
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**

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

```json
{
  "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

```json
{ "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**

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

**JavaScript**

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

**Python**

```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](/es/developers/guides/conversations/)
- [Leads](/es/developers/guides/leads/)
- [Números bloqueados en el dashboard](/es/dashboard/blocked-numbers/)
