Blocked contacts

A blocked contact is a number, or a dial prefix, the agent must ignore: spam, competitors, countries you do not serve. The API manages the same rules as the Numbers the agent ignores section of the dashboard.

Endpoints

Method	Path	Scope
GET	`/blocked-contacts`	`blocklist:manage`
POST	`/blocked-contacts`	`blocklist:manage`
DELETE	`/blocked-contacts/{id}`	`blocklist:manage`

What a block does

The agent no longer replies to the contact and no longer follows up.
Incoming messages are still stored and visible in the conversation, so your team sees what happens and can still answer by hand.
It is not a WhatsApp-level block: the person can still write to the number.

A rule applies to the whole workspace, every campaign. Rules created from a conversation in the dashboard can be scoped to one campaign; those show that campaign’s slug in campaign_id.

List rules

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": "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": "Out of market",
      "campaign_id": null,
      "created_at": "2026-09-15T12:01:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}

kind filters on number or prefix; limit is 1 to 100, 50 by default. phone is the number with a + for a number rule on a real phone, null for a prefix or a masked WhatsApp id.

Block a number

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":"Spammer","reason":"Sends ads every day"}'

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: 'Spammer', reason: 'Sends ads every day' }),
});
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": "Spammer", "reason": "Sends ads every day"},
)
rule = r.json()["data"]  # 201

{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c141",
    "kind": "number",
    "value": "33612345678",
    "phone": "+33612345678",
    "label": "Spammer",
    "reason": "Sends ads every day",
    "campaign_id": null,
    "created_at": "2026-09-19T08:12:00.000Z"
  }
}

phone accepts any international format; spaces and punctuation are ignored. label (up to 80 characters) and reason (up to 500) are optional.

Block a dial prefix

{ "kind": "prefix", "prefix": "+91", "label": "India", "reason": "Out of market" }

prefix is 1 to 4 digits, with or without the +. Send it to the same POST /blocked-contacts; the response has the same shape, with kind: "prefix" and phone: null.

Remove a rule

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 with no body. The agent answers the contact again from the next message.

The match rule

A number rule matches the exact WhatsApp id: 33612345678 blocks +33612345678 and nothing else.
A prefix rule matches every number that starts with those digits: 91 blocks all of India. It only applies to real phone numbers: a masked WhatsApp id or an Instagram thread carries no country and is never matched by a prefix.
Group threads are never blocked by these rules.

Errors you will meet

HTTP	`code`	When
401	`missing_api_key`, `invalid_api_key`	Key absent, unknown or revoked.
403	`insufficient_scope`	The key lacks `blocklist:manage`.
404	`not_found`	Unknown rule, or a rule of another workspace.
409	`already_blocked`	The same number or prefix is already blocked.
422	`validation_error`	Unknown `kind`, unusable `phone` or `prefix`, `label` or `reason` too long.
429	`quota_exceeded`	The workspace already holds 500 rules.
429	`rate_limited`	Too many requests this minute. Honor `Retry-After`.