Перейти к основному содержанию

Зачем нужны 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, которые необходимо сохранять вашей интеграции. Пример имени пользователя WhatsApp

Обзор идентификаторов

Meta генерирует стандартные BSUID автоматически. Каждый BSUID начинается с двухбуквенного кода страны пользователя по стандарту ISO 3166 alpha-2, за которым следуют точка и до 128 буквенно-цифровых символов. Сохраняйте значение целиком. Не удаляйте и не изменяйте префикс страны, точку или символы идентификатора. Для BSUID действуют следующие правила жизненного цикла:
  • BSUID уникален для пары «бизнес-портфолио — пользователь».
  • BSUID пользователя меняется при смене пользователем своего номера телефона.
  • Родительский BSUID работает во всех связанных портфолио, для которых Meta включила эту функцию.
  • Бизнес-номер телефона не может использовать стандартный BSUID, привязанный к другому портфолио.
Шаблоны аутентификации one-tap, zero-tap и copy-code требуют наличия номера телефона. Не отправляйте такие типы шаблонов, используя только BSUID.
Чтобы связать портфолио и использовать родительские BSUID, обратитесь к контактному лицу в Meta для проверки соответствия требованиям. Вы можете продолжать использовать стандартные BSUID в их исходных портфолио после того, как Meta включит родительские BSUID. Пример business-scoped user ID

Перед началом работы

  • Сохраните свой ключ 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 > Настройки компании > Информация о компании. Отключение функции удаляет сохраненные записи и останавливает регистрацию новых. Повторное включение запускает сбор новых записей, но не восстанавливает удаленные данные. Настройки адресной книги Meta

Запросы контактов и локальное хранилище (Local Storage)

Когда пользователь делится своим номером телефона с помощью кнопки запроса контактных данных, Meta добавляет этот номер в адресную книгу, если функция активна. Для компаний, использующих Local Storage, Meta извлекает номер телефона из переданной vCard и сохраняет его в адресной книге в центрах обработки данных Meta. Остальные данные vCard не сохраняются дольше стандартного периода хранения. Meta отменила прежнее требование отправлять отдельное сообщение для фиксации этой связки. Информацию об актуальном поведении Local Storage см. в официальной документации по BSUID.

Проверка записи в адресной книге Meta

Используйте GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}, чтобы проверить, есть ли у Meta запись с номером телефона для стандартного BSUID. Эта операция не возвращает сам номер телефона и не изменяет запись.
Используйте API-ключ вашего аккаунта YCloud. API-ключи Developer App возвращают HTTP 403. WABA должен быть доступен вашему аккаунту, номер телефона должен быть привязан к этому WABA, а стандартный BSUID должен принадлежать тому же бизнес-портфолио Meta. Родительские BSUID, содержащие .ENT., не поддерживаются. При формировании пути вручную выполните URL-encoding начального символа + в номере телефона как %2B. Успешный ответ всегда содержит логическое значение present:
HTTP 200 со значением present: false указывает на отсутствие соответствующей записи. Некорректные входные данные, ошибки доступа и сбои вышестоящего сервиса по-прежнему считаются ошибками. Вышестоящий HTTP 404 не означает present: false.

Удаление записи из адресной книги Meta

Удалите запись из адресной книги Meta для стандартного BSUID через один рабочий номер телефона WhatsApp с помощью: DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}
Используйте для этой операции стандартный BSUID. Родительские 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 имеет приоритет при наличии обоих полей.
Полный жизненный цикл совершения вызовов описан в разделе Управление звонками WhatsApp.

Обработка полей вебхука для BSUID

В следующих полезных нагрузках Webhook от YCloud показаны поля, добавленные или измененные для поддержки BSUID. Обновите свой парсер, чтобы принимать новые идентификаторы и обрабатывать отсутствие номеров телефонов клиентов. Примеры включают конверт событий YCloud и показывают расположение каждого поля. Необязательные поля следуют приведенным ниже правилам пропуска. Удалите комментарии // <ADDED> и // <CHANGED> перед использованием полезной нагрузки в качестве тестовых данных JSON. Применяйте следующие правила пропуска:
  • Поле родительского BSUID отсутствует, если родительские BSUID не включены.
  • Поле адресата отправленного сообщения или вызова может отсутствовать, если обращение к пользователю выполнялось по номеру телефона.
  • customerProfile присутствует в обновлениях сообщений со статусами sent, delivered и read, но отсутствует в обновлениях failed.
  • customerProfile.username отсутствует, если пользователь не включил имена пользователей. Оно также отсутствует в обновлениях статуса sent.
  • Номер телефона может отсутствовать, даже если соответствующий BSUID присутствует.
В примере показано доставленное сообщение. <CHANGED> помечает to как условное, когда номер телефона недоступен. Новый объект customerProfile опускается для failed; его поле username также опускается для sent или если у пользователя нет имени пользователя.
Сохраняйте новые идентификаторы отправителя вместе с существующим именем профиля. Бизнес-получатель to не меняется; номер телефона клиента from может быть опущен. Пример сообщения system со сменой номера телефона приведен ниже.
Настройки остаются в объекте whatsappUserPreference. Используйте предоставленные идентификаторы пользователя, даже если поле contactPhoneNumber отсутствует.
Для вызовов, инициированных компанией, идентификаторами клиента являются toUserId и toParentUserId. Для вызовов, инициированных пользователем, это fromUserId и fromParentUserId. В этих примерах может быть опущено только поле номера телефона клиента.
Для вызовов, инициированных компанией, идентификаторами клиента являются toUserId и toParentUserId. Для вызовов, инициированных пользователем, это fromUserId и fromParentUserId. В этих примерах может быть опущено только поле номера телефона клиента.
Идентификаторы получателя находятся на одном уровне с recipientPhone внутри callingStatusUpdated.
Обновление одного участника может содержать идентификаторы непосредственно в whatsappGroup. Результаты пакетных операций содержат их в каждом элементе массивов addedParticipants, removedParticipants или failedParticipants. Обрабатывайте массив, соответствующий операции в событии.
Сохраняйте специфическую для события обертку: входящая история использует whatsappInboundMessage, а исходящая история — whatsappMessage. Поля исходящих сообщений toUserId и toParentUserId являются псевдонимами совместимости для recipientUserId и parentRecipientUserId. В этих примерах показаны события, содержащие сообщения; фрагмент истории, содержащий только метаданные, может опускать оба объекта сообщений.
Эта полезная нагрузка сохранена из устаревшей документации по миграции на BSUID. Это событие не указано в текущем публичном каталоге доступных для подписки событий; не добавляйте его в enabledEvents на основе этого примера. Используйте приведенную ниже структуру при поддержке интеграции, которая уже получает эту устаревшую полезную нагрузку.
Это сообщения, отправленные из приложения 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. В следующем примере показана смена номера телефона:
Рассматривайте все поля идентификации как необязательные. Родительские BSUID передаются только тогда, когда они включены и доступны. 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 отображает данные компании в следующем порядке:
  1. Имя, сохраненное в контактах клиента.
  2. Подтвержденное название компании или название официального бизнес-аккаунта (Official Business Account).
  3. Имя пользователя компании.
  4. Номер телефона.
Номер телефона вашей компании остается видимым в профиле компании.

Контрольный список миграции

  1. Добавьте каждое поле вебхука, связанное с BSUID, в модель десериализации как необязательное поле.
  2. Храните обычные и родительские BSUID отдельно от номеров телефонов и имен пользователей.
  3. Индексируйте идентификаторы клиентов по портфелю и BSUID. Не рассматривайте BSUID как глобально переносимый идентификатор.
  4. Маршрутизируйте запросы сообщений и звонков через to или recipient и протестируйте правило приоритета to.
  5. Протестируйте пользователей только с именами пользователей, отсутствие номеров телефонов, смену номеров телефонов, смену BSUID при неизменном номере телефона, отсутствие родительских BSUID, дубликаты вебхуков, а также наличие и повторное создание записей в адресной книге.

Примеры статусов сообщений

Проверьте полезную нагрузку отправленных, доставленных, прочитанных и завершившихся сбоем сообщений.

Примеры входящих сообщений

Проверьте полезную нагрузку контактов, системных обновлений и других входящих данных.