Кратко: В июне 2026 года WhatsApp заменит телефонные номера на BSUID (Business-Scoped User IDs). Храните оба поля в базе данных, внедрите 3-уровневый паттерн отката для разрешения идентификаторов и будьте готовы к тому, что поле from в вебхуках станет null. Формат BSUID: страна.буквенно-цифровой_код — напр.: US.13491208655302741918.
Июнь 2026 года сломает чатботов, работающих с телефонными номерами. WhatsApp запускает имена пользователей и новую систему идентификации под названием BSUID (Business-Scoped User ID). Телефонные номера исчезают; BSUID остаются. Если ваша интеграция хранит только телефонные номера, отправляет сообщения на адреса E.164 или предполагает, что поле from всегда содержит телефонный номер — вы строите на фундаменте, который рухнет через несколько недель.
Это руководство для backend-разработчиков, запускающих автоматизацию WhatsApp в продакшене: создателей чатботов, основателей SaaS с системами уведомлений и инженеров по интеграции, поддерживающих корпоративные стеки сообщений. Вам нужно понять, что такое BSUID, почему это ломает существующие системы и как именно мигрировать до июня 2026 года.
Что такое BSUID и почему июнь 2026 года всё меняет
Формат BSUID: код страны плюс энтропия, которую нужно сохранить. Business-Scoped User ID объединяет код страны с буквенно-цифровой строкой: {страна}.{идентификатор}. Пример: US.13491208655302741918. Этот идентификатор заменяет телефонный номер как основной адрес для взаимодействий с WhatsApp Business API.
Изменение не косметическое. WhatsApp вводит имена пользователей, которые можно настроить, чтобы скрыть телефонные номера от бизнес-контактов. Когда пользователь скрывает свой номер, BSUID становится единственным доступным идентификатором. Это концептуально то же самое, что LID (Line Identity), на который WhatsApp переходит с 2024 года. Разница: LID был внутренним переходом; BSUID — это публичная реальность, с которой должен работать ваш код.
Авторитетный источник подтверждает сроки: Имена пользователей WhatsApp и BSUID запускаются в июне 2026 года. Как отмечено в FAQ Whapi.Cloud об именах пользователей WhatsApp, BSUID концептуально совпадает с LID — это новый основной идентификатор для работы с API. Системы, которые не адаптируются, столкнутся с бесшумными сбоями, неотличимыми от успешных отправок.
Мы видели этот паттерн миграции раньше. Когда WhatsApp перевёл внутреннюю инфраструктуру с телефонной адресации на маршрутизацию через LID, open-source библиотеки столкнулись с критическими изменениями. Те же паттерны повторяются с BSUID — только на этот раз последствия внешние. Ваше сообщение может быть отмечено как отправленное, при этом пользователь его никогда не получит.
Сценарий сбоя: когда телефонные номера становятся призраками
Призрачные чаты: сообщения, отправленные на номера, которые никто не получает. Это конкретный сбой, который ваши пользователи испытают, если вы не мигрируете. Когда WhatsApp полностью включит приватность имён пользователей, пользователи, скрывшие свои телефонные номера, больше не будут получать сообщения, отправленные на их адрес E.164. Ваш API-запрос возвращает успех — HTTP 200, ID сообщения присвоен — но сообщение попадает в пустоту доставки.
Вот как выглядит сценарий призрачного чата на практике. Ваша система хранит телефонный номер клиента: +12025551234. Вы отправляете сообщение, используя этот номер как адресата. API принимает запрос. Но пользователь включил приватность имени пользователя, поэтому его клиент WhatsApp больше не маршрутизирует сообщения, адресованные по телефонному номеру. Сообщение бесшумно отбрасывается. Пейлоады вебхуков, которые вы получаете, также могут измениться, когда пользователи скрывают свои номера.
// СЦЕНАРИЙ ПРИЗРАЧНОГО ЧАТА — Этот код сломается в июне 2026
// Отправка на телефонный номер, когда пользователь его скрыл = бесшумный сбой
const response = await fetch('https://gate.whapi.cloud/messages/text', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.WHAPI_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '+12025551234', // Телефонный номер — МОЖЕТ НЕ ДОЙТИ
body: 'Ваш заказ отправлен!'
})
});
// HTTP 200 возвращён, сообщение отображается как отправленное
// Но пользователь его никогда не получает — создан призрачный чат
console.log('Сообщение отправлено:', response.data);
Феномен призрачных чатов уже наблюдается на фазе миграции LID. Разработчики сообщают, что валидные телефонные номера возвращают null из lookup API, а сообщения, отправленные на эти номера, создают недоставленные разговоры. Когда переход на BSUID завершится в июне 2026 года, это станет поведением по умолчанию для пользователей с включённой приватностью — а не крайним случаем.
Типичные соображения: Призрачные чаты хуже, чем видимые ошибки. Неудавшаяся доставка с кодом ошибки запускает логику повторных попыток и алерты. Призрачный чат выглядит как успех в ваших логах, пока клиент ничего не получает. Ваши метрики показывают 98% доставки, в то время как реальный охват может быть 60% или ниже для пользователей с включённой приватностью.
Как ломается API: от вебхуков до ключей базы данных
Поле from становится null — ваши предположения о БД умирают. Самое критичное изменение — в пейлоадах вебхуков. Когда пользователь скрывает свой телефонный номер, поле from во входящих вебхуках сообщений может быть пустым или null. Системы, построенные на предположении, что каждое сообщение имеет валидный телефонный номер отправителя, сломаются на этапе парсинга.
Как документирует Azure Communication Services (2024): "Поле from теперь может быть пустым или null, когда пользователь скрывает свой телефонный номер." Это не теоретический риск. Это документированное изменение поведения, которое влияет на то, как вы парсите вебхуки, храните историю разговоров и связываете входящие сообщения с записями клиентов.
Влияние на базу данных столь же серьёзно. E.164 был вечным — пока WhatsApp не изменил вечность. Существующие системы часто используют телефонные номера как внешние ключи, связывающие таблицы разговоров с таблицами клиентов. Когда BSUID заменяют телефонные номера как основные идентификаторы, эти связи внешних ключей ломаются. Поиск в БД по WHERE phone = '+12025551234' не возвращает результатов, когда идентификатор теперь US.13491208655302741918.
Несовместимость модели данных — скрытая стоимость этой миграции. Системы, предполагающие, что поля to и from всегда содержат телефонные номера E.164, столкнутся с разрывом внешних ключей, дублированием записей клиентов под BSUID и потерей связности разговоров. Миграция требует изменений схемы, а не только обновлений кода.
Сравнение телефонного номера, LID и BSUID:
| Атрибут | Телефонный номер (E.164) | LID (Line Identity) | BSUID (Business-Scoped User ID) |
| Формат | +{страна}{номер} напр.: +12025551234 |
{буквенно-цифровой} напр.: [email protected] |
{страна}.{идентификатор} напр.: US.13491208655302741918 |
| Видимость | Публичная (если пользователь разрешил) | Внутренняя | API-ориентированная |
| Доступность | Снижается — пользователи могут скрыть | Переход на BSUID | Основной с июня 2026 |
| Надёжность lookup | Пока работает | Возвращает null для валидных пользователей | Прямая — lookup не нужен |
| Требование хранения | Сохранить для обратной совместимости | Устарел | Обязательный первичный ключ |
3-уровневый паттерн отката
Lookup LID не работает; откаты спасают продакшен. Lookup API, разрешающие телефонные номера в LID, уже возвращают null для валидных пользователей WhatsApp. Вебхук-событие lid-mapping.update срабатывает нерегулярно, препятствуя надёжному маппингу LID-телефон. Продакшен-система не может полагаться только на lookup — нужна стратегия отката при сбое разрешения.
3-уровневый паттерн отката возник из миграции LID и применяется прямо к адаптации BSUID. Мы наблюдали этот паттерн в продакшен-системах, обрабатывающих миллионы сообщений. Уровни работают последовательно: сначала BSUID, потом lookup LID, затем повтор по телефону. Каждый уровень обрабатывает режим отказа предыдущего.
Уровень 1 — Прямая отправка по BSUID: Если у вас есть BSUID из предыдущего взаимодействия или вебхука — отправляйте напрямую. Это самый надёжный путь: без lookup, без неоднозначности разрешения. Формат BSUID предсказуем: страна.идентификатор.
Уровень 2 — Lookup LID с кэшем: Если у вас есть телефонный номер, но нет BSUID — попробуйте lookup LID через endpoint /contacts/lids. Сохраняйте успешные маппинги в Redis или вашу БД с TTL. Lookup может вернуть null — это ожидаемо. Переходите на уровень 3, когда это произойдёт.
Уровень 3 — Повтор по телефону с детекцией призраков: Отправляйте на телефонный номер как откат. Мониторьте уведомления о доставке. Если сообщение активному пользователю не получает подтверждения доставки в течение 24 часов, в то время как другие сообщения доставляются — отметьте для ручной проверки. Это ваш детектор призрачных чатов.
// 3-УРОВНЕВЫЙ ПАТТЕРН ОТКАТА для миграции BSUID
// Пробует BSUID → Lookup LID → Телефон с детекцией призраков
async function sendWithFallback(phoneNumber, messageBody) {
// Уровень 1: Сначала пробуем кэшированный BSUID
const cachedBSUID = await db.get(`bsuid:${phoneNumber}`);
if (cachedBSUID) {
return await sendMessage(cachedBSUID, messageBody, 'bsuid');
}
// Уровень 2: Пробуем lookup LID с кэшированием
try {
const lidResponse = await fetch(
`https://gate.whapi.cloud/contacts/lids/${phoneNumber}`,
{ headers: { Authorization: `Bearer ${token}` } }
);
const lidData = await lidResponse.json();
if (lidData.lid) {
// Конвертируем LID в формат BSUID и кэшируем
const bsuid = `${lidData.country}.${lidData.identifier}`;
await db.setex(`bsuid:${phoneNumber}`, 86400, bsuid);
return await sendMessage(bsuid, messageBody, 'bsuid');
}
} catch (e) {
// Lookup не удался — логируем и переходим к откату
logger.warn(`Lookup LID не удался для ${phoneNumber}`);
}
// Уровень 3: Откат на телефон с флагом детекции призраков
// Без этого отката валидные пользователи ничего не получат
const result = await sendMessage(phoneNumber, messageBody, 'phone');
await db.sadd('ghost-watch', phoneNumber); // Мониторим доставку
return result;
}
Проекты, пропускающие 3-уровневый паттерн, часто видят резкое падение доставки, когда WhatsApp запускает приватность имён пользователей в новых регионах. Паттерн отката — не защитное программирование, а минимально жизнеспособная архитектура для июня 2026 года.
Что ваша схема БД должна хранить сейчас
Разрыв внешних ключей БД — самая болезненная часть миграции, о которой сообщают разработчики. Системы, считающие телефонные номера E.164 неизменными идентификаторами, сломаются. Вам нужна схема, которая рассматривает телефонные номера как один из множества возможных идентификаторов, а не первичный ключ.
Необходимые изменения схемы:
-
Поле основного идентификатора: Добавьте
bsuid VARCHAR(50)как основной ключ поиска для операций WhatsApp. Формат:XX.XXXXXXXXXXXXXXXXXXX(код страны + точка + 17-20 цифр). -
Вторичное поле телефона: Оставьте
phone VARCHAR(20)для обратной совместимости и читаемого отображения, но удалите ограничения внешних ключей, ссылающихся на него. -
Кэш разрешения идентификаторов: Добавьте lookup-таблицу
identifier_mappings (phone, bsuid, lid, last_updated, source)для кэширования результатов разрешения и отслеживания происхождения. -
Null-безопасный парсер вебхуков: Обновите обработчики вебхуков для приёма nullable полей
from. Когда null — извлекайте идентификатор отправителя из полей BSUID, если они есть. -
Timestamp миграции: Добавьте
bsuid_migrated_atдля отслеживания, какие записи были обновлены BSUID.
Самый частый паттерн в миграциях: команды пытаются сохранить телефонные номера как первичные ключи и хранить BSUID как опциональное вторичное поле. Это ломается, когда пользователь скрывает номер — вы создаёте дублирующую запись клиента под BSUID, фрагментируя историю разговоров и данные заказов. BSUID должен быть каноническим идентификатором; телефон — метаданными для отображения.
Отраслевое влияние: примеры e-commerce и здравоохранения
70% автоматизации означают ноль процентов, если идентификаторы сломаются. Миграция BSUID — не просто технический рефакторинг, она угрожает операционной ценности. E-commerce бизнесы, автоматизирующие 70% запросов поддержки через WhatsApp, увидят, как автоматизация упадёт до нуля, если их разрешение идентификаторов сломается. Клиники, достигающие снижения неявок на 40-65% через напоминания о приёмах, потеряют эту эффективность, если сообщения станут призрачными чатами.
Сценарий использования e-commerce: Отслеживание заказов, восстановление брошенных корзин и автоматизация поддержки клиентов зависят от надёжной доставки сообщений. Типичная настройка отправляет тысячи сообщений ежедневно. Если 30% идут пользователям с включённой приватностью имени, а система не мигрировала на обработку BSUID — это сотни недоставленных сообщений в день. Клиенты не получают уведомления об отправке. Объём тикетов поддержки взрывается.
Сценарий использования здравоохранения: Боты-напоминалки о приёмах достигают снижения неявок на 40-65%, когда сообщения надёжно доходят до пациентов. Автоматизация зависит от запланированных исходящих сообщений на подтверждённые телефонные номера. Если система напоминаний не сохранила BSUID, а lookup LID возвращает null, напоминание становится призрачным чатом. Пациент пропускает приём. Клиника теряет выручку.
Оба сектора зависят от предсказуемой маршрутизации сообщений. Миграция BSUID вносит непредсказуемость именно там, где эти рабочие процессы требуют надёжности. Миграция — не опциональное обслуживание, а сохранение операционной ценности.
Чек-лист миграции на июнь 2026 года
Мигрируйте сейчас или мигрируйте в аварийном режиме позже. Чек-лист ниже охватывает ключевые шаги для подготовки вашей интеграции WhatsApp к переходу на BSUID. Выполните их до июня 2026 года, чтобы избежать призрачных чатов и сбоев доставки.
Предварительная миграция (завершить к маю 2026):
-
Аудит текущей схемы БД — выявить все таблицы, использующие телефонные номера как внешние ключи
-
Внедрить колонку BSUID параллельно с телефонными номерами в таблицах клиентов и разговоров
-
Развернуть 3-уровневый паттерн отката в логике отправки сообщений
-
Обновить парсеры вебхуков для корректной обработки null в поле
from -
Протестировать поведение endpoint lookup LID — задокументировать обработку ответов null
Миграция (завершить к 1 июня 2026):
-
Пакетное заполнение BSUID для существующих контактов через API lookup LID
-
Переключить основную логику отправки на использование BSUID как приоритетного идентификатора
-
Включить мониторинг призрачных чатов — отслеживать сообщения без подтверждения доставки в течение 24 часов
-
Обновить документацию поддержки клиентов для ссылки на BSUID вместо телефонного номера
Пост-миграционный мониторинг: Следите за дублирующимися записями клиентов — признаком того, что телефонные lookup'ы пропускают мигрированные BSUID-записи. Мониторьте rates доставки по типу идентификатора. Ожидайте 95%+ доставки через BSUID, 80-90% через телефонный откат, разница — риск призрачных чатов.
Почему Whapi.Cloud работает с BSUID без поломок
Baileys сломался; Whapi.Cloud подготовился. Экосистема open-source библиотек боролась с миграциями идентичности WhatsApp. Разработчики сообщают об ошибках Bad MAC, сбоях No Session и исключениях Invalid PreKey при переходах LID. Это не баги уровня приложения — это протокольные разрывы, требующие инфраструктурных исправлений.
Whapi.Cloud поглощает протокольные изменения выше по течению, чтобы ваша API-поверхность оставалась стабильной. Web-сессионная сокет-архитектура — тот же механизм, который использует WhatsApp Web — обеспечивает более стабильный фундамент, чем подходы эмуляции браузера. Когда WhatsApp меняет форматы идентификаторов, инфраструктурная команда Whapi.Cloud обрабатывает протокольную адаптацию. Ваши HTTP-вызовы к API остаются неизменными.
Open-source интеграции ломаются в 3 часа ночи без ответственной стороны. У Whapi.Cloud есть живой саппорт, который активно помогает клиентам решать продакшен-проблемы — включая гайд по миграции для подготовки к BSUID. Мы провели сотни интеграций через протокольные изменения. Распознавание паттернов из этой операционной истории питает инфраструктурные улучшения, предотвращающие поломки. Для команд, выбирающих между self-hosted библиотеками и managed gateways, миграция BSUID — точка принятия решения. Self-hosted стеки требуют, чтобы вы мониторили GitHub issues, применяли патчи, тестировали протокольные изменения и управляли таймингом миграции самостоятельно. Managed инфраструктура перекладывает эту операционную нагрузку на провайдера. Учитывая, что WhatsApp вносит протокольные изменения без предупреждения, managed путь предлает предсказуемость, которую self-hosted не может обеспечить на малом и среднем масштабе.
Если вы столкнётесь с неожиданным поведением во время миграции на BSUID, свяжитесь с командой поддержки Whapi.Cloud через виджет чата на whapi.cloud — команда активно помогает клиентам решать продакшен-проблемы.
Мы не рассматриваем путь миграции официального WhatsApp Business API здесь — это требует бизнес-верификации Meta, workflow одобрения шаблонов и тарифов за сообщение, несовместимых с неофициальной API-архитектурой. Для команд, использующих официальный API, обращайтесь напрямую к документации Meta BSP.
