Зачем нужны BSUID
В 2026 году WhatsApp внедряет необязательные имена пользователей (usernames). Когда пользователь создает имя пользователя, WhatsApp может отображать его вместо номера телефона и может опускать номер телефона в полезных нагрузках Webhook. Каждый пользователь сам решает, использовать ли имя пользователя, поэтому компании больше не могут полагаться на номера телефонов как на единственный способ идентификации клиентов. В связи с этим Meta требует от компаний и партнеров WhatsApp Business Platform, а также от рекламодателей click-to-WhatsApp поддержки BSUID, чтобы они могли продолжать обрабатывать сообщения от пользователей, выбравших имена пользователей. Чтобы поддержать это изменение, Meta начала добавлять business-scoped user ID (BSUID) в полезные нагрузки Webhook в начале апреля 2026 года. BSUID — это внутренний идентификатор одного пользователя WhatsApp в рамках одного бизнес-портфолио Meta. Meta включает его в Webhook сообщений независимо от того, выбрал ли пользователь имя пользователя, и его можно использовать для отправки сообщений, когда номер телефона недоступен. Имена пользователей и BSUID имеют разные жизненные циклы. Пользователь может изменить имя пользователя без изменения номера телефона или BSUID. Если пользователь меняет номер телефона, Meta генерирует новый BSUID. Храните эти идентификаторы отдельно и обновляйте их связь при получении системного события об изменении номера телефона. Номер телефона по-прежнему может отображаться, если с бизнес-номера отправлялись сообщения или совершались звонки этому пользователю в течение последних 30 дней, либо если пользователь есть в адресной книге Meta. Считайте поля номера телефона и имени пользователя условными и настройте обработчики и хранилище идентификаторов на прием BSUID наряду с любыми другими присутствующими идентификаторами. В этом руководстве рассматриваются правила идентификации по BSUID, запросы на отправку сообщений и вызовов, адресная книга Meta и поля Webhook, которые необходимо сохранять вашей интеграции.
Обзор идентификаторов
Meta генерирует стандартные BSUID автоматически. Каждый BSUID начинается с двухбуквенного кода страны пользователя по стандарту ISO 3166 alpha-2, за которым следуют точка и до 128 буквенно-цифровых символов. Сохраняйте значение целиком. Не удаляйте и не изменяйте префикс страны, точку или символы идентификатора.
Для BSUID действуют следующие правила жизненного цикла:
- BSUID уникален для пары «бизнес-портфолио — пользователь».
- BSUID пользователя меняется при смене пользователем своего номера телефона.
- Родительский BSUID работает во всех связанных портфолио, для которых Meta включила эту функцию.
- Бизнес-номер телефона не может использовать стандартный BSUID, привязанный к другому портфолио.
Перед началом работы
- Сохраните свой ключ API YCloud в
YCLOUD_API_KEY. - Используйте бизнес-номер WhatsApp, принадлежащий тому же портфолио, что и стандартный BSUID.
- Подпишите свою конечную точку Webhook на события WhatsApp, используемые вашей интеграцией.
- Считайте каждое новое поле BSUID, родительского BSUID, номера телефона и имени пользователя необязательным при десериализации Webhook.
- Храните стандартный BSUID и родительский BSUID независимо, если присутствуют оба.
Отправка сообщения с помощью BSUID
Обе конечные точки сообщений WhatsApp принимаютrecipient:
Укажите в
recipient стандартный BSUID или родительский BSUID. Опустите to, если хотите, чтобы YCloud обращался к пользователю по BSUID.
POST /whatsapp/messages, чтобы поставить сообщение в очередь.
Запрос номера телефона пользователя
Используйте сообщение с запросом контактных данных, когда вашему рабочему процессу требуется номер телефона, который не был передан в вебхуке. Пользователь сам решает, делиться ли им.Использование кнопки в шаблоне
Добавьте кнопкуREQUEST_CONTACT_INFO в сервисный или маркетинговый шаблон. Текст кнопки зафиксирован как Share Contact Info, и кнопка не принимает параметры во время отправки.
Использование интерактивного сообщения
Отправьте интерактивное сообщение типаrequest_contact_info, когда шаблон не требуется:
Обработка ответа с контактом
Когда пользователь делится контактной информацией, YCloud отправляет событиеwhatsapp.inbound_message.received, в котором поле сообщения type имеет значение contacts. В ответе на ваш запрос значением contacts[].origin будет contact_request.
2xx и обработайте номер телефона асинхронно. Контакт, отправленный напрямую из WhatsApp, также может содержать vCard.
Принцип работы адресной книги Meta
Адресная книга Meta хранит связку между номером телефона пользователя и BSUID. Если эта функция включена, отправка или получение сообщения либо звонка с использованием номера телефона пользователя сохраняет оба идентификатора. Затем Meta может передавать эту связку в вебхуках, даже если пользователь переключится на использование username. Адресные книги принадлежат отдельным бизнес-портфолио. Связанные портфолио не используют общие записи и не синхронизируют их: фиксируйте связку независимо в каждом портфолио. Meta сохраняет записи до тех пор, пока вы не отключите эту функцию или не деактивируете свой аккаунт. Отключить её можно в разделе Meta Business Suite > Настройки компании > Информация о компании. Отключение функции удаляет сохраненные записи и останавливает регистрацию новых. Повторное включение запускает сбор новых записей, но не восстанавливает удаленные данные.
Запросы контактов и локальное хранилище (Local Storage)
Когда пользователь делится своим номером телефона с помощью кнопки запроса контактных данных, Meta добавляет этот номер в адресную книгу, если функция активна. Для компаний, использующих Local Storage, Meta извлекает номер телефона из переданной vCard и сохраняет его в адресной книге в центрах обработки данных Meta. Остальные данные vCard не сохраняются дольше стандартного периода хранения. Meta отменила прежнее требование отправлять отдельное сообщение для фиксации этой связки. Информацию об актуальном поведении Local Storage см. в официальной документации по BSUID.Проверка записи в адресной книге Meta
ИспользуйтеGET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}, чтобы проверить, есть ли у Meta запись с номером телефона для стандартного BSUID. Эта операция не возвращает сам номер телефона и не изменяет запись.
403. WABA должен быть доступен вашему аккаунту, номер телефона должен быть привязан к этому WABA, а стандартный BSUID должен принадлежать тому же бизнес-портфолио Meta. Родительские BSUID, содержащие .ENT., не поддерживаются. При формировании пути вручную выполните URL-encoding начального символа + в номере телефона как %2B.
Успешный ответ всегда содержит логическое значение present:
200 со значением present: false указывает на отсутствие соответствующей записи. Некорректные входные данные, ошибки доступа и сбои вышестоящего сервиса по-прежнему считаются ошибками. Вышестоящий HTTP 404 не означает present: false.
Удаление записи из адресной книги Meta
Удалите запись из адресной книги Meta для стандартного BSUID через один рабочий номер телефона WhatsApp с помощью:DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}
.ENT., не поддерживаются. При формировании пути вручную выполните URL-encoding начального символа + в номере телефона как %2B.
Ответ HTTP 200 всегда содержит success: true. Значение deleted, равное true, означает, что Meta удалила соответствующую запись. Значение false означает, что Meta обработала запрос, но подходящей записи найдено не было.
Удаление записи не приводит к удалению контактов YCloud, сообщений или бизнес-записей BSUID. После удаления события вебхуков для рабочих номеров телефонов в том же бизнес-портфолио Meta больше не будут содержать номер телефона пользователя вместе с BSUID. 30-дневный кэш Meta по-прежнему может возвращать оба идентификатора, а последующее взаимодействие может создать запись в адресной книге заново.
Начало вызова с использованием BSUID
POST /whatsapp/calls/connect также принимает recipient. Применяются те же правила адресации: укажите to или recipient, при этом to имеет приоритет при наличии обоих полей.
Обработка полей вебхука для BSUID
В следующих полезных нагрузках Webhook от YCloud показаны поля, добавленные или измененные для поддержки BSUID. Обновите свой парсер, чтобы принимать новые идентификаторы и обрабатывать отсутствие номеров телефонов клиентов.
Примеры включают конверт событий YCloud и показывают расположение каждого поля. Необязательные поля следуют приведенным ниже правилам пропуска. Удалите комментарии
// <ADDED> и // <CHANGED> перед использованием полезной нагрузки в качестве тестовых данных JSON.
Применяйте следующие правила пропуска:
- Поле родительского BSUID отсутствует, если родительские BSUID не включены.
- Поле адресата отправленного сообщения или вызова может отсутствовать, если обращение к пользователю выполнялось по номеру телефона.
customerProfileприсутствует в обновлениях сообщений со статусамиsent,deliveredиread, но отсутствует в обновленияхfailed.customerProfile.usernameотсутствует, если пользователь не включил имена пользователей. Оно также отсутствует в обновлениях статусаsent.- Номер телефона может отсутствовать, даже если соответствующий BSUID присутствует.
whatsapp.message.updated
whatsapp.message.updated
В примере показано доставленное сообщение.
<CHANGED> помечает to как условное, когда номер телефона недоступен. Новый объект customerProfile опускается для failed; его поле username также опускается для sent или если у пользователя нет имени пользователя.whatsapp.inbound_message.received
whatsapp.inbound_message.received
Сохраняйте новые идентификаторы отправителя вместе с существующим именем профиля. Бизнес-получатель
to не меняется; номер телефона клиента from может быть опущен. Пример сообщения system со сменой номера телефона приведен ниже.whatsapp.user.preferences
whatsapp.user.preferences
Настройки остаются в объекте
whatsappUserPreference. Используйте предоставленные идентификаторы пользователя, даже если поле contactPhoneNumber отсутствует.whatsapp.call.connect
whatsapp.call.connect
Для вызовов, инициированных компанией, идентификаторами клиента являются
toUserId и toParentUserId. Для вызовов, инициированных пользователем, это fromUserId и fromParentUserId. В этих примерах может быть опущено только поле номера телефона клиента.- BUSINESS_INITIATED
- USER_INITIATED
whatsapp.call.terminate
whatsapp.call.terminate
Для вызовов, инициированных компанией, идентификаторами клиента являются
toUserId и toParentUserId. Для вызовов, инициированных пользователем, это fromUserId и fromParentUserId. В этих примерах может быть опущено только поле номера телефона клиента.- BUSINESS_INITIATED
- USER_INITIATED
whatsapp.call.status.updated
whatsapp.call.status.updated
Идентификаторы получателя находятся на одном уровне с
recipientPhone внутри callingStatusUpdated.whatsapp.group.participants_update
whatsapp.group.participants_update
Обновление одного участника может содержать идентификаторы непосредственно в
whatsappGroup. Результаты пакетных операций содержат их в каждом элементе массивов addedParticipants, removedParticipants или failedParticipants. Обрабатывайте массив, соответствующий операции в событии.- added
- removed
- failed
whatsapp.smb.history
whatsapp.smb.history
Сохраняйте специфическую для события обертку: входящая история использует
whatsappInboundMessage, а исходящая история — whatsappMessage. Поля исходящих сообщений toUserId и toParentUserId являются псевдонимами совместимости для recipientUserId и parentRecipientUserId. В этих примерах показаны события, содержащие сообщения; фрагмент истории, содержащий только метаданные, может опускать оба объекта сообщений.- Входящая история
- Исходящая история
whatsapp.smb.app.state.sync
whatsapp.smb.app.state.sync
Эта полезная нагрузка сохранена из устаревшей документации по миграции на BSUID. Это событие не указано в текущем публичном каталоге доступных для подписки событий; не добавляйте его в
enabledEvents на основе этого примера. Используйте приведенную ниже структуру при поддержке интеграции, которая уже получает эту устаревшую полезную нагрузку.whatsapp.smb.message.echoes
whatsapp.smb.message.echoes
Это сообщения, отправленные из приложения WhatsApp Business или с поддерживаемого сопутствующего устройства. Устаревшие имена полей
toUserId и toParentUserId являются псевдонимами совместимости для recipientUserId и parentRecipientUserId. Сохраняйте профиль в whatsappMessage.Обработка изменений номера телефона и BSUID
КогдаwhatsappInboundMessage.type имеет значение system, обрабатывайте оба варианта смены идентификационных данных:
Используйте
system.user_id и любое предоставленное значение system.parent_user_id для новой идентификационной информации. Используйте system.previous_user_id и system.previous_parent_user_id для предыдущей информации, если они предоставлены. Эти вложенные поля сохраняют исходные имена Meta в стиле snake_case.
В следующем примере показана смена номера телефона:
wa_id представляет собой номер телефона без начального + и может быть опущен; для user_changed_user_id он также может оставаться неизменным.
Не удаляйте существующий номер телефона только потому, что в событии он отсутствует. Сохраняйте прежние и новые идентификаторы достаточно долго, чтобы сопоставить существующие переписки и идемпотентно обновить хранилище идентификаторов.
См. раздел Входящее сообщение об изменении BSUID с примером без номера телефона.
Имена пользователей компании
Имя пользователя компании помогает клиентам находить вашу компанию в WhatsApp. Оно не скрывает номер телефона вашей компании. У каждого номера телефона может быть только одно имя пользователя, и одно имя пользователя не может использоваться одновременно двумя телефонными номерами WhatsApp. Имя пользователя клиента может меняться без изменения BSUID пользователя. Сохраняйте имя пользователя как информацию профиля, а не используйте его в качестве ключа идентификации. Правила формата длиной от 3 до 35 символов, а также процесс запроса и проверки описаны в разделе Запрос имени пользователя компании.
Зарезервированные имена пользователей
Вы можете запросить подходящее имя пользователя, зарезервированное Meta, или выбрать другое имя пользователя для своего бренда. Используйте WhatsApp Manager, Meta Business Suite или API для работы с именами пользователей. Само по себе одобрение не означает, что имя пользователя становится активным для клиентов. Если зарезервированное имя пользователя принадлежит вашей Странице Facebook или аккаунту Instagram, свяжите номер телефона вашей компании с этой Страницей или аккаунтом перед его запросом. Вы можете связать его в процессе запроса имени пользователя в Meta Business Suite или WhatsApp Manager, либо добавить номер телефона на Страницу или в аккаунт. Вам потребуется полный контроль или базовый частичный доступ с разрешениемmanage_phone.
Приоритет отображения в окне чата
WhatsApp отображает данные компании в следующем порядке:- Имя, сохраненное в контактах клиента.
- Подтвержденное название компании или название официального бизнес-аккаунта (Official Business Account).
- Имя пользователя компании.
- Номер телефона.
Контрольный список миграции
- Добавьте каждое поле вебхука, связанное с BSUID, в модель десериализации как необязательное поле.
- Храните обычные и родительские BSUID отдельно от номеров телефонов и имен пользователей.
- Индексируйте идентификаторы клиентов по портфелю и BSUID. Не рассматривайте BSUID как глобально переносимый идентификатор.
- Маршрутизируйте запросы сообщений и звонков через
toилиrecipientи протестируйте правило приоритетаto. - Протестируйте пользователей только с именами пользователей, отсутствие номеров телефонов, смену номеров телефонов, смену BSUID при неизменном номере телефона, отсутствие родительских BSUID, дубликаты вебхуков, а также наличие и повторное создание записей в адресной книге.
Примеры статусов сообщений
Проверьте полезную нагрузку отправленных, доставленных, прочитанных и завершившихся сбоем сообщений.
Примеры входящих сообщений
Проверьте полезную нагрузку контактов, системных обновлений и других входящих данных.

