Идентификаторы пользователей с бизнес-целями | Документация для разработчиков
Идентификаторы пользователей с бизнес-целями
Обновлено: 31 марта 2026 г
Данный документ был существенно обновлен 18 марта 2026 года. Подробности в журнале изменений
WhatsApp планирует запустить функцию присвоения имен пользователям в конце 2026 года.
Имена пользователей — это дополнительная функция для пользователей и компаний. Если пользователь WhatsApp использует имя пользователя, вместо номера телефона в приложении будет отображаться его имя пользователя. Однако имена пользователей для компаний не предназначены для обеспечения конфиденциальности. Использование имени пользователя для компании не приведет к скрытию номера телефона вашей компании в приложении.
Для поддержки имен пользователей Meta будет использовать новый идентификатор пользователя в бэкэнде, называемый идентификатором пользователя с привязкой к бизнесу (business-scoped user ID, или BSUID). BSUID однозначно идентифицирует пользователя WhatsApp и привязан к конкретной компании.
В этом документе описывается, как добавление имен пользователей повлияет на запросы API, ответы API и полезные нагрузки веб-хуков. Дополнительные изменения, необходимые для поддержки имен пользователей до того, как эта функция станет доступна, будут зафиксированы здесь.
Любые изменения, описанные в этом документе, могут быть внесены.
Имена пользователей
Имя пользователя — это уникальное, необязательное имя, которое пользователи WhatsApp могут установить, чтобы в приложении отображалось их имя пользователя вместо номера телефона. Имена пользователей можно использовать вместо имен профилей при персонализации содержимого сообщений для отдельных пользователей.
Пользователи WhatsApp могут использовать только одно имя пользователя, но периодически менять его. Изменение имени пользователя не влияет на номер телефона пользователя или идентификатор пользователя, привязанный к бизнес-аккаунту, а также не влияет на возможность пользователя общаться с другими пользователями WhatsApp или компаниями на платформе WhatsApp Business. К именам пользователей применяются те же ограничения по формату, что и к бизнес-именам пользователей .
Имена пользователей присваиваются
username в ответах API и полезных нагрузках вебхуков. После включения имя пользователя WhatsApp будет отображаться во всех вебхуках входящих сообщений , а также во всех доставленных и прочитанных сообщений о статусе .Идентификатор пользователя с бизнес-областью
Идентификаторы BSUID начнут появляться в веб-хуках в начале апреля 2026 года.
BSUID — это уникальный идентификатор пользователя, который можно использовать для отправки сообщений пользователю WhatsApp, если вам неизвестен его номер телефона. BSUID будет присвоен параметру
user_id и будет отображаться во всех веб-хуках сообщений , независимо от того, включена ли функция указания имени пользователя или нет.Идентификаторы BSUID привязаны к отдельным бизнес-портфелям. Это означает, что любой номер телефона компании, принадлежащий данному портфелю, может быть использован для отправки сообщения с идентификатором BSUID, привязанным к тому же портфелю, а попытки отправить сообщение с использованием номера телефона, принадлежащего другому портфелю, завершатся неудачей.
Идентификаторы BSUID будут следующими:
сгенерировано автоматически двухбуквенного пользователя по стандарту ISO 3166 alpha-2 и точки, за которым следуют до 128 буквенно-цифровых символов (например, US.13491208655302741918 ).Уникальные для каждой пары «бизнес-портфель — пользователь» ( ранее бизнес-портфели назывались «бизнес-менеджерами»).Создаётся заново, если пользователь меняет свой номер телефона (что запускает веб-перехватчик системных сообщений о состоянии ).
шаблонов аутентификации с одним касанием, без касания и копирования кода , для которых требуются номера телефонов пользователей.
При отправке API-запросов с использованием BSUID, указывайте полное значение BSUID: код страны, точку и все буквенно-цифровые символы. Отсутствие или изменение кода страны, точки или буквенно-цифровых символов приведет к ошибке запроса.
Если вы являетесь управляемой компанией с несколькими бизнес-портфелями и хотите использовать BSUID, которые будут работать во всех из них, см. раздел « Идентификаторы пользователей, относящиеся к родительскому бизнесу» .
Идентификаторы родительских пользователей, относящиеся к бизнес-задачам
Если вы являетесь управляемой компанией и хотите связать бизнес-портфели, вы можете обратиться к своему контактному лицу в Meta, чтобы проверить, соответствуете ли вы требованиям. Если вы соответствуете требованиям и ваши бизнес-портфели будут связаны, родительские BSUID будут включены во все веб-хуки сообщений и присвоены новому
parent_user_id .Родительские BSUID можно использовать вместо обычных BSUID для отправки сообщений пользователям. Функционально родительские BSUID обладают теми же свойствами, что и обычные BSUID, но могут использоваться для любого номера телефона компании в наборе связанных портфелей. Родительские BSUID имеют тот же формат, что и обычные BSUID, но включают
ENT между кодом страны и буквенно-цифровым идентификатором (например, US.ENT.11815799212886844830 ).Обратите внимание, что вы по-прежнему можете отправлять сообщения пользователям, используя их обычный BSUID, привязанный к вашему бизнес-портфелю.
Номера телефонов
Если пользователь WhatsApp включает функцию указания имени пользователя, его номер телефона не будет включаться в веб-хуки, если вы ранее не взаимодействовали с этим пользователем, как объяснено ниже. Поэтому, независимо от того, включил ли пользователь эту функцию или нет, BSUID пользователя будет включен в любые веб-хуки, которые обычно содержат его номер телефона, и будет присвоен новому свойству user_id.
Чтобы уменьшить вероятность потери контекста разговора с существующими пользователями, которые включили функцию имен пользователей, номера телефонов пользователей будут включаться в веб-хуки, если выполняется любое из следующих условий:
Вы отправляли сообщение или звонили на номер телефона пользователя в течение последних 30 дней до срабатывания веб-хукаВы получали сообщение или звонок с номера телефона пользователя в течение последних 30 дней с момента срабатывания веб-хукаПользователь находится в вашей книге контактов.
Обратите внимание, что указанные выше условия 30-дневного периода проверки оцениваются для каждого корпоративного номера телефона. Если вы отправляете сообщение пользователю с одного из ваших корпоративных номеров телефонов, веб-хуки, связанные с другим корпоративным номером телефона в вашем портфеле, не будут включать номер телефона пользователя, если только этот конкретный номер также не отправлял или не получал сообщения или звонки на номер телефона пользователя или с него в течение последних 30 дней.
Идентификаторы BSUID начнут отображаться в веб-хуках в начале апреля 2026 года. Однако наши API не будут поддерживать отправку сообщений, адресованных пользователям с BSUID, до мая 2026 года (точная дата уточняется). Как только наши API начнут поддерживать BSUID в мае, вы сможете отправлять сообщения пользователям, используя их BSUID, номер телефона или и то, и другое.
Если вы являетесь поставщиком решений и предоставляете своим корпоративным клиентам услуги обмена сообщениями через WhatsApp, ваши клиенты смогут использовать ваше приложение для отправки сообщений другим пользователям, используя номера телефонов своих корпоративных портфелей и любые BSUID, привязанные к их портфелю. Однако, если вы попытаетесь использовать один из BSUID вашего корпоративного клиента с вашим собственным номером телефона, это не удастся, поскольку BSUID привязаны к портфелям (и, по сути, к активам, которыми владеет портфель).
Если вы не уверены в принадлежности актива:
Отправьте GET-запрос к API клиентских бизнес-аккаунтов WhatsApp, чтобы получить список аккаунтов WABA, которые вам не принадлежат, но которыми с вами поделились.Отправьте GET-запрос к API принадлежащих вам бизнес-аккаунтов WhatsApp, чтобы получить список принадлежащих вам аккаунтов WABA.Отправьте GET-запрос к API телефонных номеров , чтобы получить список телефонных номеров, принадлежащих указанной WABA.
Книга контактов
В начале апреля 2026 года, для обеспечения непрерывности переписки, будет выпущена функция контактной книги, которая будет хранить контактную информацию пользователей WhatsApp. Контактная книга предоставляется и размещается компанией Meta; никаких работ по интеграции не требуется.
Как только эта функция станет доступна, при отправке сообщения/звонке на номер телефона пользователя или получении сообщения/звонка с номера телефона пользователя, номер телефона пользователя и BSUID будут добавлены в вашу телефонную книгу. После записи эти данные будут использоваться для заполнения любых полезных нагрузок веб-хуков и ответов API, содержащих номер телефона пользователя или BSUID, независимо от того, включена ли функция добавления имен пользователей.
Контактная книга ограничена уровнем бизнес-портфеля, поэтому любое взаимодействие между любым номером телефона компании в рамках этого портфеля и пользователем приведет к сохранению номера телефона пользователя и BSUID в контактной книге. Сохранение будет происходить только в результате взаимодействий, произошедших после запуска контактной книги; предыдущие взаимодействия не будут фиксироваться задним числом, и контактная информация этих пользователей не будет включаться в ответы API или веб-хуки.
Данные из контактной книги будут сохраняться до тех пор, пока вы не отключите эту функцию или не деактивируете свою учетную запись. При желании вы можете отключить эту функцию в любое время после 16 марта 2026 года в Meta Business Suite > Настройки бизнеса > Информация о бизнесе . Если вы отключите контактную книгу, она перестанет хранить информацию о пользователях, и вся уже сохраненная информация будет удалена. Если вы снова включите контактную книгу позже, она снова начнет хранить информацию о пользователях, но ранее сохраненную информацию восстановить будет невозможно.
Ограничения:
Если вы используете локальное хранилище и пользователь делится с вами своим номером телефона, нажав кнопку «Поделиться контактной информацией», Meta извлекает номер телефона пользователя из предоставленной контактной карточки (vCard) и сохраняет его в вашей телефонной книге в центрах обработки данных Meta. Извлекается и сохраняется только номер телефона; никакие другие данные vCard не сохраняются после стандартного периода хранения данных в локальном хранилище .Контактные книги привязаны к бизнес-портфелям. Это означает, что если у вас есть связанные портфели, номер телефона пользователя и BSUID должны быть записаны в контактную книгу каждого портфеля отдельно; контактная информация пользователей не передается и не синхронизируется между связанными портфелями.
коды стран
Если пользователь WhatsApp включает функцию указания имени пользователя, его номер телефона (и, следовательно, код страны) может не отображаться в веб-хуках. В таких случаях вместо него будет отображаться BSUID пользователя с префиксом в виде двухбуквенного ISO 3166 alpha-2 (например,
US.13491208655302741918 ).Имена пользователей для бизнеса
Компании также смогут использовать корпоративное имя пользователя. Однако, если вы используете корпоративное имя пользователя, это не приведет к скрытию вашего корпоративного номера телефона в WhatsApp или WhatsApp Business.
Имя пользователя для бизнеса привязано к одному рабочему номеру телефона во всем WhatsApp, то есть номер телефона может иметь только одно имя пользователя одновременно, и никакие два номера телефона WhatsApp (для частных лиц или для бизнеса) не могут иметь одинаковое имя пользователя.
Имена пользователей для корпоративных пользователей должны соответствовать следующему формату:
может содержать только английские буквы (az), цифры (0-9), точку (.) и символ подчеркивания (_)Неанглийские символы (например, ñ, é, ü) не поддерживаются и приведут к ошибке запросаДлина текста должна составлять от 3 до 35 символовдолжен содержать хотя бы одну английскую букву (az, AZ)не должен начинаться или заканчиваться точкой, а также не должен состоять из двух последовательных точекне должен начинаться с wwwНе должен заканчиваться доменным именем (например, .com, .org, .net, .int, .edu, .gov, .mil, .us, .in, .html и т. д.)Регистр не учитывается при сравнении имен пользователей, но точка и символ подчеркивания — нет; например, myID и myid — это одно и то же имя пользователя, но myid, my.id и my_id — это разные имена пользователей
Зарезервированные имена пользователей
До того, как функция присвоения имени пользователя станет доступна, у вас будет возможность зарезервировать для вас имя пользователя, которое WhatsApp уже зарезервировал. В качестве альтернативы вы можете выбрать другое имя пользователя, соответствующее вашим фирменным требованиям. Зарезервированное имя пользователя можно зарезервировать через WhatsApp Manager, Meta Business Suite или через API . Зарезервированные имена пользователей, получившие одобрение, станут активными после того, как функция присвоения имени пользователя станет доступна.
Если для вашей страницы в Facebook или аккаунта в Instagram уже используется зарезервированное имя пользователя, вам необходимо привязать номер телефона вашей компании к вашей странице в Facebook или аккаунту в Instagram, прежде чем вы сможете зарезервировать это имя пользователя.
Вы можете привязать свой номер телефона при подтверждении имени пользователя в Meta Business Suite или WhatsApp Manager, либо зайдя на свою страницу в Facebook или в аккаунт Instagram и добавив номер телефона напрямую .
Для привязки номера телефона вам необходим полный доступ к странице или учетной записи, либо базовый частичный доступ с разрешением manage_phone. Информацию о контроле/доступе и разрешениях см. разделе «О разрешениях для бизнес-портфеля и бизнес-активов» .
Приоритет отображения окна чата
При отображении информации о вашей компании в окнах чата в приложении будет соблюдаться следующий приоритет (в порядке убывания приоритета). Ваши рабочие номера телефонов всегда будут отображаться в вашем профиле компании.
Сохраненное имя контактаПодтвержденное название компании или официальное название Имя пользователяНомер телефона
Поддерживать
Получить текущее имя пользователя
username — Текущее имя пользователя. Будет опущено, если в рабочем номере телефона нет имени пользователя.статус — Статус пользователя. Возможные значения:Одобрено — Имя пользователя одобрено и видно пользователям WhatsApp.Зарезервировано — Имя пользователя зарезервировано для рабочего номера телефона, но не отображается пользователям WhatsApp. Оно станет видимым, как только функция имен пользователей станет доступна всем.
Удалить имя пользователя
success — Логическое значение. Будет установлено в true , если имя пользователя удалено успешно, в противном случае — в false .
вебхук business_username_updates
Будет добавлен новый business_username_update
Пожалуйста, подпишите каждое из ваших приложений на это поле веб-перехватчика, чтобы получать уведомления об изменениях имени пользователя.
id — Идентификатор бизнес-аккаунта WhatsApp.время — метка времени Unix, указывающая момент срабатывания веб-перехватчика.display_phone_number — Номер телефона компании, отображаемый в вашем профиле в приложении (номер, который отображается).username — Имя пользователя, для которого изменился статус. Опускается, если статус установлен как «удален» .статус — Значения могут быть следующими:Одобрено — указывает, что имя пользователя одобрено и видно пользователям WhatsApp. Срабатывает, когда статус имени пользователя меняется с «зарезервировано» на «одобрено» или когда имя пользователя было изменено через приложение WhatsApp Business.Удалено — указывает на то, что имя пользователя было удалено через приложение WhatsApp Business.Зарезервировано — указывает, что имя пользователя зарезервировано для рабочего номера телефона, но не отображается для пользователей WhatsApp. Оно станет видимым, как только функция имен пользователей станет доступна всем.
Сообщения
коды ошибок
Добавление нового кода ошибки в ответ на POST-запрос /
Код ошибки — 131062Подробности — Для этого сообщения не поддерживаются получатели, использующие идентификаторы пользователей, привязанные к бизнес-процессам (BSUID).
тестирование вебхуков
Вы можете протестировать полезные нагрузки веб-хуков, отражающие реальные сценарии использования имен пользователей, используя панель управления приложениями > Варианты использования (значок карандаша) > Связь с клиентами через WhatsApp > Настройка > конфигурации ( панель управления приложениями > WhatsApp > Конфигурация для приложений, созданных до декабря 2025 года). Нажмите «Тест» рядом с веб-хуком сообщений, чтобы отправить тестовый веб-хук сообщений на вашу конечную точку веб-хука.
Инструмент тестирования поддерживает веб-хуки для входящих сообщений и веб-хуки для сообщений о состоянии отправленных сообщений в следующих сценариях:
Пользователь не указал имя пользователя — в полезные данные веб-хука будут включены поля BSUID и номер телефона, но не имя пользователя. Это состояние по умолчанию для большинства пользователей на момент запуска.Пользователь указал имя пользователя, но номер телефона недоступен — в полезные данные веб-хука будут включены поля имени пользователя и BSUID, но поля номера телефона будут опущены. Ваша интеграция должна корректно обрабатывать этот сценарий. См. раздел «Номера телефонов» для получения информации об условиях включения номеров телефонов.Пользователь указал имя пользователя, и номер телефона доступен — полезная нагрузка веб-хука будет включать все поля: имя пользователя, BSUID и номер телефона.Присутствует родительский BSUID — Для компаний со связанными бизнес-портфелями полезная нагрузка веб-хука будет включать родительский BSUID в дополнение к BSUID уровня портфеля.
Краткий справочник идентификаторов веб-перехватчиков
В приведенных ниже таблицах кратко описано, какие идентификаторы пользователей будут включены в сообщения веб-хуков, в зависимости от типа веб-хука и от того, зарегистрировал ли пользователь имя пользователя.
Веб-хуки статуса исходящих сообщений
Эти идентификаторы применяются к веб-хукам, отображающим статусы отправки, доставки и прочтения сообщений .
| Идентификатор | Отправлено на указанный номер телефона | Отправлено в BSUID |
|---|---|---|
wa_id |
Всегда включено |
Включено, если номер телефона доступен в соответствии с условиями для номеров телефонов |
ID пользователя |
Всегда включено |
Всегда включено |
parent_user_id |
Включается, если родительские BSUID включены |
Включается, если родительские BSUID включены |
имя пользователя |
Включается в список доставленных/прочитанных сообщений, если у пользователя есть имя пользователя |
Включается в список доставленных/прочитанных сообщений, если у пользователя есть имя пользователя |
Веб-хуки для входящих сообщений
Эти идентификаторы применяются к входящих сообщений , включая сообщения, инициированные пользователем, и ответы пользователя.
| Идентификатор | У пользователя есть имя пользователя | У пользователя нет имени пользователя |
|---|---|---|
wa_id |
Включено, если номер телефона доступен в соответствии с условиями для номеров телефонов |
Всегда включено |
ID пользователя |
Всегда включено |
Всегда включено |
parent_user_id |
Включается, если родительские BSUID включены |
Включается, если родительские BSUID включены |
имя пользователя |
Всегда включено |
Не включено |
веб-хуки сообщений
веб-хуки для сообщений о состоянии
Эти изменения будут применяться к для сообщений о статусе .
contacts — Новый массив. Включается только для сообщений о статусе «отправлено», «доставлено» и «прочитано». Будет полностью опущен для которые не прошли проверку .name — Новое свойство. Значение будет установлено равным отображаемому имени пользователя WhatsApp.Имя пользователя — Новое свойство.Если функция отображения имен пользователей включена, то будет установлено имя пользователя WhatsApp.Будет полностью опущено для отправленных сообщений о статусе или если пользователь не включил функцию имен пользователей.wa_id — Новое свойство. Номера телефонов», он будет установлен на номер телефона пользователя .Номер телефона будет опущен, если его невозможно указать в соответствии с указанными условиями.user_id — Новое свойство. Будет установлено значение BSUID пользователя WhatsApp.parent_user_id родительский BSUID пользователя . В противном случае свойство будет полностью опущено.статусы recipient_id — Новое поведение (можно опустить).Если вы отправили сообщение на этот номер телефона, значение будет установлено на номер телефона пользователя.Если вы отправили сообщение группе, значение будет установлено на её идентификатор.Этот номер будет пропущен, если вы отправили сообщение пользователю с BSUID или родительским BSUID, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» .recipient_user_id — Новое свойство. Будет установлено значение BSUID пользователя или родительского BSUID, если сообщение было отправлено пользователю с таким же BSUID. В противном случае оно будет опущено.parent_user_id Если вы включили родительские BSUID, родительский BSUID пользователя
Пример веб-хука для отображения доставленных сообщений о статусе, описывающего сообщение, отправленное компанией, включившей родительские BSUID, на номер телефона пользователя WhatsApp, включившего функцию имен пользователей:
Пример веб-хука для отображения статуса отправленного сообщения, полученного от компании, в которой включены родительские BSUID, пользователю WhatsApp, в котором включена функция указания имени пользователя. В этом примере мы не можем указать номер телефона пользователя в соответствии с условиями, описанными в Номера телефонов» (поэтому
wa_id и recipient_id опущены).Веб-хуки для входящих сообщений
Эти изменения касаются веб-хуков для входящих сообщений ( текстовых , графических , интерактивных и т. д.), включая входящие сообщения, отправленные пользователями в групповом чате.
Приведённый ниже пример синтаксиса предназначен для входящего текстового сообщения, но изменения одинаковы для всех типов входящих сообщений.
контакты профиль Имя пользователя — Новое свойство.Будет установлено значение, равное имени пользователя, если у пользователя включена функция ввода имени пользователя.Будет пропущено, если пользователь не зарегистрировал имя пользователя.wa_id — Новое поведение (можно опустить). Номера телефонов», он будет установлен на номер телефона пользователя .Номер телефона будет опущен, если его невозможно указать в соответствии с указанными условиями.user_id — Новое свойство, устанавливаемое в значение BSUID пользователя.parent_user_id — Новое свойство. Будет установлено значение родительского BSUID пользователя, если вы включили родительские BSUID. В противном случае оно будет опущено.сообщения из — Новое поведение (можно опустить). Номера телефонов», он будет установлен на номер телефона пользователя .Номер телефона будет опущен, если его невозможно указать в соответствии с указанными условиями.from_user_id — Новое свойство, устанавливаемое в значение BSUID пользователя.from_parent_user_id — Новое свойство, устанавливаемое равным BSUID родительского пользователя, если вы включили родительские BSUID. В противном случае оно будет опущено.
Пример входящего текстового сообщения от пользователя, у которого включена функция указания имени пользователя, компании, у которой включены родительские BSUID . В этом сценарии мы не можем включить номер телефона пользователя в соответствии с условиями, описанными в Номера телефонов» .
вебхуки для сообщений о состоянии системы
Эти изменения касаются вебхуков для сообщений о состоянии системы
система body — Новая строка. Будет установлена на имя пользователя. изменился с к если пользователь изменил свой рабочий номер телефона.wa_id — Новое поведение (можно опустить).Будет опущено, если пользователь включил функцию указания имени пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» .Если функция добавления имен пользователей не включена, будет установлен номер телефона пользователя.user_id — Новое свойство. Будет установлено значение нового BSUID пользователя.parent_user_id родительский BSUID пользователя , если вы включили родительские BSUID. В противном случае оно будет опущено. type — Новое значение ( user_changed_user_id ). Будет установлено на user_changed_user_id , если пользователь WhatsApp изменил свой номер телефона.
веб-хуки user_preferences
Эти изменения будут применяться к user_preferences .
контакты профиль username — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. Свойство опускается, если функция имени пользователя отключена.wa_id — Новое поведение (можно опустить).Будет опущено, если пользователь включил функцию указания имени пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» .Если функция добавления имен пользователей не включена, будет установлен номер телефона пользователя.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id родительского BSUID пользователя , если вы включили родительские BSUID. В противном случае оно будет опущено.пользовательские_настройки wa_id — Новое поведение (можно опустить). Будет опущено, если пользователь включил функцию имени пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» . В противном случае будет установлен номер телефона пользователя.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id родительского BSUID пользователя , если вы включили родительские BSUID. В противном случае оно будет опущено.
вебхуки user_id_update
Новый user_id_update будет срабатывать при изменении BSUID пользователя WhatsApp. Подпишите свои приложения на это поле веб-хука, чтобы получать уведомления об изменениях BSUID.
контакты wa_id — Будет установлен на номер телефона пользователя, если он доступен. Будет опущен, если пользователь включил функцию имени пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» .обновление идентификатора пользователя wa_id — Будет установлен на номер телефона пользователя, если он доступен. Будет опущен, если пользователь включил функцию имени пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» .Подробности — Удобочитаемое описание обновления.user_id — Объект, содержащий предыдущий и текущий BSUID пользователя.предыдущий — Старый BSUID пользователя.current — Новый BSUID пользователя.parent_user_id BSUID родительского пользователя , если вы включили отображение BSUID родительских пользователей. В противном случае он будет опущен.предыдущий — старый родительский BSUID пользователя.current — Новый BSUID родительского узла пользователя.метка времени — метка времени Unix, указывающая, когда был отправлен веб-перехватчик.
Веб-хуки API групп
Веб-хуки для сообщений о состоянии групп
Эти изменения будут применяться к сообщений о
доставке и прочтении для сообщений, отправляемых группе.contacts — Новый массив. Включается только для сообщений о доставленных и прочитанных сообщениях. Будет полностью опущен для веб-хуков, обрабатывающих сообщения о неудачных попытках получения.name — Новое свойство. Значение будет установлено равным отображаемому имени пользователя WhatsApp.username — Новое свойство. Будет установлено на имя пользователя WhatsApp, если пользователь указал имя пользователя. Будет опущено для веб-хуков отправленных сообщений статуса или если пользователь не включил функцию имен пользователей.wa_id — Новое свойство.Будет опущено, если пользователь зарегистрировал имя пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» .Если вы отправили сообщение на этот номер телефона, значение будет установлено на номер телефона пользователя.user_id — Новое свойство. Будет установлено значение BSUID пользователя WhatsApp.parent_user_id Если включена поддержка родительских BSUID, родительский BSUID пользователя recipient_participant_id — Изменено. Если сообщение было отправлено на этот номер, значение будет установлено на номер телефона пользователя. В противном случае оно будет опущено.recipient_participant_user_id — Будет установлено значение BSUID пользователя или родительского BSUID, если вы отправили сообщение пользователю с его BSUID или родительским BSUID. В противном случае оно будет опущено.recipient_participant_parent_user_id — Новое свойство. Если вы включили родительские BSUID, оно будет установлено на значение родительского BSUID пользователя. В противном случае оно будет опущено.
вебхуки group_participants_update
Эти изменения касаются group_participants_update .
Входные данные — Новое значение (BSUID или родительский BSUID).Если вы удалили пользователя из группы, используя его номер телефона, значение будет установлено на номер телефона пользователя.Значение будет установлено на BSUID пользователя или родительский BSUID, если вы удалили пользователя из группы, используя его BSUID или родительский BSUID.wa_id — Новое поведение (можно опустить).Этот параметр будет опущен, если пользователь включил функцию указания имени пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае будет установлен номер телефона пользователя.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id Если включена поддержка родительских BSUID, родительский BSUID пользователя username — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. В противном случае оно будет опущено.
Сосуществование
История веб-хуков
Эти изменения коснутся истории , описывающих историю чатов в приложении WhatsApp Business для зарегистрированных бизнес-клиентов.
id — Новое поведение (может быть опущено). Будет опущено, если на момент запроса на синхронизацию истории у пользователя уже включена возможность добавления имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» . В противном случае будет установлен номер телефона пользователя.контекст — Новый объект контекста.wa_id — Новое свойство.Этот параметр будет пропущен, если на момент запроса на синхронизацию у пользователя уже включена функция имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае он будет установлен на номер телефона пользователя.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id равное родительскому BSUID пользователя , если вы включили родительские BSUID. В противном случае оно будет опущено.Имя пользователя — Новое свойство.Если функция указания имени пользователя включена, значение будет установлено равным его имени. В противном случае оно будет опущено.сообщения из — Новое поведение (можно опустить).Этот параметр будет пропущен, если на момент запроса на синхронизацию у пользователя уже включена функция имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае он будет установлен на номер телефона пользователя.from_user_id — Новое свойство. Будет установлено значение BSUID пользователя.from_parent_user_id равное родительскому BSUID пользователя , если вы включили родительские BSUID. В противном случае оно будет опущено.
Эти изменения коснутся истории , описывающих медиафайлы, отправленные пользователем WhatsApp корпоративному клиенту или наоборот.
Контакты — Новый объект.профиль username — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. В противном случае оно будет опущено.wa_id — Новое свойство.Этот параметр будет пропущен, если на момент запроса на синхронизацию у пользователя уже включена функция имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае он будет установлен на номер телефона пользователя.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id равное родительскому BSUID пользователя , если вы включили родительские BSUID. В противном случае оно будет опущено.сообщения из — Новое поведение (можно опустить).Этот параметр будет пропущен, если на момент запроса на синхронизацию у пользователя уже включена функция имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае он будет установлен на номер телефона пользователя.from_user_id — Новое свойство. Будет установлено значение BSUID пользователя.from_parent_user_id равное родительскому BSUID пользователя , если вы включили родительские BSUID. В противном случае оно будет опущено.message_echoes — Новое поведение (можно опустить).Этот параметр будет пропущен, если на момент запроса на синхронизацию у пользователя уже включена функция имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае он будет установлен на номер телефона пользователя.to_user_id — Новое свойство. Будет установлено значение BSUID пользователя.to_parent_user_id равное родительскому BSUID пользователя , если вы включили родительские BSUID. В противном случае оно будет опущено.
smb_message_echoes webhooks
Эти изменения будут применяться к smb_message_echoes .
Контакты — Новый массив.профиль username — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. В противном случае оно будет опущено.wa_id — Новое свойство. Будет опущено, если на момент использования бизнес-клиентом приложения WhatsApp Business для отправки сообщения пользователю, у пользователя уже была включена функция добавления имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае будет установлен номер телефона пользователя.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id равное родительскому BSUID пользователя , если вы включили родительские BSUID. В противном случае оно будет опущено.message_echoes — Новое поведение (может быть опущено). Будет опущено, если в момент использования бизнес-клиентом приложения WhatsApp Business для отправки сообщения пользователю, у пользователя уже была включена функция имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае будет установлен номер телефона пользователя.to_user_id — Новое свойство. Будет установлено значение BSUID пользователя.to_parent_user_id равное родительскому BSUID пользователя , если вы включили родительские BSUID. В противном случае оно будет опущено.
smb_app_state_sync webhooks
Эти изменения будут применяться к smb_app_state_sync .
phone_number — Новое поведение (можно опустить). Будет опущено, если на момент запроса на синхронизацию у пользователя уже включена возможность использования имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае будет установлен номер телефона пользователя.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id равное родительскому BSUID пользователя , если вы включили родительские BSUID. В противном случае оно будет опущено.username — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. В противном случае оно будет опущено.
Отзыв сообщений через веб-хуки
Эти изменения будут применяться к отзыва сообщений .
контакты профиль username — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. В противном случае оно будет опущено.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id родительскому BSUID пользователя . В противном случае оно будет опущено.
Веб-хуки для редактирования сообщений
Эти изменения будут применяться к редактирования сообщений .
контакты профиль username — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. В противном случае оно будет опущено.wa_id — Новое свойство. Будет опущено, если на момент редактирования сообщения пользователем WhatsApp функция добавления имен пользователей уже включена, и номер телефона не может быть указан в соответствии с условиями, описанными в Номера телефонов» . В противном случае оно будет опущено.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id родительскому BSUID пользователя . В противном случае оно будет опущено.
Аналитика
Без изменений.
Выставление счетов и формирование инвойсов
Без изменений.
Часто задаваемые вопросы
Что мне нужно сделать, чтобы добавить поддержку имен пользователей?
Идентификаторы BSUID и родительские BSUID начнут появляться в полезных нагрузках веб-хуков в марте 2026 года, до того, как имена пользователей станут доступны пользователям WhatsApp. Для обработки сообщений от пользователей, которые включат эту функцию после ее появления, вам потребуется поддерживать BSUID (и родительские BSUID, если вы их включите). Для этого необходимо:
Обновите интеграцию веб-хуков, чтобы она поддерживала BSUID (и родительский BSUID , если он используется).Разработайте логику для обработки нескольких идентификаторов (номера телефонов пользователей, не использующих имя пользователя; BSUID пользователей, использующих имя пользователя, если номер телефона отсутствует в веб-хуках), и сопоставьте соответствующие поля с вашей CRM/базой данных.Обновите внутренние и внешние системы, связанные с этими интеграциями, чтобы они могли обрабатывать BSUID и объединяться с предыдущими идентификаторами; в первую очередь, это CRM (как сторонние, так и внутренние базы данных) и любые инструменты или рабочие процессы, запускаемые на основе CRM (например, сообщения, запускаемые в рамках кампаний, управление кампаниями, измерение результатов, выставление счетов и т. д.).Если вам по-прежнему требуются номера телефонов клиентов, обновите своих мессенджеров/сценарии взаимодействия (если они используются), чтобы они запрашивали номера телефонов, обрабатывали сценарии, когда пользователи не сообщают свои номера телефонов, и совершенствуйте эти новые сценарии общения. Общие ограничения в сценариях использования ИИ см . в Условиях использования решения WhatsApp Business .Если у вас несколько бизнес-портфелей в Meta, вам может потребоваться внедрить решение для обеспечения централизованного доступа к CRM для всех этих портфелей, чтобы минимизировать операционные издержки, связанные с использованием и хранением BSUID (и родительских BSUID).
Когда я получу BSUID или родительский BSUID, а не номер телефона?
Когда пользователь присваивает себе имя пользователя, обеспечивается конфиденциальность его номера телефона, то есть его номер телефона не будет отображаться в приложении и не будет включаться в веб-хуки. Если номер телефона пользователя отсутствует (отсутствует свойство wa_id), можно использовать его BSUID (или родительский BSUID , если используется), который будет включен и присвоен новому свойству user_id (
parent_user_id для родительских BSUID).Если пользователь не добавил имя пользователя, вы получите как его номер телефона, так и его BSUID (а также родительский BSUID, если он включен).
Обратите внимание, что мы продолжим передавать номер телефона при соблюдении определенных условий . Однако, согласно нашим Условиям использования облачного API, номера телефонов и связанные с ними данные хранятся максимум 30 дней для поддержки таких функций, как повторная доставка сообщений. Могут возникнуть ситуации, когда вы будете получать сообщения от существующих пользователей за пределами этого 30-дневного периода, которые могут выглядеть для вас как сообщения от нового пользователя. Поэтому крайне важно как можно скорее начать поддержку BSUID, чтобы свести к минимуму потерю контекста разговора.
Почему партнерам и компаниям, напрямую интегрированным с Cloud API и использующим его, включая рекламные объявления, ведущие к рекламодателям WhatsApp, необходимо внедрять BSUID?
Партнеры и компании должны внедрить BSUID для продолжения обработки входящих сообщений от пользователей, использующих имена пользователей WhatsApp. После внедрения BSUID и обработки сообщений от таких пользователей, веб-хуки сообщений в некоторых случаях, например, в wa_id, больше не будут включать номера телефонов, поэтому любой, кто использует облачный API, должен убедиться, что все подключенные системы могут обрабатывать BSUID. Они также смогут запрашивать номер телефона пользователя в ходе обсуждения.
Если я ещё не использую BSUID и начинаю получать сообщения от пользователей, использующих эти имена, которые я не могу обработать, есть ли какие-либо варианты решения проблемы?
Если вы еще не внедрили BSUID и не можете обрабатывать сообщения от пользователей, использующих это имя, у вас не будет никаких возможностей для исправления ситуации.
Для сообщений от новых клиентов: веб-хук будет по-прежнему отправляться при входящем сообщении. В зависимости от особенностей реализации это может повлиять на ваши системы, которые не предназначены для обработки входящих сообщений без номеров телефонов пользователей и BSUID, присвоенного новому полю user_id. Для сообщений от существующих клиентов: номер телефона будет по-прежнему включаться, если выполняются условия, описанные в разделе Номера телефонов»
После добавления поддержки BSUID, запрашивайте номера телефонов у пользователей, реализовав кнопку запроса номера телефона .
Чем отличаются корпоративные имена пользователей от отображаемых имен? В каких случаях пользователь увидит корпоративное имя пользователя, а в каких — отображаемое имя?
Имена пользователей для компаний позволят пользователям связываться с компанией по её имени пользователя, то есть конечный пользователь сможет найти компанию, используя своё точное имя пользователя, и связаться с ней. Поскольку конечные пользователи не могут осуществлять поиск по отображаемым именам, имена пользователей для компаний предоставляют явное преимущество в качестве уникального идентификатора, позволяющего пользователям надёжно находить нужную компанию.
Имена пользователей для бизнеса должны соответствовать определенным правилам форматирования в отношении длины и допустимого количества символов, в то время как для отображаемых имен допускаются некоторые послабления в плане форматирования.
Имена пользователей для бизнеса уникальны и привязаны один к одному к номерам телефонов, то есть @JaspersMarket будет привязан к одному номеру телефона, а @JaspersMarketCustomerSupport — к другому. Отображаемые имена не привязаны один к одному к номерам телефонов, то есть под отображаемым именем Jasper's Market может быть 10 номеров телефонов.
Когда у компании есть и имя пользователя, и отображаемое имя, отображаемое имя будет отображаться первым (например, в профиле, списке чатов, сообщениях и т. д.), чтобы компания могла завоевать доверие пользователей, а пользователи могли узнать компанию, когда она свяжется с ними.
Журнал изменений документа
31 марта 2026 г
23 марта 2026 г
user_id в ответах на сообщения и маркетинговые сообщения : если запрос содержит как номер телефона, так и BSUID или родительский BSUID, ответ не будет содержать user_id , поскольку номер телефона имеет приоритет, и ответ идентичен запросу только с номером телефона. Соответственно обновлен пример ответа для случая с номером телефона и BSUID.
18 марта 2026 г
ENT (например, US.ENT.11815799212886844830 ).Добавлена информация о доступности кнопки запроса контактных данных (начало мая 2026 г.).Уточнено, что контактная книга предоставляется и размещается компанией Meta без необходимости интеграции, имеет ограниченный охват на уровне бизнес-портфеля и хранит только те взаимодействия, которые произошли после запуска.Уточнено, что к именам пользователей применяются те же ограничения по формату, что и к именам пользователей в компаниях .Уточнено, что символы, отличные от английских (например, ñ, é, ü), не поддерживаются в бизнес-именах пользователей .Уточнено, что условия 30-дневного ретроспективного анализа в Номера телефонов» оцениваются для каждого номера телефона компании.Удалена фраза «Вы находитесь в списке контактов пользователя в WhatsApp» из условий включения номера телефона .
18 февраля 2026 г
6 февраля 2026 г
wa_id в веб-хуках входящих сообщений).Изменен способ отображения ошибок при попытке принять или изменить имя пользователя компании .Удалена возможность отмены ожидающих запросов на присвоение имени пользователя для корпоративных пользователей.Изменен веб-перехватчик phone_number_username_update на business_username_updates .