Contacts bloqués

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 la section Numéros ignorés par l’agent du dashboard.

Endpoints

Méthode	Chemin	Scope
GET	`/blocked-contacts`	`blocklist:manage`
POST	`/blocked-contacts`	`blocklist:manage`
DELETE	`/blocked-contacts/{id}`	`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, toutes campagnes. Les règles créées depuis une conversation dans le dashboard peuvent être limitées à une campagne ; celles-là affichent le slug de cette campagne dans campaign_id.

Lister les règles

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

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();

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": "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 -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"}'

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

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

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

{ "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 -X DELETE "https://app.whatsetter.com/api/v1/blocked-contacts/66f1a2b3c4d5e6f7a8b9c141" \
  -H "Authorization: Bearer ws_live_…"

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

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