ВойтиНачать бесплатный пробный период
Meta Tech Provider

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

Имена пользователей WhatsApp позволяют показывать имя вместо номера телефона, поэтому с начала апреля 2026 года вебхуки сообщений Cloud API также передают идентификатор пользователя в рамках бизнеса (BSUID), например US.13491208655302741918, в полях user_id и from_user_id. Если у пользователя есть имя, за 30 дней с этим номером не было ни одного сообщения или звонка и он не находится в адресной книге, поля wa_id и from не передаются.

easyCoexistence подключает номер приложения WhatsApp Business к Cloud API через Coexistence и направляет вебхуки messages и smb_message_echoes на ваш эндпоинт так, как их отправляет Meta, включая поля BSUID.

April 2026

Когда BSUID начали появляться в вебхуках Cloud API, раньше, чем имена пользователей стали доступны пользователям WhatsApp.

July 2026

Когда API начали принимать сообщения, отправленные на BSUID, который указывается в recipient вместо to.

30 days

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

128

Большинство буквенно-цифровых символов, которые идут после двухбуквенного кода страны и точки в BSUID.

131062

Ошибка Messages API: «Business-scoped User ID (BSUID) recipients are not supported for this message.»

user_changed_user_id

Тип системного сообщения о смене BSUID, переданный без номера телефона, со старым BSUID в previous_user_id.

Что такое имена пользователей WhatsApp и BSUID?

Имя пользователя является необязательным уникальным именем, которое пользователь WhatsApp может задать. Оно показывается в приложении вместо номера телефона, и в 2026 году Meta постепенно вводит имена пользователей. BSUID представляет собой внутренний идентификатор, который Meta добавила, чтобы бизнес мог по-прежнему различать пользователей: он создаётся автоматически, уникален для каждой пары «бизнес-портфолио и пользователь» и записывается как двухбуквенный код страны по ISO 3166, точка и до 128 буквенно-цифровых символов. Meta требует, чтобы партнёры и напрямую интегрированные бизнесы его поддерживали, поскольку ни один бизнес не контролирует, будут ли его пользователи переходить на имена пользователей.

Какие поля несут новые идентификаторы?

Новые свойства появляются рядом с полями, где раньше был номер телефона, во всех вебхуках messages, status, system и user_preferences. Родительские поля появляются только у бизнес-портфолио, которые Meta включила в родительские BSUID; они работают во всех включённых портфолио:

contacts[].user_idThe user's BSUID, in incoming messages and in sent, delivered and read statuses
messages[].from_user_idThe sender's BSUID, beside from
contacts[].profile.usernameThe username, when the user has one; never on sent statuses
statuses[].recipient_user_idThe recipient's BSUID, unless a send to a phone number failed
parent_user_idA parent BSUID shared by enrolled portfolios, such as US.ENT.11815799212886844830
wa_id, from, recipient_idNow left out when the phone number cannot be shared

Когда номер телефона не передаётся?

Когда у пользователя есть имя и не выполняется ни одно из трёх условий Meta. Номер остаётся в вебхуках, если номер телефона бизнеса писал пользователю или звонил ему за последние 30 дней, получил от него сообщение или звонок за этот период либо пользователь находится в адресной книге портфолио. Период в 30 дней отсчитывается для каждого номера телефона бизнеса, поэтому второй номер того же портфолио может получить только BSUID того же пользователя. Пользователи без имени по-прежнему приходят и с номером телефона, и с BSUID.

Как выглядит входящее сообщение теперь?

Как и раньше, только BSUID стоит рядом с номером телефона или вместо него. В примере Meta для пользователя с именем, номер которого нельзя передать, в contacts приходят profile.name, profile.username и user_id, а в сообщении вместо прежнего from указано from_user_id:

messages webhook: a text from a user known only by BSUID
{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "102290129340398",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
        "contacts": [{
          "profile": { "name": "Sheena Nelson", "username": "realsheenanelson" },
          "user_id": "US.13491208655302741918"
        }],
        "messages": [{
          "from_user_id": "US.13491208655302741918",
          "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
          "timestamp": "1749416383",
          "type": "text",
          "text": { "body": "Does it come in another color?" }
        }]
      }
    }]
  }]
}

Как меняются вебхуки статусов?

Статусы «отправлено», «доставлено» и «прочитано» получают массив contacts с именем пользователя, user_id, wa_id, если номер можно передать, и username для статусов «доставлено» и «прочитано». В статусах recipient_user_id содержит BSUID, а recipient_id не передаётся, если вы отправили сообщение на BSUID и номер нельзя передать. У статуса «ошибка» нет массива contacts, и он не содержит recipient_user_id, если сообщение было отправлено на номер телефона, поэтому сопоставляйте сбои по id сообщения.

Как хранить пользователей и сопоставлять их?

В первую очередь по BSUID, а номер телефона использовать как второй ключ, когда он приходит. Храните BSUID целиком, как строку, вместе с кодом страны и точкой, так как Meta отклоняет запросы, которые меняют любую его часть, и сохраняйте родительский BSUID, если ваши портфолио включены в программу. Сопоставляйте существующие записи по wa_id, пока он приходит, и храните BSUID рядом с ними, потому что пользователь, который позже введёт имя, может вернуться без номера. В FAQ Meta рекомендуется такое же сопоставление в CRM и подключённых к ним инструментах.

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

Его BSUID пересоздаётся, и изменение приходит в поле messages как системное сообщение, так как у Meta нет поля user_id_update для подписки. system.type равен user_changed_number, если новый номер можно передать вам, или user_changed_user_id, если можно передать только изменение BSUID; system.user_id содержит новый BSUID, а system.previous_user_id старый, и по нему запись переносится. Обрабатывайте оба типа.

Как ответить пользователю, известному только по BSUID?

Отправляйте на /<BUSINESS_PHONE_NUMBER_ID>/messages с recipient, равным BSUID, и без to; если заполнены оба поля, приоритет у to, и ответ уходит на номер телефона. Тогда запись contacts в ответе содержит input и user_id вместо wa_id. Работают любые типы сообщений, кроме шаблонов аутентификации «одним нажатием», «без нажатия» и «с кодом для копирования»: им нужен номер телефона. Достичь BSUID могут только номера из того же бизнес-портфолио. Ошибка 131062 означает, что этот тип сообщения не принимает получателей с BSUID.

POST /<BUSINESS_PHONE_NUMBER_ID>/messages, sent to a BSUID
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "recipient": "US.13491208655302741918",
  "type": "text",
  "text": { "body": "Yes, it also comes in blue." }
}

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

С помощью кнопки REQUEST_CONTACT_INFO, добавленной в шаблон утилиты или маркетинговый шаблон, либо отправленной как интерактивное сообщение типа request_contact_info. Пользователь, нажавший кнопку, передаёт свой номер в переписке, и приходит вебхук contacts с origin, равным contact_request, и номером в phones[].wa_id; контакт, отправленный вручную, приходит с origin, равным other, и vCard. Meta сделала кнопку доступной в начале июля 2026 года, и её надпись нельзя изменить.

Что такое адресная книга?

Это хранилище, которое Meta ведёт для каждого бизнес-портфолио без дополнительной интеграции: как только номер телефона бизнеса отправляет сообщение, звонит или получает сообщение или звонок с номера пользователя, этот номер и BSUID записываются и используются для заполнения последующих вебхуков номером телефона, независимо от наличия имени. Учитываются только взаимодействия после запуска. Её можно отключить в Meta Business Suite: «Настройки бизнеса», «Информация о бизнесе»; при этом удаляются все её данные. Запросы GET или DELETE к /<BUSINESS_PHONE_NUMBER_ID>/contact_book с параметром bsuid проверяют или удаляют одну запись.

Что должна изменить интеграция Coexistence?

Обработку трёх вебхуков, которые получают только номера в режиме Coexistence, тоже нужно изменить. В history каждая переписка получает объект context с wa_id, user_id и username, а её сообщения получают from_user_id. В smb_message_echoes добавляется массив contacts, поле message_echoes[].to может отсутствовать, а to_user_id содержит BSUID; правки и удаления, сделанные в приложении WhatsApp Business, приходят так же. В smb_app_state_sync поле phone_number контакта может отсутствовать, рядом с ним указаны user_id и username. Сопоставляйте эхо-сообщения и импортированные чаты по user_id в дополнение к номеру.

Как протестировать до того, как пользователи начнут использовать имена?

Инструментом тестирования Meta в App Dashboard: в разделе «Use cases», «Connect with customers through WhatsApp», «Customize», «Configuration» ссылка Test рядом с вебхуком messages отправляет пример на ваш эндпоинт. Он охватывает входящие сообщения и статусы в четырёх сценариях:

  • Пользователь без имени: поля BSUID и номера телефона, без username.
  • Пользователь с именем, номер которого недоступен: username и BSUID, без полей номера телефона.
  • Пользователь с именем, номер которого доступен: username, BSUID и номер телефона.
  • Портфолио, включённое в родительские BSUID: родительский BSUID рядом с собственным BSUID портфолио.

Как easyCoexistence работает с BSUID?

Передаёт их так, как их отправляет Meta. Номер, направленный на ваш эндпоинт через set_webhook_destination, получает вебхуки messages и smb_message_echoes напрямую от Meta, включая user_id, from_user_id, to_user_id и username; при включённых автоматизациях или пересылке easyCoexistence пересылает значение, отправленное Meta, без изменений. Чтобы ответить на BSUID, ваш код использует get_api_credentials, который возвращает ID номера телефона, его эндпоинт отправки и, если доступно, ваш собственный токен; инструменты send_message и send_template принимают номер телефона в международном формате, только цифрами.

Распространённые ошибки

  • Привязка контактов только к wa_id. Пользователь с именем, у которого за 30 дней не было контакта с номером, приходит только с user_id и from_user_id, и обработчик, требующий wa_id, пропускает сообщение.
  • Обрезка кода страны в BSUID. Meta требует передавать значение целиком, с кодом страны и точкой, и запрос с любой изменённой частью завершается ошибкой.
  • Ожидание поля user_id_update. У Meta его нет: изменения BSUID приходят в messages как системные сообщения типов user_changed_number или user_changed_user_id.
  • Сопоставление эхо Coexistence только по to. В smb_message_echoes поле to может отсутствовать, поэтому ответ, набранный в приложении, останется незамеченным, если не сопоставлять и to_user_id.
Настройка с EasyCoexistence

А get_api_credentials даёт вашему коду всё необходимое, чтобы отвечать с recipient. Каждое подключение находится под мониторингом 24/7. От US$ 9 до US$ 0,75 за подключение в месяц, со снижением по мере добавления подключений, первые 3 дня бесплатно.

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

Получают ли BSUID пользователи без имени?

Да. Meta задаёт user_id в вебхуках messages независимо от наличия имени у пользователя, поэтому большинство пользователей приходят и с номером телефона, и с BSUID.

Может ли номер в режиме Coexistence иметь имя бизнеса?

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

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

Нет. BSUID принадлежит одному портфолио и одному пользователю, и номер из другого портфолио не может ему написать. Управляемые бизнесы, которые Meta включает в программу, получают родительские BSUID с ENT после кода страны; они работают во всех включённых портфолио.

Сколько стоит easyCoexistence для номера WhatsApp?

От US$ 9 до US$ 0,75 за подключение в месяц в зависимости от количества подключений; первые 3 дня бесплатно. Собственные платы Meta за сообщения остаются на способе оплаты вашего аккаунта WhatsApp Business.

Читайте дальше

Готовы начать?

Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.

Начать бесплатный пробный период

Проверено по состоянию на