Bloquer un utilisateur sur l'API WhatsApp Business : la règle des 24 heures dont personne ne parle

La semaine dernière, nous avons livré une fonction de blocage/déblocage pour notre intégration Bitrix24, nous l'avons testée avec un numéro pris au hasard, et nous l'avons regardée « réussir » — HTTP 200, aucune erreur, tout au vert. Sauf que le numéro n'est jamais apparu sur la liste de blocage.

Cet après-midi-là nous en a appris davantage sur le comportement de blocage de l'API WhatsApp Business que la documentation elle-même, alors voici tout au même endroit — y compris la règle qui explique la plupart des plaintes du type « le blocage ne marche pas ».

D'abord, vérifions que nous parlons du même problème

Les résultats de recherche sur ce sujet sont un vrai fouillis, parce que deux problèmes très différents partagent les mêmes mots :

• Vous voulez bloquer un utilisateur — un spammeur ou un contact abusif qui écrit à votre entreprise. C'est le sujet de cet article.
• WhatsApp a bloqué votre compte — votre numéro a été banni ou restreint. Problème complètement différent (violations de politique, notes de qualité, outils non officiels), et rien de ce qui suit ne vous aidera.

L'API elle-même est simple

La Cloud API expose une liste de blocage par numéro de téléphone professionnel. Trois opérations, un seul endpoint :

• POST /{phone-number-id}/block_users — bloquer un ou plusieurs numéros
• DELETE sur le même chemin — débloquer
• GET sur le même chemin — lister qui est actuellement bloqué

Le payload se résume à messaging_product: "whatsapp" plus un tableau d'utilisateurs. Une fois bloqué, les messages d'un utilisateur ne vous parviennent tout simplement plus — aucun webhook ne se déclenche, rien n'atterrit dans votre boîte de réception ni dans votre CRM. De son côté, la livraison s'arrête discrètement à une seule coche grise.

Jusqu'ici, rien de surprenant. Passons aux parties qui mordent vraiment.

Règle n° 1 : vous ne pouvez bloquer que les personnes qui vous ont écrit dans les dernières 24 heures

C'est la règle majeure, tout droit sortie de la documentation Meta mais rarement mise en avant dans les outils :

Vous ne pouvez bloquer que les utilisateurs qui ont envoyé un message à votre entreprise au cours des dernières 24 heures.

Impossible de bloquer préventivement un numéro qui ne vous a pas écrit. Impossible de bloquer quelqu'un dont le spam est arrivé il y a trois jours. La fenêtre est la même fenêtre de service client de 24 heures qui régit les réponses libres — le blocage est traité comme un élément d'une conversation active, pas comme un pare-feu au niveau du compte.

En pratique, ça signifie que le blocage fonctionne exactement quand vous en avez le plus besoin (un spammeur en pleine rafale) et refuse de fonctionner quand vous faites du ménage (« je vais bloquer tous ceux qui nous ont spammés le mois dernier » — non).

Règle n° 2 : une réponse 200 ne veut pas dire que quelqu'un a été bloqué

Voici la réponse qui nous a piégés. Les requêtes de blocage sont traitées numéro par numéro : l'appel API peut réussir globalement alors que chaque numéro qu'il contient est refusé. Les refus voyagent à l'intérieur de la réponse 200 :

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

Si le numéro que vous avez tenté de bloquer ne vous a pas écrit dans les 24 heures, il atterrit dans failed_users — et si votre intégration ne vérifie que le statut HTTP, elle annoncera joyeusement un succès sans avoir rien bloqué. C'est précisément le bug que nous avons attrapé dans notre propre première version, et à en juger par les fils de forum, nous n'étions pas les premiers.

Si vous construisez sur cette API : traitez failed_users comme le vrai résultat, et montrez la raison à l'humain qui a cliqué sur « bloquer ».

Les autres limites, en vitesse

• 1 000 numéros maximum par requête, et la liste elle-même plafonne à 64 000 utilisateurs bloqués par numéro de téléphone. Généreux, mais pas infini pour les cibles de spam à fort volume.
• Impossible de bloquer un autre compte professionnel — l'API ne bloque que les utilisateurs ordinaires.
• Le blocage est par numéro de téléphone, pas par WABA. Bloquez un spammeur sur votre numéro commercial : il pourra toujours écrire à votre numéro de support.
• Meta étend l'endpoint pour accepter les nouveaux identifiants utilisateur propres à chaque entreprise en plus des numéros de téléphone — un volet du déploiement des noms d'utilisateur, où vous pourriez ne même pas avoir le numéro d'un spammeur. Les mêmes règles s'appliquent.

Un effet de bord à garder en tête

Un utilisateur bloqué produit un silence complet — pas de webhooks, pas d'événements, rien. Nous vérifions désormais la liste de blocage comme étape standard chaque fois qu'un « les messages de ce client n'arrivent plus » remonte au support, parce qu'un blocage oublié depuis longtemps ressemble trait pour trait à une intégration cassée. Une seule requête GET suffit à l'écarter.

Bloquer depuis Bitrix24

Si votre WhatsApp passe par WASync, la liste de blocage vit sur la connexion elle-même : un panneau Bloqués où vous voyez chaque numéro bloqué, en ajoutez un, ou débloquez. Deux choix de conception sortent directement des échecs décrits plus haut :

1. Quand Meta refuse un blocage, nous vous montrons la vraie raison — y compris une note en langage clair sur la règle des 24 heures — au lieu d'une fausse coche verte.
2. La liste est toujours lue en direct depuis Meta, donc ce que vous voyez est ce qui est réellement appliqué, pas une copie en cache.

Le spam sur WhatsApp est déjà assez pénible sans que vos outils vous mentent sur le succès du blocage.

Vous gérez votre support WhatsApp via les Canaux ouverts Bitrix24 ? Notre checklist de dépannage pour les messages qui n'apparaissent pas devrait aussi vous intéresser — les blocages silencieux figurent parmi les sept causes de la liste.