Использование business-scoped user ID

Для чего нужны BSUID

В 2026 году WhatsApp внедряет необязательные имена пользователей. Когда пользователь выбирает имя пользователя, WhatsApp может отображать его вместо номера телефона и может не указывать номер телефона в полезных нагрузках Webhook. Каждый пользователь сам решает, использовать ли имя пользователя, поэтому компании больше не могут полагаться на номера телефонов как на единственный способ идентификации клиентов. По этой причине Meta требует от компаний и партнеров WhatsApp Business Platform, а также от рекламодателей click-to-WhatsApp поддерживать BSUID, чтобы продолжать обрабатывать сообщения от пользователей, использующих имена пользователей. Чтобы поддержать это изменение, в начале апреля 2026 года Meta начала добавлять business-scoped user ID (BSUID) в полезные нагрузки Webhook. BSUID — это внутренний идентификатор пользователя WhatsApp в рамках одного бизнес-портфолио Meta. Meta включает его в Webhook сообщений независимо от того, выбрал ли пользователь имя пользователя, и его можно использовать для отправки сообщений, когда номер телефона пользователя недоступен. Имена пользователей и BSUID имеют разный жизненный цикл. Пользователь может изменить свое имя пользователя, не меняя номер телефона или BSUID. Если пользователь меняет номер телефона, Meta генерирует новый BSUID. Храните эти идентификаторы отдельно и обновляйте их связь при получении системного события об изменении номера телефона. Номер телефона все еще может отображаться, если с бизнес-номера телефона отправлялись сообщения или совершались звонки этому пользователю в течение последних 30 дней, либо если пользователь есть в адресной книге Meta. Относитесь к полям номера телефона и имени пользователя как к условным и обновите парсеры и хранилище идентификаторов для поддержки BSUID наряду с любыми другими присутствующими идентификаторами. В этом руководстве рассматриваются правила идентификации BSUID, запросы на отправку сообщений и звонков, адресная книга Meta и поля Webhook, которые необходимо сохранять вашей интеграции. Пример имени пользователя WhatsApp

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

Идентификатор	Область действия	Пример	Когда использовать
Номер телефона	Один аккаунт WhatsApp	`+16315551111`	Используйте, когда номер телефона доступен и операция требует его наличия.
BSUID	Одно бизнес-портфолио Meta и один пользователь WhatsApp	`US.13491208655302741918`	Используйте с любого бизнес-номера телефона в том же портфолио.
Родительский BSUID	Набор связанных бизнес-портфолио Meta и один пользователь WhatsApp	`US.ENT.11815799212886844830`	Используйте только после того, как Meta включит родительские BSUID для связанных портфолио.

Meta генерирует обычные BSUID автоматически. Каждый BSUID начинается с двухбуквенного кода страны пользователя по стандарту ISO 3166 alpha-2, за которым следуют точка и до 128 буквенно-цифровых символов. Сохраняйте значение целиком. Не удаляйте и не изменяйте префикс страны, точку или символы идентификатора. К BSUID применяются следующие правила жизненного цикла:

BSUID уникален для пары «бизнес-портфолио — пользователь».
BSUID пользователя меняется, когда пользователь меняет свой номер телефона.
Родительский BSUID работает во всех связанных портфолио, для которых Meta включила эту функцию.
Бизнес-номер телефона не может использовать обычный BSUID, привязанный к другому портфолио.

Шаблоны аутентификации в одно касание (one-tap), без касания (zero-tap) и с копированием кода требуют наличия номера телефона. Не отправляйте эти типы шаблонов, указывая только BSUID.

Чтобы связать портфолио и использовать родительские BSUID, обратитесь к контактному лицу в Meta для проверки соответствия требованиям. После того как Meta включит родительские BSUID, вы сможете продолжить использовать обычные BSUID в их исходных портфолио. Пример business-scoped user ID

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

Сохраните свой API-ключ YCloud в YCLOUD_API_KEY.
Используйте бизнес-номер телефона WhatsApp, принадлежащий тому же портфолио, что и обычный BSUID.
Подпишите конечную точку вашего Webhook на события WhatsApp, которые используются вашей интеграцией.
Считайте каждое новое поле BSUID, родительского BSUID, номера телефона и имени пользователя необязательным при десериализации Webhook.
Сохраняйте обычный BSUID и родительский BSUID раздельно, если присутствуют оба.

Отправка сообщения с помощью BSUID

Обе конечные точки сообщений WhatsApp принимают recipient:

Конечная точка	Поведение
`POST /whatsapp/messages/sendDirectly`	Отправляет сообщение синхронно в WhatsApp Business API.
`POST /whatsapp/messages`	Помещает сообщение в очередь для асинхронной отправки.

Задайте в recipient обычный BSUID или родительский BSUID. Опустите to, если хотите, чтобы YCloud адресовал сообщение пользователю по BSUID.

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "type": "text",
    "text": {
      "body": "Hello from YCloud!"
    }
  }'

Используйте то же тело запроса с POST /whatsapp/messages, чтобы поставить сообщение в очередь.

Входные данные	Результат
Только `to`	YCloud отправляет на номер телефона.
Только `recipient`	YCloud отправляет на BSUID или родительский BSUID.
И `to`, и `recipient`	YCloud использует `to` и игнорирует `recipient`.
Ни одно поле	YCloud отклоняет запрос.

Запрос номера телефона пользователя

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

Использование кнопки шаблона

Добавьте кнопку REQUEST_CONTACT_INFO в сервисный или маркетинговый шаблон. Текст кнопки фиксирован: Share Contact Info, и кнопка не принимает параметры во время отправки.

{
  "type": "buttons",
  "buttons": [
    {
      "type": "REQUEST_CONTACT_INFO",
      "text": "Share Contact Info"
    }
  ]
}

Создайте и согласуйте шаблон перед его отправкой. Пример полного запроса шаблона см. в разделе Request phone number template.

Использование интерактивного сообщения

Отправьте интерактивное сообщение request_contact_info, если шаблон не требуется:

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "type": "interactive",
    "interactive": {
      "type": "request_contact_info",
      "body": {
        "text": "Please share your phone number."
      },
      "action": {
        "name": "request_contact_info"
      }
    }
  }'

Обработка ответа с контактом

Когда пользователь делится контактной информацией, YCloud отправляет событие whatsapp.inbound_message.received, в котором сообщение type имеет тип contacts. В качестве ответа на ваш запрос поле contacts[].origin содержит значение contact_request.

{
  "type": "whatsapp.inbound_message.received",
  "whatsappInboundMessage": {
    "fromUserId": "US.13491208655302741918",
    "type": "contacts",
    "contacts": [
      {
        "origin": "contact_request",
        "phones": [
          {
            "phone": "+16315551111",
            "wa_id": "16315551111"
          }
        ]
      }
    ]
  }
}

Проверьте подпись события, подтвердите его получение ответом 2xx и обработайте номер телефона асинхронно. Контакт, отправленный напрямую из WhatsApp, также может содержать vCard. Кнопка запроса контактной информации

Принцип работы адресной книги Meta

Адресная книга Meta хранит связь между номером телефона пользователя и BSUID. Если эта функция включена, при отправке или получении сообщения или вызова с использованием номера телефона пользователя сохраняются оба идентификатора. Затем Meta может передавать эту связь в Webhook, даже если пользователь установит себе имя пользователя. Адресные книги принадлежат отдельным бизнес-портфолио. Связанные портфолио не используют общие записи и не синхронизируют их: связь должна фиксироваться независимо в каждом портфолио. Meta сохраняет записи до тех пор, пока вы не отключите эту функцию или не деактивируете свою учетную запись. Отключить ее можно в меню Meta Business Suite > Настройки компании > Информация о компании. Отключение функции удаляет сохраненные записи и останавливает сохранение новых. При повторном включении начнется сбор новых записей, но удаленные данные восстановлены не будут. Настройки адресной книги Meta

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

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

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

Удалите запись из адресной книги Meta для обычного BSUID через один бизнес-номер WhatsApp с помощью: DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}

curl --request DELETE \
  "https://api.ycloud.com/v2/whatsapp/phoneNumbers/WABA_ID/%2B16315551111/contactBook/US.13491208655302741918" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Accept: application/json"

Для этой операции используйте стандартный BSUID. Родительские BSUID, содержащие .ENT., не поддерживаются. При формировании пути вручную выполните URL-кодирование ведущего знака + в номере телефона как %2B. HTTP-ответ 200 всегда содержит success: true. Значение deleted, равное true, означает, что Meta удалила соответствующую запись. Значение false означает, что Meta обработала запрос, но подходящая запись не была найдена. Удаление записи не удаляет контакты, сообщения или бизнес-записи BSUID в YCloud. После удаления события Webhook для бизнес-номеров телефонов в том же бизнес-портфолио Meta больше не содержат одновременно номер телефона пользователя и BSUID. 30-дневный кэш Meta все еще может предоставлять оба идентификатора, а при последующем взаимодействии запись в адресной книге может быть создана повторно.

Совершение вызова с помощью BSUID

POST /whatsapp/calls/connect также принимает recipient. Применяются те же правила выбора цели: укажите to или recipient, при этом to имеет приоритет, если указаны оба параметра.

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/calls/connect \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "recipient": "US.13491208655302741918",
    "sdpType": "offer",
    "sdp": "SDP_OFFER"
  }'

Полный жизненный цикл звонков см. в разделе Управление звонками WhatsApp.

Обработка полей BSUID в Webhook

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

Событие	Необязательные поля для сохранения
`whatsapp.message.updated`	`whatsappMessage.recipientUserId`, `whatsappMessage.parentRecipientUserId`, `whatsappMessage.customerProfile.name`, `whatsappMessage.customerProfile.username`
`whatsapp.inbound_message.received`	`whatsappInboundMessage.fromUserId`, `whatsappInboundMessage.fromParentUserId`, `whatsappInboundMessage.customerProfile.username`
`whatsapp.user.preferences`	`whatsappUserPreference.userId`, `whatsappUserPreference.parentUserId`
`whatsapp.call.connect`	`callingConnect.toUserId`, `callingConnect.toParentUserId`, `callingConnect.fromUserId`, `callingConnect.fromParentUserId`
`whatsapp.call.terminate`	`callingTerminate.toUserId`, `callingTerminate.toParentUserId`, `callingTerminate.fromUserId`, `callingTerminate.fromParentUserId`
`whatsapp.call.status.updated`	`callingStatusUpdated.recipientUserId`, `callingStatusUpdated.parentRecipientUserId`
`whatsapp.group.participants_update`	`whatsappGroup.recipientUserId`, `whatsappGroup.parentRecipientUserId`, `whatsappGroup.customerProfile.username`, а также поля `recipientUserId` и `parentRecipientUserId` в `whatsappGroup.addedParticipants[]`, `whatsappGroup.removedParticipants[]` и `whatsappGroup.failedParticipants[]`
`whatsapp.smb.history`	`whatsappInboundMessage.fromUserId`, `whatsappInboundMessage.fromParentUserId`, `whatsappInboundMessage.customerProfile.username`, `whatsappMessage.toUserId`, `whatsappMessage.toParentUserId`
`whatsapp.smb.app.state.sync`	`whatsappSmbAppStateSync.stateSync[].contact.userId`, `whatsappSmbAppStateSync.stateSync[].contact.parentUserId`, `whatsappSmbAppStateSync.stateSync[].contact.username`
`whatsapp.smb.message.echoes`	`whatsappMessage.toUserId`, `whatsappMessage.toParentUserId`, `whatsappMessage.customerProfile.username`

Применяйте следующие правила отсутствия полей:

Поле родительского BSUID отсутствует, если родительские BSUID не включены.
Поле адресата отправленного сообщения или вызова может отсутствовать, если обращение к пользователю происходило по номеру телефона.
customerProfile появляется в обновлениях сообщений sent, delivered и read, но отсутствует в обновлениях failed.
customerProfile.username отсутствует, если пользователь не включил имена пользователей. Оно также отсутствует в обновлениях статуса sent.
Номер телефона может отсутствовать, даже когда присутствует соответствующий BSUID.

Обработка смены номера телефона пользователем

Если входящее сообщение содержит type: system и system.type: user_changed_number, замените старую привязку идентификатора новыми значениями. Имена полей BSUID в объекте system остаются в формате snake_case от Meta.

{
  "type": "system",
  "system": {
    "type": "user_changed_number",
    "wa_id": "16315552222",
    "user_id": "US.13491208655302741919",
    "parent_user_id": "US.ENT.11815799212886844831"
  }
}

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

Имена пользователей компании

Имя пользователя компании помогает клиентам находить вашу компанию в WhatsApp. Оно не скрывает номер телефона вашей компании. К каждому номеру телефона может быть привязано только одно имя пользователя, и одно имя пользователя нельзя использовать для двух телефонных номеров WhatsApp. Имя пользователя клиента может измениться без изменения его BSUID. Храните имя пользователя как данные профиля, а не используйте его в качестве ключа идентификации. Смотрите раздел Запрос имени пользователя компании, чтобы узнать правила формата (от 3 до 35 символов), а также процесс подачи заявки и проверки. Пример имени пользователя компании

Зарезервированные имена пользователей

Вы можете запросить подходящее имя пользователя, зарезервированное Meta, или выбрать другое имя пользователя для вашего бренда. Используйте WhatsApp Manager, Meta Business Suite или API имен пользователей. Одобрение само по себе не означает, что имя пользователя станет активным для клиентов. Если зарезервированное имя пользователя принадлежит вашей Странице Facebook или аккаунту Instagram, свяжите номер телефона вашей компании с этой Страницей или аккаунтом перед подачей заявки. Вы можете привязать его во время запроса имени пользователя в Meta Business Suite или WhatsApp Manager либо добавить номер телефона на Страницу или в аккаунт. Вам потребуется полный контроль или базовый частичный доступ с разрешением manage_phone.

Приоритет отображения в окне чата

WhatsApp отображает информацию о компании в следующем порядке:

Имя, сохраненное в контактах клиента.
Подтвержденное название компании или имя официального бизнес-аккаунта.
Имя пользователя компании.
Номер телефона.

Номер телефона вашей компании остается видимым в профиле компании.

Чек-лист по миграции

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

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

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

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

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

Начало работы

Руководства

Конечные точки

Webhooks

Использование business-scoped user ID

Для чего нужны BSUID

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

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

Отправка сообщения с помощью BSUID

Запрос номера телефона пользователя

Использование кнопки шаблона

Использование интерактивного сообщения

Обработка ответа с контактом

Принцип работы адресной книги Meta

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

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

Совершение вызова с помощью BSUID

Обработка полей BSUID в Webhook

Обработка смены номера телефона пользователем

Имена пользователей компании

Зарезервированные имена пользователей

Приоритет отображения в окне чата

Чек-лист по миграции

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

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

​Для чего нужны BSUID

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

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

​Отправка сообщения с помощью BSUID

​Запрос номера телефона пользователя

​Использование кнопки шаблона

​Использование интерактивного сообщения

​Обработка ответа с контактом

​Принцип работы адресной книги Meta

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

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

​Совершение вызова с помощью BSUID

​Обработка полей BSUID в Webhook

​Обработка смены номера телефона пользователем

​Имена пользователей компании

​Зарезервированные имена пользователей

​Приоритет отображения в окне чата

​Чек-лист по миграции

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

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

Для чего нужны BSUID

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

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

Отправка сообщения с помощью BSUID

Запрос номера телефона пользователя

Использование кнопки шаблона

Использование интерактивного сообщения

Обработка ответа с контактом

Принцип работы адресной книги Meta

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

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

Совершение вызова с помощью BSUID

Обработка полей BSUID в Webhook

Обработка смены номера телефона пользователем

Имена пользователей компании

Зарезервированные имена пользователей

Приоритет отображения в окне чата

Чек-лист по миграции