Вебхук account_update и все причины отключения
account_update сообщает, что состояние подключения изменилось. Его поле event указывает, что произошло, а при удалении disconnection_info.reason показывает причину. Именно она определяет, вернётся ли номер или исчез окончательно.
EasyCoexistence распознаёт каждую причину, записывает её в историю подключения и отделяет восстановимое удаление из-за неактивности от действительно исчезнувшего номера.
Событие Meta отправляет, когда приложение удалено из аккаунта.
Именованные причины отключения, которые может содержать удаление.
Период неактивности основного устройства, который приходит как PRIMARY_INACTIVITY.
Какие события содержит account_update?
PARTNER_REMOVED, когда приложение удалено из WhatsApp Business Account. Это главный сигнал отключения, на который стоит опираться, а не делать вывод по полю, ставшему false.
ACCOUNT_OFFBOARDED, когда номер полностью выведен из системы. ACCOUNT_RECONNECTED, когда ранее удалённое подключение возвращается. А также события принудительных ограничений: ACCOUNT_RESTRICTION и ACCOUNT_VIOLATION, плюс события с DISABLED или BAN в названии.
Сюда же приходят результаты проверки и одобрения, с VERIFIED или APPROVED в названии. Обработчик должен проверять имя события, а неизвестные события считать информационными, не завершая работу с ошибкой: Meta может добавлять события без предупреждения.
Каковы причины отключения?
Их шесть, и значение у каждой своё.
PRIMARY_INACTIVITY означает правило примерно четырнадцати дней: приложение WhatsApp Business не открывали на основном устройстве. Это восстановимо и встречается намного чаще всего.
COMPANION_INACTIVITY означает то же на дополнительном устройстве, но с более длинным периодом, около тридцати дней.
BUSINESS_DOWNGRADE означает, что номер вернулся в обычное приложение WhatsApp. Это завершает Coexistence, поскольку для Coexistence требуется приложение Business.
CHANGE_NUMBER означает смену самого номера. USER_RE_REGISTERED означает повторную регистрацию на новом устройстве. ACCOUNT_DISCONNECTED означает, что клиент отключил номер сам или это сделала система.
Причина также приходит вместе с disconnection_info.initiated_by, где указано, сделал ли это человек или система.
Почему причина важнее события?
Потому что один PARTNER_REMOVED не показывает, что делать дальше.
Если номер удалён из-за PRIMARY_INACTIVITY, он вернётся: компания открывает приложение, подключается снова, и всё продолжает работать. Если считать это уходом клиента, можно отправить письмо об отмене человеку, который всё ещё пользуется сервисом.
Удаление из-за BUSINESS_DOWNGRADE или ACCOUNT_DISCONNECTED означает другую ситуацию. Если считать его временным, подключение может навсегда остаться в неопределённом состоянии.
Если удаление пришло без причины, запасным сигналом служит initiated_by: удаление, выполненное человеком, выглядит намеренным, а необъяснимое системное удаление, нет. Это различие лучше заложить в код, чем выяснять позже через поддержку.
Распространённые ошибки
- Считать все PARTNER_REMOVED одинаковыми. Причина отличает две недели тишины от ушедшего клиента.
- Выводить об отключении по полю, ставшему false, вместо этого события. Так появляются ложные оповещения.
- Завершать работу при неизвестном имени события. Meta добавляет события, а обработчик должен пропускать незнакомые.
Часто задаваемые вопросы
PARTNER_REMOVED означает окончательное удаление?
Обычно нет. Чаще всего приходит PRIMARY_INACTIVITY: приложение не открывали, а повторное подключение всё восстанавливает.
Повторное подключение восстановит адрес вебхука?
Нет, и в этом ловушка. Адрес является переопределением в подписке приложения и удаляется вместе с ним. Его нужно указать заново.
Что такое COMPANION_INACTIVITY?
Та же неактивность, но на дополнительном устройстве, а не на основном, с более длинным периодом около тридцати дней.
Можно ли получить это событие без причины?
Да. В таком случае только disconnection_info.initiated_by показывает, было ли удаление намеренным.
Читайте дальше
Готовы начать?
Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.
Начать бесплатный пробный периодПроверено по состоянию на