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

Зачем нужны BSUID

В 2026 году WhatsApp внедряет опциональные имена пользователей. Если пользователь выбирает имя пользователя, 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

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

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

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

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

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

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

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

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

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

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

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

Укажите в recipient обычный BSUID или parent 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 или parent 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_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-уведомления, даже если пользователь начнет использовать имя пользователя (username). Адресные книги привязаны к отдельным бизнес-портфолио. Связанные портфолио не разделяют и не синхронизируют свои записи: связь сохраняется независимо в каждом портфолио. Meta хранит записи до тех пор, пока вы не отключите эту функцию или не деактивируете аккаунт. Вы можете отключить ее в разделе Meta Business Suite > Настройки компании > Информация о компании. Отключение функции приводит к удалению сохраненных записей и прекращению фиксации новых. Повторное включение начинает сбор новых записей, но не восстанавливает удаленные данные. Настройки адресной книги Meta

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

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

Удаление записи из адресной книги 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.

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

Приведенные ниже полезные нагрузки Webhook от YCloud демонстрируют поля, добавленные или измененные для поддержки BSUID. Обновите свой парсер для поддержки новых идентификаторов и обработки отсутствующих номеров телефонов клиентов.

Маркер	Значение
`<ADDED>`	Новое необязательное поле или объект, добавленный для поддержки BSUID.
`<CHANGED>`	Существующее поле с номером телефона клиента может быть опущено; его имя остается неизменным.
Без маркера	Существующие поля, сохраненные для демонстрации полной структуры события.

Примеры содержат оболочку события YCloud и показывают расположение каждого поля. Необязательные поля следуют описанным ниже правилам исключения. Удалите комментарии // <ADDED> и // <CHANGED> перед использованием данных полезной нагрузки в качестве тестового JSON.

Событие	Необязательные поля для сохранения
`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.

whatsapp.message.updated

В примере показано доставленное сообщение. <CHANGED> помечает to как условное, если номер телефона недоступен. Новый объект customerProfile опускается для failed; его username также опускается для sent или если у пользователя нет имени пользователя.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "delivered",
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": { // <ADDED>
      "name": "Example customer", // <ADDED>
      "username": "example_customer" // <ADDED>
    }
  }
}

whatsapp.inbound_message.received

Сохраняйте новые идентификаторы отправителя вместе с существующим именем профиля. Идентификатор бизнес-получателя to не меняется; номер телефона клиента from может быть опущен. Пример смены номера телефона приведен ниже для сообщения system.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

whatsapp.user.preferences

Настройка остается в whatsappUserPreference. Используйте предоставленные идентификаторы пользователя, даже если contactPhoneNumber отсутствует.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.user.preferences",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappUserPreference": {
    "wabaId": "WABA_ID",
    "businessPhoneNumber": "+16315551111",
    "businessPhoneId": "BUSINESS_PHONE_ID",
    "contactName": "Example customer",
    "contactPhoneNumber": "+16315552222", // <CHANGED>
    "userId": "US.13491208655302741918", // <ADDED>
    "parentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "detail": "User requested to stop marketing messages",
    "category": "marketing_messages",
    "value": "stop",
    "timestamp": "1791532800000"
  }
}

whatsapp.call.connect

Для звонков, инициированных бизнесом, идентификаторами клиента являются toUserId и toParentUserId. Для звонков, инициированных пользователем, это fromUserId и fromParentUserId. Только поле номера телефона клиента может быть опущено в этих примерах.

BUSINESS_INITIATED
USER_INITIATED

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingConnect": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "direction": "BUSINESS_INITIATED",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "sdpType": "answer",
    "sdp": "SDP_CONTENT"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingConnect": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "direction": "USER_INITIATED",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "sdpType": "offer",
    "sdp": "SDP_CONTENT"
  }
}

whatsapp.call.terminate

BUSINESS_INITIATED
USER_INITIATED

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingTerminate": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "direction": "BUSINESS_INITIATED",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "startTime": 1791532770000,
    "endTime": 1791532800000,
    "duration": 30,
    "status": "COMPLETED"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingTerminate": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "direction": "USER_INITIATED",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "startTime": 1791532770000,
    "endTime": 1791532800000,
    "duration": 30,
    "status": "COMPLETED"
  }
}

whatsapp.call.status.updated

Идентификаторы получателя находятся на одном уровне с recipientPhone внутри callingStatusUpdated.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingStatusUpdated": {
    "wabaId": "WABA_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "status": "RINGING",
    "recipientPhone": "+16315552222", // <CHANGED>
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830" // <ADDED>
  }
}

whatsapp.group.participants_update

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

added
removed
failed

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "added",
    "groupId": "GROUP_ID@g.us",
    "addedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        }
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z",
    "waId": "16315552222", // <CHANGED>
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_remove",
    "status": "removed",
    "groupId": "GROUP_ID@g.us",
    "removedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        }
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "failed",
    "groupId": "GROUP_ID@g.us",
    "failedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        },
        "errors": [
          {
            "code": 131000,
            "title": "Something went wrong",
            "message": "Please retry later."
          }
        ]
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z"
  }
}

whatsapp.smb.history

Сохраняйте оболочку конкретного события: входящая история использует whatsappInboundMessage, а исходящая — whatsappMessage. Исходящие toUserId и toParentUserId являются псевдонимами совместимости для recipientUserId и parentRecipientUserId. В этих примерах показаны события, содержащие сообщения; фрагмент истории, содержащий только метаданные, может опускать оба объекта сообщений.

Входящая история
Исходящая история

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "sent",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830" // <ADDED>
  }
}

whatsapp.smb.app.state.sync

Эта полезная нагрузка сохранена из устаревшей документации по миграции на BSUID. Это событие не указано в текущем общедоступном каталоге событий, доступных для подписки; не добавляйте его в enabledEvents на основе этого примера. Используйте приведенную структуру при поддержке интеграции, которая уже получает эту устаревшую полезную нагрузку.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.app.state.sync",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappSmbAppStateSync": {
    "wabaId": "WABA_ID",
    "phoneNumber": "+16315551111",
    "stateSync": [
      {
        "contact": {
          "fullName": "Example customer",
          "firstName": "Example",
          "phoneNumber": "+16315552222", // <CHANGED>
          "userId": "US.13491208655302741918", // <ADDED>
          "parentUserId": "US.ENT.11815799212886844830", // <ADDED>
          "username": "example_customer" // <ADDED>
        },
        "action": "add",
        "timestamp": 1791532800000
      }
    ]
  }
}

whatsapp.smb.message.echoes

Это сообщения, отправленные из приложения WhatsApp Business или поддерживаемого сопряженного устройства. Устаревшие имена полей toUserId и toParentUserId являются псевдонимами совместимости для recipientUserId и parentRecipientUserId. Сохраняйте профиль в whatsappMessage.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "sent",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": { // <ADDED>
      "username": "example_customer" // <ADDED>
    }
  }
}

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

Когда whatsappInboundMessage.type имеет значение system, а system.type — user_changed_number, внешние поля отправителя определяют старую идентичность пользователя. Вложенные поля system содержат новые BSUID и, если доступно, новый номер телефона. Используйте имена полей user_id и parent_user_id внутри system.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "system",
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    },
    "system": {
      "type": "user_changed_number",
      "wa_id": "16315553333", // <CHANGED>
      "user_id": "US.13491208655302741919", // <ADDED>
      "parent_user_id": "US.ENT.11815799212886844831" // <ADDED>
    }
  }
}

Считайте parent_user_id необязательным. Новый номер телефона в wa_id также может отсутствовать, поэтому используйте user_id и любой предоставленный 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 отображает информацию о компании в следующем порядке приоритета:

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

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

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

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

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

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

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

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

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

Руководства

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

Webhooks

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

Зачем нужны BSUID

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

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

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

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

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

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

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

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

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

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

Инициация звонка с помощью BSUID

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

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

Бизнес-имена пользователей

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

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

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

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

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

​Зачем нужны BSUID

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

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

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

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

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

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

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

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

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

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

​Инициация звонка с помощью BSUID

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

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

​Бизнес-имена пользователей

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

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

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

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

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

Зачем нужны BSUID

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

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

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

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

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

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

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

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

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

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

Инициация звонка с помощью BSUID

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

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

Бизнес-имена пользователей

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

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

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