Имена пользователей 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.
Когда BSUID начали появляться в вебхуках Cloud API, раньше, чем имена пользователей стали доступны пользователям WhatsApp.
Когда API начали принимать сообщения, отправленные на BSUID, который указывается в recipient вместо to.
Период давности, который отсчитывается отдельно для каждого номера телефона бизнеса: любое сообщение или звонок с пользователем в этот период сохраняет его номер в вебхуках.
Большинство буквенно-цифровых символов, которые идут после двухбуквенного кода страны и точки в BSUID.
Ошибка Messages API: «Business-scoped User ID (BSUID) recipients are not supported for this message.»
Тип системного сообщения о смене BSUID, переданный без номера телефона, со старым BSUID в previous_user_id.
Что такое имена пользователей WhatsApp и BSUID?
Имя пользователя является необязательным уникальным именем, которое пользователь WhatsApp может задать. Оно показывается в приложении вместо номера телефона, и в 2026 году Meta постепенно вводит имена пользователей. BSUID представляет собой внутренний идентификатор, который Meta добавила, чтобы бизнес мог по-прежнему различать пользователей: он создаётся автоматически, уникален для каждой пары «бизнес-портфолио и пользователь» и записывается как двухбуквенный код страны по ISO 3166, точка и до 128 буквенно-цифровых символов. Meta требует, чтобы партнёры и напрямую интегрированные бизнесы его поддерживали, поскольку ни один бизнес не контролирует, будут ли его пользователи переходить на имена пользователей.
Какие поля несут новые идентификаторы?
Новые свойства появляются рядом с полями, где раньше был номер телефона, во всех вебхуках messages, status, system и user_preferences. Родительские поля появляются только у бизнес-портфолио, которые Meta включила в родительские BSUID; они работают во всех включённых портфолио:
Когда номер телефона не передаётся?
Когда у пользователя есть имя и не выполняется ни одно из трёх условий Meta. Номер остаётся в вебхуках, если номер телефона бизнеса писал пользователю или звонил ему за последние 30 дней, получил от него сообщение или звонок за этот период либо пользователь находится в адресной книге портфолио. Период в 30 дней отсчитывается для каждого номера телефона бизнеса, поэтому второй номер того же портфолио может получить только BSUID того же пользователя. Пользователи без имени по-прежнему приходят и с номером телефона, и с BSUID.
Как выглядит входящее сообщение теперь?
Как и раньше, только BSUID стоит рядом с номером телефона или вместо него. В примере Meta для пользователя с именем, номер которого нельзя передать, в contacts приходят profile.name, profile.username и user_id, а в сообщении вместо прежнего from указано from_user_id:
{
"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.
{
"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.
А 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 за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.
Начать бесплатный пробный периодПроверено по состоянию на