Blocking a User on the WhatsApp Business API: the 24-Hour Rule Nobody Mentions

We shipped a block/unblock feature for our Bitrix24 integration last week, tested it with a random number, and watched it "succeed" — HTTP 200, no error, all green. Except the number never appeared on the block list.

That afternoon taught us more about the WhatsApp Business API's blocking behavior than the documentation did, so here's everything in one place — including the rule that explains most "blocking doesn't work" complaints.

First, make sure we're talking about the same problem

Search results around this topic are a mess because two very different problems share the same words:

• You want to block a user — a spammer or abusive contact writing to your business. That's this article.
• WhatsApp blocked your account — your number got banned or restricted. Completely different problem (policy violations, quality ratings, unofficial tooling), and none of what follows will help.

The API itself is simple

The Cloud API exposes a block list per business phone number. Three operations, one endpoint:

• POST /{phone-number-id}/block_users — block one or more numbers
• DELETE the same path — unblock
• GET the same path — list who's currently blocked

The payload is just messaging_product: "whatsapp" plus an array of users. Once blocked, a user's messages simply never reach you — no webhook fires, nothing lands in your inbox or CRM. From their side, delivery quietly stops at one gray check.

So far, so obvious. Now the parts that actually bite.

Rule 1: you can only block people who messaged you in the last 24 hours

This is the big one, straight from Meta's docs but rarely surfaced in tooling:

You can only block users that have messaged your business in the last 24 hours.

You cannot preemptively block a number that hasn't written to you. You can't block someone whose spam arrived three days ago. The window is the same 24-hour customer-service window that governs free-form replies — blocking is treated as part of an active conversation, not an account-level firewall.

In practice this means blocking works exactly when you need it most (a spammer mid-burst) and refuses to work when you're doing cleanup ("let me block everyone who spammed us last month" — no).

Rule 2: a 200 response doesn't mean anyone got blocked

Here's the response that fooled us. Block requests are per-number: the API call can succeed overall while every single number in it is refused. The refusals ride inside the 200 response:

{
  "messaging_product": "whatsapp",
  "block_users": {
    "added_users": [],
    "failed_users": [
      {
        "input": "40740000000",
        "errors": [
          { "message": "...", "code": ... }
        ]
      }
    ]
  }
}

If the number you tried to block hasn't messaged you within 24 hours, it lands in failed_users — and if your integration only checks the HTTP status, it will happily report success while blocking nothing. That's precisely the bug we caught in our own first version, and judging by forum threads, we weren't the first.

If you're building on this API: treat failed_users as the real result, and show the reason to the human who clicked "block."

The other limits, quickly

• 1,000 numbers max per request, and the list itself caps at 64,000 blocked users per phone number. Generous, but not infinite for high-volume spam targets.
• You can't block another business account — the API only blocks regular users.
• Blocking is per phone number, not per WABA. Block a spammer on your sales number and they can still write to your support number.
• Meta is extending the endpoint to accept the new business-scoped user IDs alongside phone numbers — part of the usernames rollout, where you might not even have a spammer's phone number. Same rules apply.

One side effect worth remembering

A blocked user produces complete silence — no webhooks, no events, nothing. We now check the block list as a standard step whenever "messages stopped arriving from this one customer" comes up in support, because a long-forgotten block looks identical to a broken integration. It takes one GET request to rule out.

Blocking from inside Bitrix24

If your WhatsApp runs through WASync, the block list lives on the connection itself: a Blocked panel where you see every blocked number, add one, or unblock. Two design choices came directly out of the failures described above:

1. When Meta refuses a block, we show you the actual reason — including a plain-language note about the 24-hour rule — instead of a fake green checkmark.
2. The list is always read live from Meta, so what you see is what's actually enforced, not a cached copy.

Spam on WhatsApp is annoying enough without your tools lying to you about whether the block worked.

Running WhatsApp support through Bitrix24 Open Lines? You might also want our troubleshooting checklist for messages that don't show up — silent blocks are one of seven causes on the list.