Nutzer blockieren über die WhatsApp Business API: die 24-Stunden-Regel, die niemand erwähnt

Letzte Woche haben wir für unsere Bitrix24-Integration eine Blockieren/Entblocken-Funktion ausgeliefert, sie mit einer beliebigen Nummer getestet und zugesehen, wie sie „funktionierte“ — HTTP 200, kein Fehler, alles grün. Nur: Die Nummer tauchte nie auf der Sperrliste auf.

Dieser Nachmittag hat uns mehr über das Blockierverhalten der WhatsApp Business API beigebracht als die Dokumentation. Hier deshalb alles an einem Ort — inklusive der Regel, die die meisten „Blockieren funktioniert nicht“-Beschwerden erklärt.

Vorab: Reden wir überhaupt vom selben Problem?

Die Suchergebnisse zu diesem Thema sind ein Durcheinander, weil zwei völlig verschiedene Probleme dieselben Wörter teilen:

• Sie wollen einen Nutzer blockieren — einen Spammer oder ausfälligen Kontakt, der Ihrem Unternehmen schreibt. Darum geht es in diesem Artikel.
• WhatsApp hat Ihr Konto blockiert — Ihre Nummer wurde gesperrt oder eingeschränkt. Ein komplett anderes Problem (Richtlinienverstöße, Qualitätsbewertungen, inoffizielle Tools), bei dem Ihnen nichts von dem Folgenden hilft.

Die API selbst ist simpel

Die Cloud API führt pro geschäftlicher Rufnummer eine Sperrliste. Drei Operationen, ein Endpunkt:

• POST /{phone-number-id}/block_users — eine oder mehrere Nummern blockieren
• DELETE auf denselben Pfad — entblocken
• GET auf denselben Pfad — auflisten, wer aktuell blockiert ist

Der Payload besteht nur aus messaging_product: "whatsapp" plus einem Array von Nutzern. Einmal blockiert, erreichen die Nachrichten eines Nutzers Sie schlicht nicht mehr — kein Webhook feuert, nichts landet im Posteingang oder CRM. Auf seiner Seite bleibt die Zustellung kommentarlos bei einem grauen Haken stehen.

So weit, so erwartbar. Jetzt die Teile, die wirklich zubeißen.

Regel 1: Blockieren geht nur bei Personen, die Ihnen in den letzten 24 Stunden geschrieben haben

Das ist die große Regel — sie steht so in Metas Dokumentation, taucht aber in kaum einem Tool auf:

Blockieren lassen sich nur Nutzer, die Ihrem Unternehmen innerhalb der letzten 24 Stunden eine Nachricht geschickt haben.

Sie können keine Nummer präventiv blockieren, die Ihnen nie geschrieben hat. Sie können niemanden blockieren, dessen Spam drei Tage alt ist. Das Fenster ist dasselbe 24-Stunden-Kundenservice-Fenster, das auch für Freitext-Antworten gilt — Blockieren wird als Teil einer aktiven Konversation behandelt, nicht als kontoweite Firewall.

In der Praxis heißt das: Blockieren funktioniert genau dann, wenn man es am dringendsten braucht (ein Spammer mitten in der Welle) — und verweigert den Dienst beim Aufräumen („ich blockiere mal alle, die uns letzten Monat zugespamt haben“ — nein).

Regel 2: Eine 200er-Antwort heißt nicht, dass irgendwer blockiert wurde

Und hier die Antwort, die uns hereingelegt hat. Block-Requests arbeiten pro Nummer: Der API-Aufruf kann insgesamt erfolgreich sein, während jede einzelne enthaltene Nummer abgelehnt wird. Die Ablehnungen reisen in der 200er-Antwort mit:

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

Hat die Nummer, die Sie blockieren wollten, Ihnen nicht innerhalb von 24 Stunden geschrieben, landet sie in failed_users — und wenn Ihre Integration nur den HTTP-Status prüft, meldet sie fröhlich Erfolg, ohne irgendjemanden zu blockieren. Genau diesen Bug haben wir in unserer eigenen ersten Version gefunden, und den Forenthreads nach zu urteilen waren wir nicht die Ersten.

Wer auf dieser API baut: Behandeln Sie failed_users als das eigentliche Ergebnis — und zeigen Sie dem Menschen, der auf „Blockieren“ geklickt hat, den Grund an.

Die übrigen Grenzen, im Schnelldurchlauf

• Maximal 1.000 Nummern pro Request, und die Liste selbst ist bei 64.000 blockierten Nutzern pro Rufnummer gedeckelt. Großzügig — aber für stark bespamte Nummern nicht unendlich.
• Andere Business-Konten lassen sich nicht blockieren — die API blockiert nur reguläre Nutzer.
• Blockiert wird pro Rufnummer, nicht pro WABA. Wer den Spammer auf der Vertriebsnummer blockiert, dem kann er weiterhin an die Support-Nummer schreiben.
• Meta erweitert den Endpunkt gerade um die neuen business-bezogenen User-IDs neben Telefonnummern — Teil des Username-Rollouts, bei dem Sie die Nummer eines Spammers womöglich gar nicht mehr haben. Es gelten dieselben Regeln.

Ein Nebeneffekt, den man sich merken sollte

Ein blockierter Nutzer erzeugt absolute Stille — keine Webhooks, keine Events, nichts. Wir prüfen inzwischen standardmäßig die Sperrliste, sobald im Support „von diesem einen Kunden kommen keine Nachrichten mehr“ auftaucht — denn eine längst vergessene Blockierung sieht exakt so aus wie eine kaputte Integration. Ein einziger GET-Request schließt das aus.

Blockieren direkt aus Bitrix24

Läuft Ihr WhatsApp über WASync, lebt die Sperrliste direkt an der Verbindung: ein Blockiert-Panel, in dem Sie jede blockierte Nummer sehen, eine hinzufügen oder entblocken. Zwei Designentscheidungen stammen unmittelbar aus den oben beschriebenen Fehlschlägen:

1. Lehnt Meta eine Blockierung ab, zeigen wir den tatsächlichen Grund an — inklusive eines verständlichen Hinweises auf die 24-Stunden-Regel — statt eines falschen grünen Häkchens.
2. Die Liste wird immer live von Meta gelesen. Was Sie sehen, ist das, was tatsächlich durchgesetzt wird — keine gecachte Kopie.

Spam auf WhatsApp ist ärgerlich genug, ohne dass einem die eigenen Tools auch noch vorlügen, die Blockierung hätte geklappt.

Sie betreiben WhatsApp-Support über Bitrix24 Offene Kanäle (Open Lines)? Dann lohnt auch unsere Troubleshooting-Checkliste für Nachrichten, die nicht ankommen — stille Blockierungen sind eine von sieben Ursachen auf der Liste.