Миграция WhatsApp Embedded Signup v4: чек-лист Coexistence до 15 октября 2026 года
Если ваша интеграция подключает существующие номера WhatsApp Business app через Coexistence, перенесите Embedded Signup v2 на v4 до 15 октября 2026 года. Для v4 Meta требует новую конфигурацию Facebook Login for Business: выбор Embedded Signup и нужных продуктов переводит flow на v4. Это миграция онбординга, а не косметическое обновление интерфейса, поэтому заново проверьте permissions, callbacks, выбор Coexistence, webhooks и синхронизацию истории.
Главное
- Meta сообщает, что Embedded Signup v2 будет выведен из эксплуатации 15 октября 2026 года, и рекомендует перейти на v4 до этой даты, чтобы избежать перебоев.
- V4 настраивается через новую конфигурацию Facebook Login for Business. Выбранные продукты определяют assets и permissions, включённые во flow.
- Онбординг пользователей WhatsApp Business app — flow, который обычно называют Coexistence, — по-прежнему поддерживается в v4.
- Успешная миграция должна доказывать больше, чем «диалог открывается»: проверьте вариант Coexistence, finish callback, asset IDs, обмен токена, доставку webhook и 24-часовое окно синхронизации истории.
- Командам, которым не нужно совместное использование одного номера официальными Business app и Cloud API, стоит сначала решить, действительно ли им нужен Coexistence.
Что меняется при миграции WhatsApp Embedded Signup на v4
В документации v4 Meta сказано, что v4 был выпущен 8 октября 2025 года и теперь заменяет v2 как актуальный путь Embedded Signup. Главное изменение реализации касается места, где определяется flow.
В v2 важные параметры flow находились в объекте extras, который передавала интеграция. Для v4 Meta предписывает создать новую конфигурацию Facebook Login for Business, выбрать Embedded Signup как login variation и указать продукты, которые должны входить во flow. Выбранные продукты автоматически определяют v4 и предварительно выбирают необходимые assets и permissions.
Из-за этого меняется область проверки миграции:
| Область миграции | Что проверить в v4 | Почему это важно |
|---|---|---|
| Login configuration | Новая конфигурация Facebook Login for Business использует variation Embedded Signup | Повторное использование старой конфигурации v2 не является документированным путём v4 |
| Products | Cloud API и все дополнительные messaging products выбраны намеренно | Выбор продуктов определяет онбординг и необходимые assets |
| Permissions | Для каждого автоматически выбранного permission получен Advanced Access | Внешне корректный диалог всё равно может завершиться ошибкой, если у app нет нужного доступа |
| Coexistence | Flow предлагает подключить существующие WhatsApp Business app account и number | Стандартный flow Cloud API не доказывает, что онбординг Business app сохранился после миграции |
| Session result | Finish event, asset IDs и exchangeable token code возвращаются в spawning window | Backend по-прежнему нужен этот результат для завершения онбординга |
| Webhooks | Payloads истории, state sync и message echoes принимаются корректно | Coexistence зависит от синхронизации после signup, а не только от самого signup |
V4 также объединяет выбор assets, business information и permissions и может включать такие продукты, как Click to WhatsApp Ads и Conversions API. Для миграции только Coexistence они необязательны. Выбирайте лишь те продукты, которые действительно поддерживает ваша интеграция: более широкий диалог означает больше permissions и больше тестирования.
Поддерживает ли Embedded Signup v4 WhatsApp Coexistence?
Да. В обновлённом руководстве по онбордингу Business app Meta прямо указано, что онбординг пользователей WhatsApp Business app остаётся поддерживаемым. В материалах поддержки и партнёрской документации этот flow называется Coexistence.
Официальные страницы нужно читать вместе. Общий guide по версиям показывает намеренно пустой объект extras для v4, а специализированный guide по Coexistence по-прежнему документирует выбор feature whatsapp_business_app_onboarding и версию session info. Не считайте, что удаление всех настроек Coexistence из существующего launcher сохранит тот же flow. Создайте новую конфигурацию v4, следуйте актуальным инструкциям по онбордингу Business app и проверьте реальный экран и callback на тестовом account.
Ожидаемый пользовательский путь конкретен: бизнес выбирает подключение существующего WhatsApp Business app account, вводит текущий номер, подтверждает соединение в Business app и завершает Embedded Signup. После этого Business app может продолжать обрабатывать сообщения один на один, а сообщения Cloud API и поддерживаемая история синхронизируются.
Если команда ещё решает, нужен ли ей workflow с двумя поверхностями, сначала прочитайте существующий guide по выбору WhatsApp Coexistence. Миграция оправданна только тогда, когда людям действительно нужны Business app и официальная интеграция Cloud API на одном номере.
Чек-лист миграции Coexistence
1. Проведите инвентаризацию всех точек входа v2
Найдите каждую production- и staging-кнопку, SDK call, configuration ID, callback handler и feature flag, способные запустить Embedded Signup. Зафиксируйте, какой клиентский сегмент использует Coexistence, а какой — стандартный flow Cloud API. Общий launcher может скрывать регрессию Coexistence, пока с ней не столкнётся реальный пользователь Business app.
2. Создайте новую конфигурацию v4
В App Dashboard → Facebook Login for Business → Configurations создайте конфигурацию, выберите Embedded Signup, укажите нужные продукты и скопируйте новый configuration ID в интеграцию. По документации Meta выбор продуктов устанавливает experience v4.
Проверьте автоматически выбранные assets и permissions. Для Cloud API в таблице v4 указаны WhatsApp Business accounts, а также whatsapp_business_management и whatsapp_business_messaging; для обоих требуется Advanced Access.
3. Повторно включите и протестируйте путь Coexistence
Для специализированного flow используйте актуальные инструкции Meta по онбордингу Business app. Во время теста убедитесь, что прежний экран выбора только WABA заменён вариантом подключения существующего WhatsApp Business account. Если такого варианта нет, остановите rollout: вы тестируете другой intent онбординга.
Также подтвердите документированные prerequisites: клиент использует WhatsApp Business app 2.24.17 или новее, ваша организация является Solution Partner или Tech Provider, callback умеет обрабатывать необходимые webhooks, а session logging включён.
4. Проверьте finish callback и состояние онбординга
В guide по Coexistence finish event указан как FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING. Сохраните возвращённые WABA ID, asset IDs и exchangeable token code, затем выполните обычные шаги клиентского онбординга, пропустив регистрацию phone number, поскольку номер уже зарегистрирован.
Не путайте документированное значение version: 3 в session payload с версией конфигурации Embedded Signup. Считайте их отдельными контрактами и проверяйте оба в тестах, а не маршрутизируйте процесс только по одному числовому полю.
После онбординга запросите поля business phone number, которые Meta документирует для этой проверки. Ожидаемое состояние: is_on_biz_app: true и platform_type: "CLOUD_API".
5. Подтвердите работу всех трёх путей синхронизации
До запуска подпишите app на дополнительные поля WABA webhook, необходимые Coexistence:
history— для предыдущих сообщений, которыми клиент согласился поделиться;smb_app_state_sync— для текущих и изменённых контактов;smb_message_echoes— для новых сообщений, отправленных из WhatsApp Business app.
После онбординга Meta даёт партнёру 24 часа на запуск синхронизации контактов и истории сообщений. Каждый запуск можно выполнить только один раз; для повтора клиенту потребуется offboard и повторное прохождение flow. Сохраняйте возвращённый request_id, быстро принимайте крупные webhook batches и обрабатывайте их асинхронно.
6. Выполняйте rollout с реальной границей rollback
Пока Meta разрешает обе версии, запускайте конфигурации v2 и v4 параллельно для контролируемой cohort. Отдельно по configuration ID отслеживайте completion rate, получение callback, token exchange, is_on_biz_app, завершение синхронизации и ошибки webhook. Если v4 не проходит gate, откатывайте точку входа, а не уже завершённое состояние клиента.
До октябрьского срока ещё достаточно времени, поэтому нет необходимости откладывать и затем выполнять рискованный одномоментный cutover. Сначала закончите техническую миграцию, затем изучите отдельный план измерения стоимости service messages WhatsApp, чтобы изменения онбординга и ценообразования не попали в один release.
Где подходит UnifyPort
UnifyPort не переносит конфигурации Meta, не выдаёт permissions Cloud API, не синхронизирует официальную историю Business app и не сохраняет статус Coexistence в Meta. Если продукту нужны эти официальные возможности, v4 — правильный путь, а ответственность за обязательную миграцию лежит на владельце интеграции.
UnifyPort решает другую задачу: подключает обычный WhatsApp account и доставляет поддерживаемые входящие сообщения как стандартное событие webhook message.received. Авторизация WhatsApp поддерживает связывание по QR code и phone number, а подписанная доставка webhook использует X-Device-Timestamp, X-Device-Signature и signing_secret endpoint.
Эта альтернатива актуальна, когда настоящая цель — входящая очередь, а не общий номер для Business app и Cloud API. Сравните три подхода в guide по путям входящих WhatsApp-сообщений, прежде чем выделять инженерное время на миграцию, официальные функции которой могут вам не понадобиться.
Ограничения и компромиссы
Embedded Signup v4 — правильный выбор для Solution Partners и Tech Providers, которые подключают клиентов к официальным продуктам Cloud API. Это также единственный из сравниваемых путей, сохраняющий поддерживаемое Meta поведение Coexistence, flow передачи истории, официальную модель assets и permissions продуктов Cloud API.
Неофициальный интерфейс не может предоставить эти привилегии. Он также не может сделать бизнес eligible для продуктов Meta, заменить окна обслуживания клиентов Meta или превратить подключение обычного account в WABA Cloud API. Его более узкое преимущество — стандартный входящий интерфейс без требования использовать официальный стек Coexistence.
Миграция на v4 также не отменяет эксплуатационные ограничения Coexistence. Сейчас Meta указывает фиксированную пропускную способность 20 messages per second для номеров, одновременно используемых Business app и Cloud API, отдельную тарификацию Cloud API для сообщений, отправленных через API, отсутствие поддержки синхронизации истории групп и конкретные ограничения companion devices. Во время acceptance testing повторно сверьте эти условия с официальным guide.
FAQ
Когда Embedded Signup v2 будет выведен из эксплуатации?
Meta сообщает, что Embedded Signup v2 будет выведен из эксплуатации 15 октября 2026 года. Владельцам интеграций следует перейти на v4 до этой даты, чтобы избежать перебоев в онбординге.
Всем ли пользователям WhatsApp Business app нужно мигрировать?
Нет. Миграцию выполняет партнёр или provider, владеющий интеграцией Embedded Signup v2. Бизнес, который использует только отдельное приложение WhatsApp Business app, не поддерживает конфигурацию Embedded Signup.
Удаляет ли v4 WhatsApp Coexistence?
Нет. Meta сообщает, что онбординг пользователей WhatsApp Business app продолжает поддерживаться в v4. При миграции нужно сохранить и протестировать специализированный выбор Coexistence, а не считать стандартный flow Cloud API эквивалентным.
Нужна ли новая конфигурация Facebook Login for Business?
Да. Guide Meta по v4 предписывает создать новую конфигурацию, выбрать Embedded Signup как login variation и указать продукты, которые нужно включить.
Что должен доказать тест миграции?
Как минимум: появился вариант подключения существующего Business app; finish callback и assets вернулись; token exchange завершился; is_on_biz_app имеет значение true, а platform_type — CLOUD_API; пути webhook history, smb_app_state_sync и smb_message_echoes работают.
Следующий шаг
Если вы владеете интеграцией Meta Embedded Signup, создайте новую конфигурацию по официальному guide по миграции на v4 и выполните приведённый выше чек-лист в staging. Если вам нужны только входящие сообщения обычного account, перед реализацией Coexistence оцените отдельный путь по guide авторизации WhatsApp в UnifyPort.
Источники
Официальные источники Meta проверены 16 июля 2026 года: