# Contacts bloqués

> Faire taire l'agent pour un numéro ou tout un indicatif, lister et retirer tes règles, et comprendre ce qu'un blocage fait et ne fait pas.

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

Un contact bloqué, c'est un numéro, ou un indicatif, que l'agent doit ignorer : spam, concurrents, pays que tu ne sers pas. L'API gère les mêmes règles que **Numéros bloqués**, dans les **Paramètres** du dashboard.

## Endpoints

| Méthode | Chemin | 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` |

## Ce que fait un blocage

- L'agent **ne répond plus** au contact et **ne le relance plus**.
- Les messages entrants sont **toujours enregistrés** et visibles dans la conversation : ton équipe voit ce qui se passe et peut toujours répondre à la main.
- Ce n'est pas un blocage côté WhatsApp : la personne peut toujours écrire au numéro.

Une règle s'applique à tout l'espace de travail, tous agents confondus : `campaign_id` vaut `null`, que la règle soit créée ici ou dans le dashboard.

## Lister les règles

**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": "33612345678",
      "phone": "+33612345678",
      "label": "Spammeur",
      "reason": null,
      "campaign_id": null,
      "created_at": "2026-09-15T12:00:00.000Z"
    },
    {
      "id": "66f1a2b3c4d5e6f7a8b9c142",
      "kind": "prefix",
      "value": "91",
      "phone": null,
      "label": "Inde",
      "reason": "Hors marché",
      "campaign_id": null,
      "created_at": "2026-09-15T12:01:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}
```

`kind` filtre sur `number` ou `prefix` ; `limit` va de 1 à 100, 50 par défaut. `phone` est le numéro avec un `+` pour une règle `number` sur un vrai téléphone, `null` pour un indicatif ou un identifiant WhatsApp masqué.

## Bloquer un numéro

**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":"+33 6 12 34 56 78","label":"Spammeur","reason":"Envoie des pubs tous les jours"}'
```

**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: '+33 6 12 34 56 78', label: 'Spammeur', reason: 'Envoie des pubs tous les jours' }),
});
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": "+33 6 12 34 56 78", "label": "Spammeur", "reason": "Envoie des pubs tous les jours"},
)
rule = r.json()["data"]  # 201
```

```json
{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c141",
    "kind": "number",
    "value": "33612345678",
    "phone": "+33612345678",
    "label": "Spammeur",
    "reason": "Envoie des pubs tous les jours",
    "campaign_id": null,
    "created_at": "2026-09-19T08:12:00.000Z"
  }
}
```

`phone` accepte tout format international ; espaces et ponctuation sont ignorés. `label` (80 caractères maximum) et `reason` (500 maximum) sont optionnels.

## Bloquer un indicatif

```json
{ "kind": "prefix", "prefix": "+91", "label": "Inde", "reason": "Hors marché" }
```

`prefix` fait 1 à 4 chiffres, avec ou sans le `+`. Envoie-le au même `POST /blocked-contacts` ; la réponse a la même forme, avec `kind: "prefix"` et `phone: null`.

## Retirer une règle

**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` sans corps. L'agent répond de nouveau au contact dès le message suivant.

## La règle de correspondance

- Une règle `number` correspond à l'identifiant WhatsApp exact : `33612345678` bloque `+33612345678` et rien d'autre.
- Une règle `prefix` correspond à tout numéro qui commence par ces chiffres : `91` bloque toute l'Inde. Elle ne s'applique qu'aux vrais numéros de téléphone : un identifiant WhatsApp masqué ou un fil Instagram n'a pas de pays et n'est jamais touché par un indicatif.
- Les fils de groupe ne sont jamais bloqués par ces règles.

## Les erreurs que tu rencontreras

| HTTP | `code` | Quand |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clé absente, inconnue ou révoquée. |
| 403 | `insufficient_scope` | La clé n'a pas `blocklist:manage`. |
| 404 | `not_found` | Règle inconnue, ou règle d'un autre espace de travail. |
| 409 | `already_blocked` | Le même numéro ou indicatif est déjà bloqué. |
| 422 | `validation_error` | `kind` inconnu, `phone` ou `prefix` inutilisable, `label` ou `reason` trop long. |
| 429 | `quota_exceeded` | L'espace de travail contient déjà 500 règles. |
| 429 | `rate_limited` | Trop de requêtes cette minute. Respecte `Retry-After`. |

## Voir aussi

- [Conversations](/fr/developers/guides/conversations/)
- [Leads](/fr/developers/guides/leads/)
- [Numéros bloqués dans le dashboard](/fr/dashboard/blocked-numbers/)
