Имена пользователей WhatsApp и BSUID: что меняется для OTP, CRM и вебхуков

Идентификатор пользователя в рамках бизнес-портфолио (BSUID) — это идентификатор, который Meta теперь вставляет в каждый вебхук WhatsApp, чтобы бизнес мог отправить сообщение пользователю, не зная его номера телефона. Он существует потому, что WhatsApp внедряет имена пользователей: как только пользователь включает имя пользователя, бизнес, который не связывался с ним недавно, может больше не получать номер. Это руководство от инженерной команды BroadNet объясняет формат, временные рамки, что все еще требует номер телефона и как мигрировать вебхуки, записи CRM и потоки OTP.

Основные выводы

• BSUID появляются в вебхуках WhatsApp с начала апреля 2026 года для каждого пользователя, независимо от того, использует ли он имя пользователя.
• BSUID выглядит как US.13491208655302741918: двухбуквенный код страны ISO 3166 (alpha-2), точка, а затем до 128 буквенно-цифровых символов.
• Он уникален для каждой пары бизнес-портфолио и пользователя и генерируется заново, если пользователь меняет свой номер телефона.
• С июля 2026 года вы можете отправлять сообщения на BSUID, за исключением шаблонов аутентификации «в одно касание», «в ноль касаний» и «копирование кода», для которых все еще требуется номер телефона.
• Meta заявляет, что партнеры и напрямую интегрированные бизнесы должны поддерживать BSUID, чтобы не потерять возможность обрабатывать сообщения от пользователей с именами пользователей.
• Сохраняйте проверенный номер телефона E.164 в качестве якоря идентификации для OTP, резервного варианта SMS и проверок на мошенничество. Относитесь к BSUID как к ключу канала WhatsApp.

Что такое идентификатор пользователя в рамках бизнес-портфолио?

Meta определяет BSUID как "уникальный идентификатор пользователя, который можно использовать для отправки сообщений пользователю WhatsApp, когда вы не знаете его номер телефона" (Meta, идентификаторы пользователя в рамках бизнес-портфолио). Формат представляет собой страну пользователя в виде кода alpha-2 ISO 3166, точку и до 128 буквенно-цифровых символов, например US.13491208655302741918.

Для проектирования системы важны три свойства:

• Область действия. BSUID уникален для одного бизнес-портфолио и одного пользователя. Один и тот же человек имеет другой BSUID для каждого бизнес-портфолио, с которым он взаимодействует, поэтому вы не можете использовать его для сопоставления клиентов в несвязанных портфолио.
• Стабильность. Он создаётся заново, когда пользователь меняет свой номер телефона. При этом Meta отправляет вебхук сервисного сообщения с типом user_changed_user_id и отдельный вебхук user_id_update.
• Родительские BSUID. Компании с несколькими бизнес-портфолио могут попросить свое контактное лицо в Meta зарегистрироваться в родительских BSUID, которые содержат ENT (например, US.ENT.11815799212886844830) и действуют во всех зарегистрированных бизнес-портфолио.

Почему WhatsApp внедряет имена пользователей?

Для обеспечения конфиденциальности. Meta объявил 29 июня 2026 года, что люди могут зарезервировать имя пользователя для использования «позже в этом году», и что когда пользователь активирует его, человек или компания, которым он напишет впервые, больше не будут видеть его номер телефона (Об Meta). В документации разработчика Meta говорится, что внедрение имен пользователей будет происходить постепенно в 2026 году.

Бизнес также может иметь имена пользователей. С 29 июня 2026 года компания может заявить права на имя пользователя, которое WhatsApp зарезервировал для нее через WhatsApp Manager, Meta Business Suite или Username API, и одобренные имена пользователей станут активными при запуске функции. Имя пользователя бизнеса не скрывает номер телефона бизнеса.

Каков график?

Потеряете ли вы номер телефона клиента?

Иногда. BSUID появляется во всех вебхуках сообщений. Номер телефона (wa_id и from во входящих сообщениях) включается только в том случае, если верно хотя бы одно из следующих условий согласно Meta:

• вы отправляли сообщения или звонили на номер телефона пользователя в течение 30 дней до срабатывания вебхука;
• вы получили сообщение или звонок с номера телефона пользователя в течение этих 30 дней; или
• пользователь находится в вашей книге контактов.

30-дневный период ретроспективного анализа оценивается для каждого бизнес-номера телефона, поэтому клиент, известный вашей линии продаж, может быть неизвестен вашей линии поддержки. Книга контактов — это функция, размещаемая Meta, которая сохраняет номера телефонов и BSUID после первого взаимодействия, поэтому последующие вебхуки могут продолжать передавать номер даже после того, как пользователь выберет имя пользователя. Она включена по умолчанию, и ее можно отключить в Meta Business Suite в разделе Business settings, Business info. Оставьте ее включенной, если у вас нет причин для обратного.

Что все еще требует номер телефона?

Meta выражается так: BSUID «могут использоваться для отправки любого типа сообщений, за исключением шаблонов аутентификации с одним нажатием, нулевым нажатием и копированием кода, которые требуют номеров телефонов пользователей». Помимо WhatsApp, любой сервис, работающий в мобильной сети, также требует номер.

Как выглядит вебхук до и после?

До BSUID блок контактов в вебхуке сообщений содержал номер телефона в wa_id, и большинство интеграций использовали его в качестве ключа клиента. Пример нового объекта контактов от Meta добавляет имя пользователя, BSUID и, если включено, родительский BSUID; wa_id присутствует только тогда, когда номер может быть передан:

1"contacts": [
2  {
3    "profile": {
4      "name": "<USER_DISPLAY_NAME>",
5      "username": "<USERNAME>"
6    },
7    "wa_id": "<USER_PHONE_NUMBER>",
8    "user_id": "<BSUID>",
9    "parent_user_id": "<PARENT_BSUID>"
10  }
11]

Входящие сообщения также содержат from_user_id (и from_parent_user_id, если включено), а вебхуки статуса содержат recipient_user_id, который, согласно Meta, всегда устанавливается в BSUID пользователя. Чтобы отправить сообщение, поместите BSUID в новый параметр recipient. Можно указать параметр to (номер телефона), параметр recipient (BSUID) или оба; если указаны оба, приоритет имеет номер телефона:

1{
2  "messaging_product": "whatsapp",
3  "recipient_type": "individual",
4  "recipient": "<BSUID>",
5  "type": "text",
6  "text": {
7    "body": "<BODY_TEXT>"
8  }
9}

Ответ на отправку затем включает user_id в массиве контактов, а wa_id становится необязательным. Если ваш парсер предполагает, что wa_id всегда присутствует, он выдаст ошибку на первом пользователе с именем пользователя. Вы можете вставить реальные полезные нагрузки в наш инспектор полезной нагрузки вебхука, чтобы проверить, какие поля на самом деле получает ваша интеграция.

Что ломается для OTP?

Шаблоны аутентификации с кнопками в одно нажатие, без нажатия или с копированием кода не могут быть отправлены на BSUID. Если пользователь с именем пользователя связывается с вами через WhatsApp, а у вас нет его номера телефона, вы не сможете отправить ему WhatsApp OTP таких типов. Это влечет за собой два последствия для процессов верификации:

• Соберите и подтвердите номер телефона при регистрации в формате E.164 и сохраните его как адрес верификации аккаунта. Не полагайтесь на то, что вебхук WhatsApp передаст его вам позже. См. что такое E.164.
• Поддерживайте канал, который работает непосредственно с номером. SMS OTP, голосовой OTP и бесшумные сетевые проверки — все они работают на основе номера телефона, именно поэтому многоканальный дизайн с автоматическим переключением остается неизменным после этого изменения. Наше руководство по многоканальному OTP и продукт BroadNet OTP описывают этот паттерн.

Что ломается для CRM и дедупликации клиентов?

Большинство CRM используют номер телефона в качестве ключа для контакта WhatsApp, потому что SMS, голосовые сообщения и WhatsApp раньше использовали его. После появления имен пользователей новый входящий контакт может прийти только с BSUID. Если вы создадите для него новую запись в CRM, вы начнете постепенно дублировать клиентов. Четыре правила помогут сохранить чистоту данных:

1. 1Моделируйте BSUID как идентификатор канала, а не как ID клиента. Один клиент может владеть несколькими BSUID (по одному на каждое бизнес-портфолио) и новым после смены номера.
2. 2Вести таблицу сопоставления BSUID, портфолио, номера телефона (если известен), даты первого появления и даты последнего появления, и обновлять ее при каждом вебхуке, включая user_id_update.
3. 3Объединяйте на основе доказательств, а не догадок: проверенного номера телефона, логина или номера заказа, который клиент предоставляет в чате.
4. 4Никогда не рассматривайте отсутствие wa_id как нового клиента. Это лишь означает, что номер не может быть передан в рамках данного события.

Как вы осуществляете миграцию? Пошаговый контрольный список

1. 1Обновите парсеры вебхуков, чтобы они считывали user_id, from_user_id, recipient_user_id и имя пользователя, а также рассматривали wa_id и from как необязательные.
2. 2Добавьте столбец BSUID (и родительский BSUID, если вы являетесь управляемым бизнесом) везде, где вы храните контакты WhatsApp.
3. 3Заполнение данных за прошлые периоды: для каждого входящего события с начала апреля 2026 года свяжите BSUID с номером телефона, который у вас уже есть.
4. 4Обрабатывайте системное сообщение user_changed_user_id и вебхук user_id_update путем повторного связывания нового BSUID с клиентом.
5. 5Добавьте параметр recipient в ваш путь отправки и используйте его в качестве резервного варианта, когда у вас нет номера телефона.
6. 6Направляйте OTP на номер телефона, никогда не на BSUID, и используйте SMS или голос в качестве резервного канала.
7. 7Зарезервируйте свое бизнес-имя пользователя в WhatsApp Manager, Meta Business Suite или через Username API.
8. 8Протестируйте работу с аккаунтом, в котором включены имена пользователей, прежде чем имена пользователей станут доступны вашим клиентам.

Если BroadNet является вашим провайдером WhatsApp, запросите тестовый доступ и подтвердите, как поля BSUID отображаются в вебхуках для вашего аккаунта, прежде чем вносить изменения в рабочий код. Подробности доступны в нашем центре для разработчиков и на странице WhatsApp Business API, а омниканальная маршрутизация обеспечивает SMS резервный переход, от которого теперь зависят потоки аутентификации.

Часто задаваемые вопросы

Что такое WhatsApp BSUID?

Идентификатор пользователя в рамках бизнеса: идентификатор, который Meta присваивает каждому WhatsApp пользователю для каждого бизнес-портфолио, чтобы бизнес мог отправлять сообщения пользователю, не зная его номера телефона. В вебхуках он отображается как user_id.

Как выглядит BSUID?

Буквенно-цифровой код страны ISO 3166 в формате alpha-2, точка, а затем до 128 буквенно-цифровых символов, например US.13491208655302741918. Родительские BSUID для управляемых бизнесов включают ENT, например US.ENT.11815799212886844830.

Потеряю ли я номер телефона клиента, когда он перейдет на имя пользователя?

Только в некоторых вебхуках. Номер по-прежнему включается, если вы обменивались сообщениями или совершали звонки по этому номеру в течение последних 30 дней или если пользователь находится в вашей книге контактов. В противном случае wa_id опускается, и вы получаете только BSUID.

Могу ли я отправлять сообщения на BSUID?

Да, начиная с июля 2026 года, используя параметр recipient при отправке API. Работает любой тип сообщения, кроме шаблонов аутентификации с одним нажатием, без нажатия и с копированием кода, которые требуют номер телефона пользователя.

Могу ли я отправлять шаблоны аутентификации (OTP) для BSUID?

Нет. Шаблоны аутентификации «в одно касание», «без касания» и «копирование кода» требуют номер телефона. Сохраняйте проверенный номер телефона для каждого аккаунта и используйте SMS или голосовой OTP в качестве резервного варианта.

Работают ли BSUID в рамках разных бизнес-портфолио?

Нет. BSUID уникален для одной пары «бизнес-портфолио и пользователь». Управляемые компании могут спрашивать Meta о родительских BSUID, которые работают в рамках совместно зарегистрированных портфолио.

Меняется ли когда-либо BSUID?

Да. Он перегенерируется, когда пользователь меняет свой номер телефона, и Meta сигнализирует об этом с помощью системного сервисного сообщения user_changed_user_id и вебхука user_id_update.

Как мне зарезервировать имя пользователя моего бизнеса?

С 29 июня 2026 года через WhatsApp Manager, Meta Business Suite или Username API. Одобренное имя пользователя становится активным при запуске функции имени пользователя, и оно не скрывает номер телефона вашего бизнеса.

Источники

• Meta для разработчиков, ID пользователей в рамках бизнес-портфолио (формат, график, поля вебхука, адресная книга, параметр отправки, исключение для шаблона аутентификации), доступ к данным от 26 сентября 2026.
• Об Meta, Пришло время зарезервировать ваше имя пользователя WhatsApp, 29 июня 2026, доступ к данным от 26 сентября 2026.