Блокировка пользователя в WhatsApp Business API: правило 24 часов, о котором молчат

На прошлой неделе мы выкатили блокировку/разблокировку в нашей интеграции с Bitrix24, протестировали её на случайном номере и увидели «успех»: HTTP 200, ни одной ошибки, всё зелёное. Вот только номер в списке блокировки так и не появился.

Тот день научил нас про блокировки в WhatsApp Business API больше, чем документация, — так что собираем всё в одном месте, включая правило, которое объясняет большинство жалоб в духе «блокировка не работает».

Сначала убедимся, что говорим об одной и той же проблеме

Поисковая выдача по этой теме — каша, потому что две совершенно разные проблемы описываются одними и теми же словами:

• Вы хотите заблокировать пользователя — спамера или хама, который пишет вашему бизнесу. Об этом наша статья.
• WhatsApp заблокировал ваш аккаунт — ваш номер забанили или ограничили. Совсем другая история (нарушения политик, рейтинг качества, неофициальные инструменты), и ничего из написанного ниже тут не поможет.

Сам API прост

Cloud API даёт список блокировки на каждый бизнес-номер. Три операции, один эндпоинт:

• POST /{phone-number-id}/block_users — заблокировать один или несколько номеров
• DELETE по тому же пути — разблокировать
• GET по тому же пути — посмотреть, кто сейчас заблокирован

В payload — только messaging_product: "whatsapp" плюс массив пользователей. После блокировки сообщения пользователя до вас просто не доходят: вебхук не срабатывает, во входящих и в CRM ничего не появляется. С его стороны доставка тихо останавливается на одной серой галочке.

Пока всё очевидно. Дальше — то, что реально кусается.

Правило 1: блокировать можно только тех, кто писал вам за последние 24 часа

Это главное. Написано прямо в документации Meta, но в инструментах почти никогда не всплывает:

Заблокировать можно только пользователей, которые писали вашему бизнесу в последние 24 часа.

Нельзя превентивно заблокировать номер, который вам не писал. Нельзя заблокировать того, чей спам пришёл три дня назад. Это то же 24-часовое сервисное окно, которое регулирует свободные ответы: блокировка считается частью активного диалога, а не файрволом на уровне аккаунта.

На практике это значит, что блокировка работает ровно тогда, когда нужнее всего (спамер посреди рассылки), — и отказывается работать, когда вы наводите порядок («дай-ка заблокирую всех, кто спамил нам в прошлом месяце» — нет).

Правило 2: ответ 200 не значит, что кто-то заблокирован

Вот ответ, который нас и обманул. Запросы на блокировку обрабатываются поштучно: вызов API в целом может пройти успешно, при том что каждый номер в нём отклонён. Отказы едут внутри ответа 200:

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

Если номер, который вы блокируете, не писал вам за последние 24 часа, он попадает в failed_users — и если интеграция смотрит только на HTTP-статус, она радостно отчитается об успехе, не заблокировав никого. Именно этот баг мы поймали в собственной первой версии, и, судя по тредам на форумах, мы такие далеко не первые.

Если вы строите что-то на этом API: считайте настоящим результатом именно failed_users — и показывайте причину человеку, который нажал «заблокировать».

Остальные ограничения — коротко

• Максимум 1 000 номеров за запрос, а сам список ограничен 64 000 заблокированных пользователей на номер. Щедро, но не бесконечно для тех, кого спамят по-крупному.
• Другой бизнес-аккаунт заблокировать нельзя — API блокирует только обычных пользователей.
• Блокировка действует на конкретный номер телефона, а не на весь WABA. Заблокировали спамера на номере отдела продаж — он всё ещё может писать в поддержку.
• Meta расширяет эндпоинт, чтобы он принимал новые business-scoped user ID наряду с номерами телефонов, — это часть запуска юзернеймов, при котором номера спамера у вас может и не быть. Правила те же.

Один побочный эффект, о котором стоит помнить

Заблокированный пользователь — это полная тишина: ни вебхуков, ни событий, ничего. Мы теперь проверяем список блокировки как обязательный шаг всякий раз, когда в поддержку приходит «от этого клиента перестали приходить сообщения»: давно забытая блокировка выглядит в точности как сломанная интеграция. Исключить её — один GET-запрос.

Блокировка прямо из Bitrix24

Если ваш WhatsApp работает через WASync, список блокировки живёт прямо на подключении: панель Blocked, где видно каждый заблокированный номер, можно добавить новый или разблокировать. Два решения в её дизайне выросли прямо из описанных выше граблей:

1. Когда Meta отклоняет блокировку, мы показываем настоящую причину — включая человеческое пояснение про правило 24 часов — вместо фальшивой зелёной галочки.
2. Список всегда читается вживую из Meta, так что вы видите ровно то, что реально действует, а не закешированную копию.

Спам в WhatsApp и так раздражает — не хватало ещё, чтобы инструменты врали вам о том, сработала ли блокировка.

Ведёте поддержку WhatsApp через Открытые линии Bitrix24? Загляните и в наш чек-лист по сообщениям, которые не доходят — тихие блокировки там одна из семи причин.