Guides par ressource
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.
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
Section intitulée « 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
Section intitulée « 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
Section intitulée « 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
Section intitulée « 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(); // 201import 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
Section intitulée « 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
Section intitulée « 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_…' },}); // 204import requests
requests.delete( "https://app.whatsetter.com/api/v1/blocked-contacts/66f1a2b3c4d5e6f7a8b9c141", headers={"Authorization": "Bearer ws_live_…"},) # 204204 sans corps. L’agent répond de nouveau au contact dès le message suivant.
La règle de correspondance
Section intitulée « La règle de correspondance »- Une règle
numbercorrespond à l’identifiant WhatsApp exact :33612345678bloque+33612345678et rien d’autre. - Une règle
prefixcorrespond à tout numéro qui commence par ces chiffres :91bloque 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
Section intitulée « 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. |