Идентификаторы пользователей с бизнес-целями | Документация для разработчиков
Идентификаторы пользователей с бизнес-целями
Обновлено: 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 будут следующими:
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 дней.
Идентификаторы BSUID начнут отображаться в веб-хуках в начале апреля 2026 года. Однако наши API не будут поддерживать отправку сообщений, адресованных пользователям с BSUID, до мая 2026 года (точная дата уточняется). Как только наши API начнут поддерживать BSUID в мае, вы сможете отправлять сообщения пользователям, используя их BSUID, номер телефона или и то, и другое.
Если вы являетесь поставщиком решений и предоставляете своим корпоративным клиентам услуги обмена сообщениями через WhatsApp, ваши клиенты смогут использовать ваше приложение для отправки сообщений другим пользователям, используя номера телефонов своих корпоративных портфелей и любые BSUID, привязанные к их портфелю. Однако, если вы попытаетесь использовать один из BSUID вашего корпоративного клиента с вашим собственным номером телефона, это не удастся, поскольку BSUID привязаны к портфелям (и, по сути, к активам, которыми владеет портфель).
Если вы не уверены в принадлежности актива:
Запрос номеров телефонов у пользователей
Эта функция станет доступна в начале мая 2026 года.
Для упрощения запроса телефонных номеров у пользователей WhatsApp
REQUEST_CONTACT_INFO доступен тип кнопки служебных и маркетинговых материалов .Если пользователь нажмет эту кнопку, его виртуальная контактная карточка и номер телефона WhatsApp будут переданы в переписке, и веб-перехватчик контактов телефона пользователя и виртуальную контактную карточку.номер
Если вы используете функцию контактной книги, номер телефона пользователя также будет автоматически добавлен в вашу контактную книгу. Для компаний, включивших локальное хранилище, Meta извлекает номер телефона пользователя из общей контактной карточки (vCard) и сохраняет его в вашей контактной книге в центрах обработки данных Meta. Извлекается и сохраняется только номер телефона; никакие другие данные vCard не сохраняются после стандартного периода использования данных.
Чтобы добавить кнопку запроса контактной информации в шаблон служебной или маркетинговой формы, используйте следующую структуру полезной нагрузки при создании или редактировании шаблона служебной или маркетинговой формы:
{ "type": "buttons", "buttons": [ { "type": "REQUEST_CONTACT_INFO" },<!-- Additional button objects would go here, if using --> ] }Кнопки запроса контактной информации нельзя настроить, поэтому вам не нужно указывать значения каких-либо параметров при отправке шаблона.
Пример полезной нагрузки веб-перехватчика для связи с использованием vCard:
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "контакты": [ { "профиль": { "имя": "<USER_DISPLAY_NAME> ", "имя пользователя": "<USERNAME> ", }, "ID пользователя": "<BSUID> " } ], "messages": [ { "id": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "type": "contacts", "origin": "contact_request/other",<!-- ADDED --> "контакты": [ { "vcard": "<VCARD> ",<!-- ADDED --> "телефоны": [ { "телефон": "<USER_PHONE_NUMBER> " } ] } ] } ] }, "поле": "сообщения" } ] } ] }Книга контактов
В начале апреля 2026 года, для обеспечения непрерывности переписки, будет выпущена функция контактной книги, которая будет хранить контактную информацию пользователей WhatsApp. Контактная книга предоставляется и размещается компанией Meta; никаких работ по интеграции не требуется.
Как только эта функция станет доступна, при отправке сообщения/звонке на номер телефона пользователя или получении сообщения/звонка с номера телефона пользователя, номер телефона пользователя и BSUID будут добавлены в вашу телефонную книгу. После записи эти данные будут использоваться для заполнения любых полезных нагрузок веб-хуков и ответов API, содержащих номер телефона пользователя или BSUID, независимо от того, включена ли функция добавления имен пользователей.
Контактная книга ограничена уровнем бизнес-портфеля, поэтому любое взаимодействие между любым номером телефона компании в рамках этого портфеля и пользователем приведет к сохранению номера телефона пользователя и BSUID в контактной книге. Сохранение будет происходить только в результате взаимодействий, произошедших после запуска контактной книги; предыдущие взаимодействия не будут фиксироваться задним числом, и контактная информация этих пользователей не будет включаться в ответы API или веб-хуки.
Данные из контактной книги будут сохраняться до тех пор, пока вы не отключите эту функцию или не деактивируете свою учетную запись. При желании вы можете отключить эту функцию в любое время после 16 марта 2026 года в Meta Business Suite > Настройки бизнеса > Информация о бизнесе. Если вы отключите контактную книгу, она перестанет хранить информацию о пользователях, и вся уже сохраненная информация будет удалена. Если вы снова включите контактную книгу позже, она снова начнет хранить информацию о пользователях, но ранее сохраненную информацию восстановить будет невозможно.
Ограничения:
коды стран
Если пользователь WhatsApp включает функцию указания имени пользователя, его номер телефона (и, следовательно, код страны) может не отображаться в веб-хуках. В таких случаях вместо него будет отображаться BSUID пользователя с префиксом в виде ISO 3166 alpha-2двухбуквенного (например,
US.13491208655302741918).Имена пользователей для бизнеса
Компании также смогут использовать корпоративное имя пользователя. Однако, если вы используете корпоративное имя пользователя, это не приведет к скрытию вашего корпоративного номера телефона в WhatsApp или WhatsApp Business.
Имя пользователя для бизнеса привязано к одному рабочему номеру телефона во всем WhatsApp, то есть номер телефона может иметь только одно имя пользователя одновременно, и никакие два номера телефона WhatsApp (для частных лиц или для бизнеса) не могут иметь одинаковое имя пользователя.
Имена пользователей для корпоративных пользователей должны соответствовать следующему формату:
Зарезервированные имена пользователей
До того, как функция присвоения имени пользователя станет доступна, у вас будет возможность зарезервировать для вас имя пользователя, которое WhatsApp уже зарезервировал. В качестве альтернативы вы можете выбрать другое имя пользователя, соответствующее вашим фирменным требованиям. Зарезервированное имя пользователя можно зарезервировать через WhatsApp Manager, Meta Business Suite или через API. Зарезервированные имена пользователей, получившие одобрение, станут активными после того, как функция присвоения имени пользователя станет доступна.
Если для вашей страницы в Facebook или аккаунта в Instagram уже используется зарезервированное имя пользователя, вам необходимо привязать номер телефона вашей компании к вашей странице в Facebook или аккаунту в Instagram, прежде чем вы сможете зарезервировать это имя пользователя.
Вы можете привязать свой номер телефона при подтверждении имени пользователя в Meta Business Suite или WhatsApp Manager, либо зайдя на свою страницу в Facebook или в аккаунт Instagram и номер телефона напрямую.добавив
Для привязки номера телефона вам необходим полный доступ к странице или учетной записи, либо базовый частичный доступ с разрешением manage_phone. разделе «О разрешениях для бизнес-портфеля и бизнес-активов». Информацию о контроле/доступе и разрешениях см.
Приоритет отображения окна чата
При отображении информации о вашей компании в окнах чата в приложении будет соблюдаться следующий приоритет (в порядке убывания приоритета). Ваши рабочие номера телефонов всегда будут отображаться в вашем профиле компании.
Поддерживать
Принять или изменить корпоративное имя пользователя
Эта функция станет доступна позже, в 2026 году.
Возможность присвоить или изменить корпоративное имя пользователя появится позже в этом году (точная дата будет объявлена дополнительно).
Синтаксис запроса:
curl -X POST 'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /username' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer<ACCESS_TOKEN> ' \ -d ' { "username": "<DESIRED_USERNAME> " }'Синтаксис ответа в случае успеха:
{ "статус": "<STATUS> " }статус — Статус последнего запрошенного имени пользователя. Возможные значения:
Одобрено — Запрошенное имя пользователя одобрено и будет видно пользователям WhatsApp после того, как функция имен пользователей станет доступна.Зарезервировано — Запрошенное имя пользователя зарезервировано и одобрено, но пока не отображается пользователям WhatsApp. Оно появится у пользователей WhatsApp, как только эта функция станет доступна всем.Синтаксис ответа в случае сбоя:
{ "ошибка": { "сообщение": "<MESSAGE> ", "тип": "<TYPE> ", "code": <CODE>, "error_data": { "messaging_product": "whatsapp", "details": " <DETAILS>" }, "error_subcode":<ERROR_SUBCODE> , "fbtrace_id": "<FBTRACE_ID> " } }</details></code>| Код | Подробности | Возможные причины и решения |
|---|---|---|
10 | Приложение не имеет разрешения на выполнение данного действия | Убедитесь, что у пользователя системы, чей токен используется в запросе, есть соответствующие права доступа к бизнес-активам в учетной записи WhatsApp Business: либо полный доступ , либо частичный доступ к номерам телефонов. |
33 | Неверный идентификатор | (1) Идентификатор номера корпоративного телефона недействителен, (2) учетная запись WhatsApp Business, связанная с номером корпоративного телефона, была удалена, или (3) пользователь, чей токен был использован в запросе, не предоставил приложению разрешение whatapp_business_management (для которого требуется расширенный доступ, если вы являетесь поставщиком решений). |
100 | Параметр недействителен | Формат имени пользователя недопустим. |
147001 | Имя пользователя недоступно | Имя пользователя уже занято, не проходит наши внутренние проверки или недоступно на платформе. Попробуйте запросить другое имя пользователя. |
147002 | Учетная запись не соответствует требованиям для запроса имени пользователя | В портфеле компании, владеющей бизнес-аккаунтом WhatsApp и бизнес-номером телефона, должен быть установлен более высокий лимит сообщений. |
147003 | Аккаунт Facebook не привязан | Необходимо связатьтелефона со страницей Facebook, которая уже использует запрошенное имя пользователя. |
147004 | Аккаунт Instagram не привязан | Необходимо привязатьтелефона к аккаунту Instagram, который уже использует запрошенное имя пользователя. |
133010 | Учетная запись не зарегистрирована | необходимо предварительно зарегистрировать рабочий телефонный номер Для использования API. |
Получить текущее имя пользователя
Вы можете использовать GET / Конечная точка для получения статуса имени пользователя, связанного с номером телефона компании, или информации об имени пользователя.
Синтаксис запроса:
curl 'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /username' \ -H 'Авторизация: Bearer'<ACCESS_TOKEN> '
Синтаксис ответа:
{ "имя пользователя": "<USERNAME> ", "статус": "<STATUS> " }username — Текущее имя пользователя. Будет опущено, если в рабочем номере телефона нет имени пользователя.статус — Статус пользователя. Возможные значения:
Одобрено — Имя пользователя одобрено и видно пользователям WhatsApp.Зарезервировано — Имя пользователя зарезервировано для рабочего номера телефона, но не отображается пользователям WhatsApp. Оно станет видимым, как только функция имен пользователей станет доступна всем.Получить зарезервированные имена пользователей
Добавление нового GET-запроса / Конечная точка, возвращающая список имен пользователей, зарезервированных для вашего бизнес-портфеля.
Позвоните на почту / Для получения нужного имени пользователя из списка потребуется его одобрение. После одобрения и появления имен пользователей в вашей стране, они перейдут в статус «активный», что означает, что имя пользователя начнет отображаться в вашем профиле, и пользователи смогут искать его с помощью поиска по точному совпадению.
Синтаксис запроса:
curl 'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /username_suggestions' \ -H 'Авторизация: Bearer'<ACCESS_TOKEN> '
Синтаксис ответа:
{ "данные": [ { "предложения_пользователя": [ "<RESERVED_USERNAME> ",<!-- Additional usernames would follow, if any --> ] } ], }username_suggestions — Массив зарезервированных имен пользователей, если таковые имеются. У этих имен пользователей выше вероятность одобрения.Удалить имя пользователя
Вы можете использовать клавишу DELETE / Конечная точка для удаления имени пользователя компании, связанного с номером телефона компании.
Синтаксис запроса:
curl -X DELETE 'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /username' \ -H 'Авторизация: Bearer'<ACCESS_TOKEN> '
Синтаксис ответа:
{ "успех":<SUCCESS?> }success — Логическое значение. Будет установлено в true , если имя пользователя удалено успешно, в противном случае — в false.вебхук business_username_updates
новый business_username_update Будет добавлен
Пожалуйста, подпишите каждое из ваших приложений на это поле веб-перехватчика, чтобы получать уведомления об изменениях имени пользователя.
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "время":<WEBHOOK_TRIGGER_TIMESTAMP> , "изменения": [ { "поле": "обновление имени_пользователя_компании", "значение": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "имя пользователя": "<USERNAME> ", "статус": "<STATUS> " } } ] } ] }id — Идентификатор бизнес-аккаунта WhatsApp.время — метка времени Unix, указывающая момент срабатывания веб-перехватчика.display_phone_number — Номер телефона компании, отображаемый в вашем профиле в приложении (номер, который отображается).username — Имя пользователя, для которого изменился статус. Опускается, если статус установлен как «удален».статус — Значения могут быть следующими:
Одобрено — указывает, что имя пользователя одобрено и видно пользователям WhatsApp. Срабатывает, когда статус имени пользователя меняется с «зарезервировано» на «одобрено»или когда имя пользователя было изменено через приложение WhatsApp Business.Удалено — указывает на то, что имя пользователя было удалено через приложение WhatsApp Business.Зарезервировано — указывает, что имя пользователя зарезервировано для рабочего номера телефона, но не отображается для пользователей WhatsApp. Оно станет видимым, как только функция имен пользователей станет доступна всем.Сообщения
Отправка запросов на отправку сообщений
Эти изменения будут применяться к POST / Запросы к конечным точкам.
В этом примере синтаксис используется для отправки
текстового сообщения, но изменения применимы ко всем типам сообщений.'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /messages' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer<ACCESS_TOKEN> ' \ -d ' { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "получатель": "<BSUID> ",<!-- ADDED --> "type": "text", "text": { "body": "<BODY_TEXT> " } }'можно указать как
Кому » (номер телефона), так и «Получателю» В запросе Кому » (номер телефона). При желании можно использовать и один из вариантов:Чтобы отправить сообщение, используя только номер телефона пользователя:
на номер телефона пользователяопустить получателя свойствоЧтобы отправить сообщение, используя только BSUID пользователя или родительский BSUID:
получателя равным BSUID пользователя или родительскому BSUIDопустить to свойствоОтправить ответное сообщение
Эти изменения касаются POST / Ответы на конечные вопросы.
{ "messaging_product": "whatsapp", "contacts": [ { "input": "<USER_PHONE_NUMBER_OR_BSUID> ",<!-- CHANGED --> "wa_id": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "ID пользователя": "<BSUID> "<!-- ADDED --> } ], "messages": [ { "id": "<WHATSAPP_MESSAGE_ID> " } ] }Входные данные — Новое значение (BSUID или родительский BSUID).
wa_id — Новое поведение (можно опустить). Вернет номер телефона пользователя, если сообщение было отправлено на этот номер. В противном случае, он будет опущен.user_id — Новое свойство.
Пример ответа на запрос на отправку сообщения, отправленного на номер телефона пользователя (BSUID пользователя или родительский BSUID в запросе не используются):
{ "messaging_product": "whatsapp", "contacts": [ { "input": "+16505551234", "wa_id": "16505551234" } ], "messages": [ { "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA" } ] }Пример ответа на запрос на отправку сообщения, отправленного на BSUID пользователя (номер телефона пользователя в запросе не использовался):
{ "messaging_product": "whatsapp", "contacts": [ { "input": "US.13491208655302741918", "user_id": "US.13491208655302741918" } ], "messages": [ { "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA" } ] }Пример ответа на запрос на отправку сообщения, отправленного на номер телефона пользователя и BSUID (номер телефона пользователя имеет приоритет):
{ "messaging_product": "whatsapp", "contacts": [ { "input": "+16505551234", "wa_id": "16505551234" } ], "messages": [ { "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA" } ] }коды ошибок
Добавление нового кода ошибки в ответ на POST-запрос / конечная точка.
131062Подробности — Для этого сообщения не поддерживаются получатели, использующие идентификаторы пользователей, привязанные к бизнес-процессам (BSUID).API для маркетинговых сообщений в WhatsApp
Отправляйте запросы на маркетинговые сообщения
API маркетинговых сообщений для WhatsApp будет поддерживать как номера телефонов, так и BSUID, а также родительские BSUID. Рекомендуется отправлять сообщения на номера телефонов, в первую очередь для того, чтобы вы могли продолжать получать сообщения на номера телефонов через веб-хуки.
Эти изменения будут применяться к POST / Запросы к конечным точкам.
'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /marketing_messages' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer<ACCESS_TOKEN> ' \ -d ' { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "получатель": "<BSUID> ",<!-- ADDED --> "type": "template", "template": {<EXPECTED_TEMPLATE_PARAMETERS> } }'можно указать как
Кому » (номер телефона), так и «Получателю» В запросе Кому » (номер телефона). При желании можно использовать и один из вариантов:Чтобы отправить сообщение, используя только номер телефона пользователя:
на номер телефона пользователяопустить получателя свойствоЧтобы отправить сообщение, используя только BSUID пользователя или родительский BSUID:
получателя равным BSUID пользователя или родительскому BSUIDопустить to свойствоОтправить маркетинговое сообщение в ответ
Эти изменения касаются POST / Ответы на конечные вопросы.
{ "messaging_product": "whatsapp", "contacts": [ { "input": "<USER_PHONE_NUMBER_OR_ID> ",<!-- CHANGED --> "wa_id": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "ID пользователя": "<BSUID> "<!-- ADDED --> } ], "messages": [ { "id": "<WHATSAPP_MESSAGE_ID> ", "message_status": "<PACING_STATUS> " } ] }Входные данные — Новое значение (BSUID или родительский BSUID).
wa_id — Возвращает номер телефона пользователя, если сообщение было отправлено на этот номер. В противном случае он будет опущен.user_id — Новое свойство.
Пример ответа на отправку шаблонного сообщения на номер телефона пользователя:
{ "messaging_product": "whatsapp", "contacts": [ { "input": "+16505551234", "wa_id": "16505551234" } ], "messages": [ { "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA", "message_status": "accepted" } ] }Пример ответа на отправку шаблонного сообщения пользователю с BSUID:
{ "messaging_product": "whatsapp", "contacts": [ { "input": "US.13491208655302741918", "user_id": "US.13491208655302741918" } ], "messages": [ { "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA", "message_status": "accepted" } ] }тестирование вебхуков
Вы можете протестировать полезные нагрузки веб-хуков, отражающие реальные сценарии использования имен пользователей, используя панель управления приложениями > Варианты использования (значок карандаша) > Связь с клиентами через WhatsApp > Настройка > конфигурации (панель управления приложениями > WhatsApp > Конфигурация для приложений, созданных до декабря 2025 года). Нажмите «Тест» рядом с веб-хуком сообщений, чтобы отправить тестовый веб-хук сообщений на вашу конечную точку веб-хука.
Инструмент тестирования поддерживает веб-хуки для входящих сообщений и веб-хуки для сообщений о состоянии отправленных сообщений в следующих сценариях:
Краткий справочник идентификаторов веб-перехватчиков
В приведенных ниже таблицах кратко описано, какие идентификаторы пользователей будут включены в сообщения веб-хуков, в зависимости от типа веб-хука и от того, зарегистрировал ли пользователь имя пользователя.
Веб-хуки статуса исходящих сообщений
Эти идентификаторы применяются к веб-хукам, отображающим статусы отправки, доставки и прочтения сообщений .
| Идентификатор | Отправлено на указанный номер телефона | Отправлено в BSUID |
|---|---|---|
wa_id | Всегда включено | Включено, если номер телефона доступен в соответствии с для номеров телефонов условиями |
ID пользователя | Всегда включено | Всегда включено |
parent_user_id | Включается, если родительские BSUID включены | Включается, если родительские BSUID включены |
имя пользователя | Включается в список доставленных/прочитанных сообщений, если у пользователя есть имя пользователя | Включается в список доставленных/прочитанных сообщений, если у пользователя есть имя пользователя |
Веб-хуки для входящих сообщений
Эти идентификаторы применяются к входящих сообщений , включая сообщения, инициированные пользователем, и ответы пользователя.
| Идентификатор | У пользователя есть имя пользователя | У пользователя нет имени пользователя |
|---|---|---|
wa_id | Включено, если номер телефона доступен в соответствии с для номеров телефонов условиями | Всегда включено |
ID пользователя | Всегда включено | Всегда включено |
parent_user_id | Включается, если родительские BSUID включены | Включается, если родительские BSUID включены |
имя пользователя | Всегда включено | Не включено |
веб-хуки сообщений
веб-хуки для сообщений о состоянии
Эти изменения будут применяться к для сообщений о статусе .
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " },<!-- Contacts will be included for sent, delivered, and read status --> "контакты": [<!-- ADDED --> { "profile": { "name": "<USER_DISPLAY_NAME> ",<!-- ADDED --><!-- Only included if user has enabled the username feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<USER_PHONE_NUMBER> ",<!-- ADDED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "статусы": [ { "id": "<WHATSAPP_MESSAGE_ID> ", "статус": "<STATUS> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "recipient_id": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "recipient_user_id": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_recipient_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ] }, "field": "messages" } ] } ] }contacts — Новый массив. Включается только для сообщений о статусе «отправлено», «доставлено» и «прочитано». Будет полностью опущен для которые не прошли проверку .
name — Новое свойство. Значение будет установлено равным отображаемому имени пользователя WhatsApp.Имя пользователя — Новое свойство.
отправленных сообщений о статусе или если пользователь не включил функцию имен пользователей.wa_id — Новое свойство.
user_id — Новое свойство. Будет установлено значение BSUID пользователя WhatsApp.parent_user_id пользователя родительский BSUID . В противном случае свойство будет полностью опущено.статусыrecipient_id — Новое поведение (можно опустить).
recipient_user_id — Новое свойство. Будет установлено значение BSUID пользователя или родительского BSUID, если сообщение было отправлено пользователю с таким же BSUID. В противном случае оно будет опущено.parent_user_id пользователя родительский BSUID . В противном случае оно будет полностью опущено.Пример веб-хука для отображения доставленных сообщений о статусе, описывающего сообщение, отправленное компанией, включившей родительские BSUID, на номер телефона пользователя WhatsApp, включившего функцию имен пользователей:
{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "contacts": [ { "profile": { "name": "Pablo M.", "username": "@pablomorales" }, "wa_id": "16505551234", "user_id": "US.13491208655302741918", "parent_user_id": "US.ENT.11815799212886844830" } ], "statuses": [ { "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=", "status": "delivered", "timestamp": "1750030073", "recipient_id": "16505551234", "recipient_user_id": "US.13491208655302741918", "parent_recipient_user_id": "US.ENT.11815799212886844830", "pricing": { "billable": true, "pricing_model": "PMP", "type": "regular", "category": "marketing" } } ] }, "field": "messages" } ] } ] }Пример веб-хука для отображения статуса отправленного сообщения, полученного от компании, в которой включены родительские BSUID, пользователю WhatsApp, в котором включена функция указания имени пользователя. В этом примере мы не можем указать номер телефона пользователя в соответствии с условиями, описанными в Номера телефонов» (поэтому
wa_id и recipient_id опущены).{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "contacts": [ { "profile": { "name": "Pablo M.", "username": "@pablomorales" }, "user_id": "US.13491208655302741918", "parent_user_id": "US.ENT.11815799212886844830" } ], "statuses": [ { "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=", "status": "delivered", "timestamp": "1750030073", "recipient_user_id": "US.13491208655302741918", "parent_user_id": "US.ENT.11815799212886844830", "pricing": { "billable": true, "pricing_model": "PMP", "type": "regular", "category": "marketing" } } ] }, "field": "messages" } ] } ] }Веб-хуки для входящих сообщений
Эти изменения касаются веб-хуков для входящих сообщений (текстовых, графических, интерактивныхи т. д.), включая входящие сообщения, отправленные пользователями в групповом чате.
Приведённый ниже пример синтаксиса предназначен для входящего текстового сообщения, но изменения одинаковы для всех типов входящих сообщений.
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "контакты": [ { "профиль": { "имя": "<WHATSAPP_USER_PROFILE_NAME> ",<!-- Only included if user has enabled the username feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<WHATSAPP_USER_ID> ",<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "сообщения": [ { "из": "<WHATSAPP_USER_PHONE_NUMBER> ",<!-- CHANGED --> "from_user_id": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "from_parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --><!-- Only included if incoming message sent in a group --> "group_id": "<GROUP_ID> ", "идентификатор": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "type": "text", "text": { "body": "<MESSAGE_TEXT_BODY> " } } ] }, "поле": "сообщения" } ] } ] }контактыпрофильИмя пользователя — Новое свойство.
wa_id — Новое поведение (можно опустить).
user_id — Новое свойство, устанавливаемое в значение BSUID пользователя.parent_user_id — Новое свойство. Будет установлено значение родительского BSUID пользователя, если вы включили родительские BSUID. В противном случае оно будет опущено.сообщенияиз — Новое поведение (можно опустить).
from_user_id — Новое свойство, устанавливаемое в значение BSUID пользователя.from_parent_user_id — Новое свойство, устанавливаемое равным BSUID родительского пользователя, если вы включили родительские BSUID. В противном случае оно будет опущено.Пример входящего текстового сообщения от пользователя, у которого включена функция указания имени пользователя, компании, у которой включены родительские BSUID. В этом сценарии мы не можем включить номер телефона пользователя в соответствии с условиями, описанными в Номера телефонов» .
{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "contacts": [ { "profile": { "name": "Sheena Nelson", "username": "@realsheenanelson" }, "user_id": "uUS.13491208655302741918", "parent_user_id": "US.ENT.11815799212886844830" } ], "messages": [ { "from_user_id": "US.13491208655302741918", "from_parent_user_id": "US.ENT.11815799212886844830", "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=", "timestamp": "1749416383", "type": "text", "text": { "body": "Есть ли он в другом цвете?" } } ] }, "field": "messages" } ] } ] }вебхуки для сообщений о состоянии системы
Эти изменения касаются о состоянии системы вебхуков для сообщений
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "сообщения": [ { "из": "<WHATSAPP_USER_PHONE_NUMBER> ", "идентификатор": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "type": "system", "system": { "body": "User...",<!-- CHANGED --> "wa_id": "<NEW_WHATSAPP_USER_ID> ",<!-- CHANGED --> "ID пользователя": "<NEW_BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<NEW_PARENT_BSUID> ",<!-- ADDED --> "тип": "<SYSTEM_CHANGE_TYPE> "<!-- CHANGED --> } } ] }, "field": "messages" } ] } ] }система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 .
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "контакты": [ { "профиль": { "имя": "<WHATSAPP_USER_NAME> ",<!-- Only included if user has enabled the usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<WHATSAPP_USER_ID> ",<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if you have enabled parent BSUIDs --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "user_preferences": [ { "wa_id": "<WHATSAPP_USER_ID> ",<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if you have enabled parent BSUIDs --> "parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "деталь": "<PREFERENCE_DESCRIPTION> ", "category": "marketing_messages", "value": "<PREFERENCE> ", "временная метка":<WEBHOOK_SENT_TIMESTAMP> } ] }, "field": "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.
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "контакты": [ { "профиль": { "имя": "<WHATSAPP_USER_NAME> " }, "wa_id": "<WHATSAPP_USER_ID> " } ], "user_id_update": [ { "wa_id": "<WHATSAPP_USER_ID> ", "подробности": "Идентификатор пользователя для<WHATSAPP_USER_PROFILE_NAME> обновлено."", "user_id": { "previous": "<OLD_BSUID> ", "текущий": "<NEW_BSUID> " },<!-- Only included if parent BSUIDs enabled --> "parent_user_id": { "previous": "<OLD_PARENT_BSUID> ", "текущий": "<NEW_PARENT_BSUID> " }, "временная метка": "<WEBHOOK_SENT_TIMESTAMP> " } ] }, "field": "user_id_update" } ] } ] }контактыwa_id — Будет установлен на номер телефона пользователя, если он доступен. Будет опущен, если пользователь включил функцию имени пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» .обновление идентификатора пользователяwa_id — Будет установлен на номер телефона пользователя, если он доступен. Будет опущен, если пользователь включил функцию имени пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» .Подробности — Удобочитаемое описание обновления.user_id — Объект, содержащий предыдущий и текущий BSUID пользователя.
предыдущий — Старый BSUID пользователя.current — Новый BSUID пользователя.parent_user_id пользователя родительский BSUID, если вы включили отображение родительских BSUID. В противном случае он будет опущен.
предыдущий — старый родительский BSUID пользователя.current — Новый BSUID родительского узла пользователя.метка времени — метка времени Unix, указывающая, когда был отправлен веб-перехватчик.API групп
Получить информацию о группе
Эти изменения касаются GET / Ответы на конечные вопросы.
{ "участники": [ { "wa_id": "<USER_PHONE_NUMBER> "<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only returned if the you have enabled parent BSUIDs --> "parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --><!-- Only returned if the user has enabled the usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> } ], "предмет": "<GROUP_SUBJECT> ", "идентификатор": "<GROUP_ID> ", "messaging_product": "whatsapp" }wa_id — Новое поведение (можно опустить).
user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id пользователя родительского BSUID, если вы включили родительские BSUID. В противном случае оно будет опущено.Имя пользователя — Новое свойство.
Получать запросы на вступление в группу
Эти изменения касаются GET / Ответы на конечные вопросы.
{ "data": [ { "join_request_id": "<JOIN_REQUEST_ID> ", "creation_timestamp": "<JOIN_REQUEST_TIMESTAMP> ", "wa_id": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --><!-- Only included if user has enabled usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> } ], "пагинация": { "курсоры": { "перед": "<BEFORE_CURSOR> ", "после": "<AFTER_CURSOR> " } } }wa_id — Новое поведение (можно опустить).
user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id пользователя родительского BSUID, если вы включили родительские BSUID. В противном случае оно будет опущено.username — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. Будет опущено, если функция имени пользователя не включена.Удалить участников группы
Эти изменения касаются команды DELETE / Запросы к конечным точкам.
curl -g -X DELETE 'https://graph.facebook.com/<API_VERSION> /<GROUP_ID> /participants' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer<ACCESS_TOKEN> ' \ -d ' { "messaging_product": "whatsapp", "participants": [ { "user": "<USER_PHONE_NUMBER> "<!-- CHANGED --> } ] }'пользователь — Принимает номер телефона пользователя или BSUID.Веб-хуки API групп
Веб-хуки для сообщений о состоянии групп
Эти изменения будут применяться к
доставке и прочтениисообщений о для сообщений, отправляемых группе.{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " },<!-- Contacts will be included for delivered and read status --> "контакты": [<!-- ADDED --> { "profile": { "name": "<USER_DISPLAY_NAME> ",<!-- ADDED --><!-- Only included if user has enabled usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<USER_PHONE_NUMBER> ",<!-- ADDED --> "ID пользователя": "<BSUID> ",<!-- ADDED --> <-- Включается только при включении родительских BSUID --> "parent_user_id": "<PARENT_BSUID> " }, # Дополнительные объекты контактов будут добавлены, если они будут агрегированы { ... } ], "statuses": [ { "id": "<WHATSAPP_MESSAGE_ID> ", "статус": "<STATUS> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "recipient_id": "<GROUP_ID> ", "recipient_type": "group", "recipient_participant_id": "<GROUP_PARTICIPANT_USER_PHONE_NUMBER> ",<!-- CHANGED --> "recipient_participant_user_id": "<BSUID> «, <-- ДОБАВЛЕНО --><!-- Only included if parent BSUIDs enabled --> "recipient_participant_parent_user_id": "<PARENT_BSUID> «, <-- ДОБАВЛЕНО --><!-- Omitted for v24.0+ unless webhook is for a free entry point conversation --> "разговор": { "id": "<CONVERSATION_ID> ", "expiration_timestamp": "<CONVERSATION_EXPIRATION_TIMESTAMP> ", "origin": { "type": "<CONVERSATION_CATEGORY> " } }, "ценообразование": { "оплачиваемый":<IS_BILLABLE?> , "pricing_model": "<PRICING_MODEL> ", "тип": "<PRICING_TYPE> ", "категория": "<PRICING_CATEGORY> " } }, # Дополнительные объекты статуса будут добавлены, если они агрегированы { ... } ] }, "field": "messages" } ] } ] }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 .
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "группы": [ { "временная метка":<WEBHOOK_TRIGGER_TIMESTAMP> , "group_id": "<GROUP_ID> ",<!-- Only if business removes participant from group --> "type": "group_participants_remove", "request_id": "REQUEST_ID", "removed_participants": [ { "input": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> } ], "инициировано_кем": "бизнес"<!-- Only if user removes themself from group --> "type": "group_participants_remove", "request_id": "REQUEST_ID", "removed_participants": [ { "wa_id": "<USER_PHONE_NUMBER> "<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --> "parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "имя пользователя": "<USERNAME> "<!-- ADDED --> } ], "инициировано_участником": "участник"<!-- Only if user joins group via invite link --> "type": "group_participants_add", "reason": "invite_link", "added_participants": [ { "wa_id": "<USER_PHONE_NUMBER> "<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --> "parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "имя пользователя": "<USERNAME> "<!-- ADDED --> } ]<!-- Only if join request created --> "type": "group_join_request_created", "join_request_id": "<JOIN_REQUEST_ID> ", "wa_id": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --> "parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "имя пользователя": "<USERNAME> "<!-- ADDED --><!-- Only if join request revoked --> "type": "group_join_request_revoked", "join_request_id": "<JOIN_REQUEST_ID> ", "wa_id": "<USER_PHONE_NUMBER> "<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --> "parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "имя пользователя": "<USERNAME> "<!-- ADDED --> } ] }, "field": "group_participants_update" } ] } ] }Входные данные — Новое значение (BSUID или родительский BSUID).
wa_id — Новое поведение (можно опустить).
user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id пользователя родительский BSUID Если включена поддержка родительских BSUID,username — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. В противном случае оно будет опущено.API блокировки пользователей
Блокировать или разблокировать запросы пользователей
Эти изменения касаются запросов POST и DELETE для блокировки пользователей . В этом примере показан синтаксис запроса на блокировку пользователя, но изменения также применимы к запросам на разблокировку.
curl 'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /block_users' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer<ACCESS_TOKENS> ' \ -d ' { "messaging_product": "whatsapp", "block_users": [ { "user": "<USER_PHONE_NUMBER> " }, { "ID пользователя": "<BSUID> "<!-- ADDED --> } ] }'можно указать как
имя пользователя (номер телефона), так и идентификатор пользователя В запросе имени пользователя (номеру телефона). При желании можно использовать либо одно, либо другое:Чтобы заблокировать или разблокировать пользователя, используя только его номер телефона:
пользователя на номер телефона пользователяне следует указывать. user_id ОбъектЧтобы заблокировать или разблокировать пользователя, используя только его BSUID или родительский BSUID:
user_id равным BSUID пользователя или родительскому BSUID.Опустить пользователя объектБлокировать или разблокировать ответы на запросы
Эти изменения будут применяться к ответам на запросы POST и DELETE Block Users .
{ "messaging_product": "whatsapp", "block_users": { "added_users": [ { "input": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "wa_id": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "ID пользователя": "<BSUID> "<!-- ADDED --> } ] } }Входные данные — Новое значение (BSUID или родительский BSUID).
wa_id — Новое поведение (можно опустить).
user_id — Новое свойство.
Получить заблокированных пользователей
Эти изменения касаются ответов GET Block Users .
Синтаксис ответа:
{ "data": [ { "messaging_product": "whatsapp", "wa_id": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "пагинация": { "курсоры": { "после": "<AFTER_CURSOR> ", "до": "<BEFORE_CURSOR> " } } }wa_id — Будет установлен на номер телефона пользователя, если он доступен. Будет опущен, если пользователь включил функцию имени пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» .user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id пользователя родительский BSUID Если включена поддержка родительских BSUID,Вызов API
Запросы на звонки, инициированные предприятиями
Изменения касаются запросов к API, инициированных бизнес-процессами.
'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /calls' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer<ACCESS_TOKEN> ' \ -d ' { "messaging_product": "whatsapp", "to": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "получатель": "<BSUID> ",<!-- ADDED --> "action": "connect", "session": { "sdp_type": "offer", "sdp": "<RFC_4566_SDP> " } }'можно указать как
Кому » (номер телефона), так и «Получателю» В запросе Кому » (номер телефона). При желании можно использовать и один из вариантов:Чтобы позвонить пользователю, используя только его номер телефона:
на номер телефона пользователяопустить получателя свойствоЧтобы позвонить пользователю, используя только его BSUID или родительский BSUID:
получателя равным BSUID пользователя или родительскому BSUIDопустить to свойствоПолучить разрешения на совершение звонков
Изменения касаются запросов на получение разрешений на вызов . Ответы остаются без изменений.
Получение разрешений на совершение звонков с использованием номера телефона пользователя:
curl 'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /call_permissions?user_wa_id=<USER_PHONE_NUMBER> ' \ -H 'Авторизация: Предъявитель<ACCESS_TOKEN> ' \
user_wa_id — Устанавливается в номер телефона пользователя.Получение разрешений на вызовы с использованием BSUID пользователя или родительского BSUID:
curl 'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /call_permissions?recipient=<BSUID> ' \ -H 'Авторизация: Предъявитель<ACCESS_TOKEN> ' \
получатель — устанавливается в значение BSUID пользователя или родительского BSUID.Отправить запрос на разрешение вызова
См. раздел «Отправка запросов на сообщения».
Вызов веб-хуков для запроса разрешения
Эти изменения будут применяться к вебхукам для обработки интерактивных сообщений, .
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "контакты": [ { "профиль": { "имя": "<WHATSAPP_USER_PROFILE_NAME> ",<!-- Only included if user has enabled the usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<WHATSAPP_USER_ID> ",<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "сообщения": [ { "контекст": { "из": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "идентификатор": "<CONTEXTUAL_WHATSAPP_MESSAGE_ID> " }, "от": "<WHATSAPP_USER_PHONE_NUMBER> ",<!-- CHANGED --> "from_user_id": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "from_parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> "идентификатор": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "type": "interactive", "interactive": { "type": "call_permission_reply", "call_permission_reply": { "response": accept, "expiration_timestamp": "<EXPIRATION_TIMTESTAMP> ", "response_source": "<RESPONSE_SOURCE> " } } } ] }, "field": "messages" } ] } ] }контактыпрофильusername — Новое свойство. Будет установлено значение имени пользователя, если пользователь указал имя пользователя. Будет опущено, если пользователь не использует имя пользователя.wa_id — Новое свойство.
user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id пользователя родительский BSUID Если включена поддержка родительских BSUID,сообщенияиз — Новое поведение (можно опустить).
from_user_id — Новое свойство. Будет установлено значение BSUID пользователя.Веб-хуки для инициированных бизнесом подключенных звонков
Эти изменения касаются веб-хуков для инициированных компанией подключенных звонков .
{ "entry": [ { "changes": [ { "field": "calls", "value": { "contacts": [<!-- ADDED --> { "профиль": {<!-- Only included if user has enabled the usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<USER_PHONE_NUMBER> ",<!-- ADDED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "вызовы": [ { "biz_opaque_callback_data": "<DATA> ", "session": { "sdp_type": "answer", "sdp": "<SDP> " }, "от": "<BUSINESS_PHONE_NUMBER> ", "идентификатор": "<WHATSAPP_CALL_ID> ", "к": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "to_user_id": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "to_parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "событие": "подключиться", "метка времени": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "direction": "BUSINESS_INITIATED" } ], "metadata": { "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> ", "display_phone_number": "<BUSINESS_PHONE_NUMBER> " }, "messaging_product": "whatsapp" } } ], "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> " } ], "object": "whatsapp_business_account" }Контакты — Новый массив.
профильИмя пользователя — Новое свойство.
wa_id — Новое свойство.
user_id — Новое свойство. Будет установлено значение BSUID пользователя WhatsApp.parent_user_id пользователя родительский BSUID Если включена поддержка родительских BSUID,звонки— Новое поведение (можно опустить). Будет установлено значение номера телефона пользователя, если пользователь зарегистрировал имя пользователя и мы можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае оно будет опущено.to_user_id — Новое свойство. Будет установлено значение BSUID пользователя.to_parent_user_id пользователя родительского BSUID, если вы включили родительские BSUID. В противном случае свойство будет полностью опущено.Веб-хуки для инициированных пользователем подключенных звонков
Эти изменения будут применяться к вебхукам для инициированных пользователем подключенных звонков .
{ "entry": [ { "changes": [ { "field": "calls", "value": { "metadata": { "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> ", "display_phone_number": "<BUSINESS_PHONE_NUMBER> " }, "calls": [ { "session": { "sdp_type": "offer", "sdp": "<SDP> " }, "от": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "from_user_id": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "from_parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "идентификатор": "<WHATSAPP_CALL_ID> ", "к": "<BUSINESS_PHONE_NUMBER> ", "событие": "подключение", "метка времени": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "direction": "USER_INITIATED" } ], "contacts": [ { "wa_id": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "профиль": { "имя": "<USER_DISPLAY_NAME> ",<!-- ADDED --><!-- Only included if user has enabled usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "ID пользователя": "<BSUID> "<!-- ADDED --> ,<!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "messaging_product": "whatsapp" } } ], "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> " } ], "object": "whatsapp_business_account" }звонки— Новое поведение (может быть опущено). Будет опущено, если для имени пользователя включена функция имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» . В противном случае будет установлен номер телефона пользователя.from_user_id — Новое свойство. Будет установлено значение BSUID пользователя.from_parent_user_id пользователя родительский BSUID . В противном случае оно будет опущено.контактыwa_id — Новое поведение (можно опустить).
name — Новое свойство. Будет установлено на имя профиля пользователя.username — Новое свойство. Если пользователь указал имя пользователя, оно будет установлено на это имя. В противном случае оно будет опущено.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id пользователя родительский BSUID Если включена поддержка родительских BSUID,Веб-хуки для завершения инициированных бизнесом звонков
Эти изменения касаются хуков, применяемых к инициированным и завершенным .
{ "entry": [ { "changes": [ { "field": "calls", "value": { "calls": [ { "biz_opaque_callback_data": "<BUSINESS_OPAQUE_DATA> ", "от": "<BUSINESS_PHONE_NUMBER> ", "идентификатор": "<WHATSAPP_CALL_ID> ", "к": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "to_user_id": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "to_parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "событие": "завершить", "метка времени": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "direction": "BUSINESS_INITIATED", "status": "COMPLETED" } ], "metadata": { "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> ", "display_phone_number": "<BUSINESS_PHONE_NUMBER> " }, "контакты": [<!-- ADDED --> { "профиль": {<!-- Only included if user has enabled the usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<USER_PHONE_NUMBER> ",<!-- ADDED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "messaging_product": "whatsapp" } } ], "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> " } ], "object": "whatsapp_business_account" }звонки— Новое поведение (можно опустить). Будет установлено значение номера телефона пользователя, если пользователь зарегистрировал имя пользователя и мы можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае оно будет опущено.to_user_id — Новое свойство. Ему будет присвоен BSUID пользователя.to_parent_user_id пользователя родительский BSUID . В противном случае оно будет опущено.Контакты — Новый массив.
профильusername — Новое свойство. Если пользователь указал имя пользователя, оно будет установлено на это имя. В противном случае оно будет опущено.wa_id — Новое свойство. Если завершающийся вызов был совершен на этот номер телефона, значение будет установлено на номер телефона пользователя. В противном случае оно будет опущено.user_id — Новое свойство. Ему будет присвоен BSUID пользователя.parent_user_id пользователя родительский BSUID Если включена поддержка родительских BSUID,Веб-хуки для завершения вызовов, инициированных пользователем
инициированных пользователем для завершенных вызовов, .
{ "entry": [ { "changes": [ { "field": "calls", "value": { "metadata": { "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> ", "display_phone_number": "<BUSINESS_PHONE_NUMBER> " }, "вызовы": [ { "продолжительность":<CALL_DURATION> , "start_time": "<CALL_START_TIMESTAMP> ", "biz_opaque_callback_data": "<BUSINESS_OPAQUE_DATA> ", "end_time": "<CALL_END_TIMESTAMP> ", "от": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "from_user_id": "<BSUID> ",<!-- ADDED --><!-- Only included if you have enabled parent BSUIDs --> "from_parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "идентификатор": "<WHATSAPP_CALL_ID> ", "к": "<BUSINESS_PHONE_NUMBER> ", "событие": "завершить", "метка времени": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "direction": "USER_INITIATED", "status": "COMPLETED" } ], "contacts": [ { "profile": { "name": "<USER_PROFILE_NAME> "<!-- ADDED --><!-- Only included if user has enabled the usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if you have enabled parent BSUIDs --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "messaging_product": "whatsapp" } } ], "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> " } ], "object": "whatsapp_business_account" }звонки— Новое поведение (может быть опущено). Будет опущено, если пользователь включил функцию имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае будет установлен номер телефона пользователя.from_user_id — Новое свойство. Будет установлено значение BSUID пользователя.from_parent_user_id , оно будет установлено на родительский BSUID пользователя родительские BSUID. В противном случае оно будет опущено.контактыпрофильname — Новое свойство. Оно будет установлено на имя профиля пользователя.username — Новое свойство. Если пользователь указал имя пользователя, оно будет установлено на это имя. В противном случае оно будет опущено.wa_id — Будет опущено, если пользователь включил функцию имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае будет установлен номер телефона пользователя.user_id — Новое свойство. Ему будет присвоен BSUID пользователя.parent_user_id пользователя родительского BSUID, если вы включили родительские BSUID. В противном случае оно будет опущено.Веб-хуки для отслеживания статуса инициированных бизнес-звонков
Эти изменения коснутся статус инициированных бизнес-запросов .
{ "entry": [ { "changes": [ { "field": "calls", "value": { "statuses": [ { "biz_opaque_callback_data": "<BUSINESS_OPAQUE_DATA> ", "идентификатор": "<WHATSAPP_CALL_ID> ", "type": "call", "status": "<STATUS> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "recipient_id": "<USER_PHONE_NUMBER> ",<!-- CHANGED --> "recipient_user_id": "<BSUID> ",<!-- ADDED --><!-- Only included if you have enabled parent BSUIDs --> "recipient_parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "метаданные": { "идентификатор_номера_телефона": "<BUSINESS_PHONE_NUMBER_ID> ", "display_phone_number": "<BUSINESS_PHONE_NUMBER> " }, "контакты": [<!-- ADDED --> { "профиль": {<!-- Only included if user has enabled the usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<USER_PHONE_NUMBER> ",<!-- ADDED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if you have enabled parent BSUIDs --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "messaging_product": "whatsapp" } } ], "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> " } ], "object": "whatsapp_business_account" }статусыrecipient_id — Новое поведение (можно опустить).
recipient_user_id — Новое свойство. Ему будет присвоен BSUID пользователя.recipient_parent_user_id пользователя родительского BSUID, если вы включили родительские BSUID. В противном случае оно будет опущено.Контакты — Новый массив.
профильusername — Новое свойство. Будет установлено значение имени пользователя, если у пользователя включена функция имен пользователей. В противном случае оно будет опущено.wa_id — Новое свойство. Если звонок был совершен на этот номер телефона, значение будет установлено на номер телефона пользователя. В противном случае оно будет опущено.user_id — Новое свойство. Ему будет присвоен BSUID пользователя.parent_user_id пользователя родительского BSUID, если вы включили родительские BSUID. В противном случае оно будет опущено.SIP-приглашения для инициированных бизнесом звонков
Эти изменения касаются инициированных бизнес-звонков, совершаемых с использованием протокола SIP.
ПРИГЛАШЕНИЕ: глоток[email protected]>;tag=Kc9QZg4496maQ К: [email protected]:35181;transport=tls;swrad=137.184.87.1~56533~3> User-Agent: SignalWire Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY Supported: timer, path, replaces Allow-Events: talk, hold, conference, refer Session-Expires: 600;refresher=uac Min-SE: 90 Content-Type: application/sdp Content-Disposition: session Content-Length: 2427 X-Relay-Call-ID: dc2c5b33-1b81-43ee-9213-afb56f4e56ba Remote-Party-ID: [email protected]>;party=calling;screen=yes;privacy=off Content-Type: application/sdp Content-Length: 2427
SIP-приглашения для инициированных пользователем вызовов
Эти изменения касаются инициированных пользователем вызовов, совершаемых с использованием протокола SIP.
INVITE sip:[email protected];transport=tls SIP/2.0 Via: SIP/2.0/TLS [2803:6080:e888:51aa:d4a4:c5e0:300:0]:33819;rport=33819;received=2803:6080:e888:51aa:d4a4:c5e0:300:0;branch=z9hG4bKPjNvs.IZBnUa1W4l8oHPpk3SUMmcx3MMcE;alias Max-Forwards: 70 От: "[email protected]> Контакт:
<BSUID> — Будет установлено значение, равное BSUID пользователя.<BSUID_OR_PHONE_NUMBER> — В случае, если звонок был совершен на BSUID пользователя или родительский BSUID, или если пользователь присвоил имя пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» . В противном случае будет использоваться номер телефона пользователя.<PARENT_BSUID> значение будет установлено равным родительскому BSUID пользователя родительские BSUID. В противном случае оно будет опущено.<USERNAME> — Будет использоваться имя пользователя, если у пользователя включена функция отображения имен пользователей. В противном случае оно будет опущено.SIP OK-ответы для звонков, инициированных бизнес-процессом
SIP/2.0 200 OK Via: SIP/2.0/TLS 54.172.60.1:5061;received=2803:6080:f934:8894:7eb5:24f9:300:0;branch=z9hG4bK1e5a.0da2ace9cc912d9e5f2595ca4acb9847.0 Via: SIP/2.0/UDP 172.25.10.217:5060;rport=5060;branch=z9hG4bK5cdada8c-cbf0-4369-b02d-cc97d3c36f2b_c3356d0b_54-457463274351249162 Record-Route: [email protected] От: "[email protected]>;tag=0d185053-2615-46c7-8ff2-250bda494cf1 CSeq: 2 INVITE Allow: INVITE, ACK, BYE, CANCEL, NOTIFY, OPTIONS Supported: timer X-FB-External-Domain: wa.meta.vc
<BSUID> — Будет установлено значение, равное BSUID пользователя.<BSUID_OR_PHONE_NUMBER> — В случае, если звонок был совершен на BSUID пользователя или родительский BSUID, или если пользователь присвоил имя пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» . В противном случае будет использоваться номер телефона пользователя.<PARENT_BSUID> значение будет установлено равным родительскому BSUID пользователя родительские BSUID. В противном случае оно будет опущено.<USERNAME> — Будет установлено значение, равное имени пользователя, если у пользователя включена функция отображения имен пользователей. В противном случае оно будет опущено.SIP BYE-ответы для вызовов, инициированных как компанией, так и пользователем
BYE sip:[email protected]:5061;transport=tls SIP/2.0 Via: SIP/2.0/TLS [2803:6080:e800:6746::]:56843;rport;branch=z9hG4bKPj65946b3e6f68128d52b6a498a8fd00a5;alias Record-Route: [email protected]>;tag=2c21fad0-c581-4e54-a707-3bd52abfcc3f Call-ID: 21e38222-6fcb-4631-8e7d-5b94cf849c90 CSeq: 31641 BYE x-wa-meta-user-id:
<BSUID> — Будет установлено значение, равное BSUID пользователя.<BSUID_OR_PHONE_NUMBER> — В случае, если звонок был совершен на BSUID пользователя или родительский BSUID, или если пользователь присвоил имя пользователя, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» . В противном случае будет использоваться номер телефона пользователя.<PARENT_BSUID> значение будет установлено равным родительскому BSUID пользователя родительские BSUID. В противном случае оно будет опущено.<USERNAME> — Будет установлено значение, равное имени пользователя, если у пользователя включена функция отображения имен пользователей. В противном случае оно будет опущено.Сосуществование
История веб-хуков
Эти изменения коснутся истории , описывающих историю чатов в приложении WhatsApp Business для зарегистрированных бизнес-клиентов.
{ "object": "whatsapp_business_account", "entry": [ { "id": "<CUSTOMER_WABA_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<CUSTOMER_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<CUSTOMER_PHONE_NUMBER_ID> " }, "история": [ { "метаданные": { "фаза":<PHASE> , "chunk_order":<CHUNK_ORDER> , "прогресс":<PROGRESS> }, "threads": [ /* Первый объект истории чата */ { "id": "<WHATSAPP_USER_PHONE_NUMBER> ",<!-- CHANGED --> "контекст": {<!-- ADDED --> "wa_id": "<WHATSAPP_USER_PHONE_NUMBER> ",<!-- ADDED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled before sync request --> "parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --><!-- Only included if user has enabled usernames feature before sync request --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "messages": [ /* Первый объект сообщения в потоке */ { "from": "<BUSINESS_OR_WHATSAPP_USER_PHONE_NUMBER> ",<!-- CHANGED --> "from_user_id" : "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled before sync request --> "from_parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "к": "<WHATSAPP_USER_PHONE_NUMBER> ", "идентификатор": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<DEVICE_TIMESTAMP> , "тип": "<MESSAGE_TYPE> ", "<MESSAGE_TYPE> ": {<MESSAGE_CONTENTS> }, "history_context": { "status": "<MESSAGE_STATUS> " } }, /* Дополнительные объекты сообщений в ветке будут добавлены, если таковые имеются */ ] }, /* Дополнительные объекты истории чата будут добавлены, если таковые имеются */ ] } ] }, "поле": "история" } ] } ] }id — Новое поведение (может быть опущено). Будет опущено, если на момент запроса на синхронизацию истории у пользователя уже включена возможность добавления имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в разделе « Номера телефонов» . В противном случае будет установлен номер телефона пользователя.контекст — Новый объект контекста.
wa_id — Новое свойство.
user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id пользователя равное родительскому BSUID, если вы включили родительские BSUID. В противном случае оно будет опущено.Имя пользователя — Новое свойство.
сообщенияиз — Новое поведение (можно опустить).
from_user_id — Новое свойство. Будет установлено значение BSUID пользователя.from_parent_user_id пользователя равное родительскому BSUID, если вы включили родительские BSUID. В противном случае оно будет опущено.Эти изменения коснутся истории , описывающих медиафайлы, отправленные пользователем WhatsApp корпоративному клиенту или наоборот.
{ "object": "whatsapp_business_account", "entry": [ { "id": "<CUSTOMER_WABA_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<CUSTOMER_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<CUSTOMER_PHONE_NUMBER_ID> " }, "контакты": [<!-- ADDED --> {<!-- Profile only included if user has enabled the usernames feature --> "профиль": { "имя пользователя": "<USERNAME> ",<!-- ADDED --> }, "wa_id": "<WHATSAPP_USER_PHONE_NUMBER> ",<!-- ADDED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> }, ],<!-- Only for messages sent from a user to a business --> "сообщения": [ { "от": "<WHATSAPP_USER_PHONE_NUMBER> ",<!-- CHANGED --> "from_user_id": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "from_parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "идентификатор": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<ORIGINAL_WEBHOOK_TRIGGER_TIMESTAMP> ", "тип": "<MEDIA_TYPE> ", "<MEDIA_TYPE> ": {<MEDIA_METADATA> } } ],<!-- Only for messages sent from a business to a user --> "message_echoes": [ { "from": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "к": "<WHATSAPP_USER_PHONE_NUMBER> ",<!-- CHANGED --> "to_user_id": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "to_parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "идентификатор": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "тип": "<MESSAGE_TYPE> ", "<MESSAGE_TYPE> ": {<MESSAGE_CONTENTS> } } ] }, "поле": "история" } ] } ] }Контакты — Новый объект.
профиль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 .
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "контакты": [<!-- ADDED --> {<!-- Only included if user has enabled the usernames feature --> "профиль": { "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<WHATSAPP_USER_PHONE_NUMBER> ",<!-- ADDED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "message_echoes": [ { "from": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "к": "<WHATSAPP_USER_PHONE_NUMBER> ",<!-- CHANGED --> "to_user_id": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "to_parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --> "идентификатор": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "тип": "<MESSAGE_TYPE> ", "<MESSAGE_TYPE> ": {<MESSAGE_CONTENTS> } } ] }, "field": "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 .
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "state_sync": [ { "type": "contact", "contact": { "full_name": "<CONTACT_FULL_NAME> ", "имя": "<CONTACT_FIRST_NAME> ", "номер телефона": "<CONTACT_PHONE_NUMBER> ",<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> ",<!-- ADDED --><!-- Only included if user has enabled the usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "действие": "<ACTION> ", "метаданные": { "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> " } },<!-- Additional contacts would follow, if any --> ] }, "field": "smb_app_state_sync" } ] } ] }phone_number — Новое поведение (можно опустить). Будет опущено, если на момент запроса на синхронизацию у пользователя уже включена возможность использования имен пользователей, и мы не можем включить его номер телефона в соответствии с условиями, описанными в Номера телефонов» . В противном случае будет установлен номер телефона пользователя.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id пользователя равное родительскому BSUID, если вы включили родительские BSUID. В противном случае оно будет опущено.username — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. В противном случае оно будет опущено.Отзыв сообщений через веб-хуки
Эти изменения будут применяться к отзыва сообщений .
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "контакты": [ { "профиль": { "имя": "<WHATSAPP_USER_PROFILE_NAME> ",<!-- Only included if user has enabled the usernames feature --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<WHATSAPP_USER_ID> ", "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "сообщения": [ { "из": "<WHATSAPP_USER_PHONE_NUMBER> ", "идентификатор": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "type": "revoke", "revoke": { "original_message_id": "<ORIGINAL_WHATSAPP_MESSAGE_ID> " } } ] }, "поле": "сообщения" } ] } ] }контактыпрофильusername — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. В противном случае оно будет опущено.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id родительского пользователя BSUID . В противном случае оно будет опущено.Веб-хуки для редактирования сообщений
Эти изменения будут применяться к редактирования сообщений .
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "контакты": [ { "профиль": { "имя": "<WHATSAPP_USER_PROFILE_NAME> ",<!-- Only included if the user has enabled usernames --> "имя пользователя": "<USERNAME> "<!-- ADDED --> }, "wa_id": "<WHATSAPP_USER_ID> ",<!-- CHANGED --> "ID пользователя": "<BSUID> ",<!-- ADDED --><!-- Only included if parent BSUIDs enabled --> "parent_user_id": "<PARENT_BSUID> "<!-- ADDED --> } ], "сообщения": [ { "из": "<WHATSAPP_USER_PHONE_NUMBER> ", "идентификатор": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "type": "edit", "edit": { "original_message_id": "<ORIGINAL_WHATSAPP_MESSAGE_ID> ", "сообщение": { "контекст": { "идентификатор": "<CONTEXT_ID> " }, "type": "image", "image": { "caption": "<MEDIA_ASSET_CAPTION> ", "mime_type": "<MEDIA_ASSET_MIME_TYPE> ", "sha256": "<MEDIA_ASSET_SHA256_HASH> ", "идентификатор": "<MEDIA_ASSET_ID> ", "url": "<MEDIA_ASSET_URL> " } } } } ] }, "поле": "сообщения" } ] } ] }контактыпрофильusername — Новое свойство. Будет установлено значение имени пользователя, если функция имени пользователя включена. В противном случае оно будет опущено.wa_id — Новое свойство. Будет опущено, если на момент редактирования сообщения пользователем WhatsApp функция добавления имен пользователей уже включена, и номер телефона не может быть указан в соответствии с условиями, описанными в Номера телефонов» . В противном случае оно будет опущено.user_id — Новое свойство. Будет установлено значение BSUID пользователя.parent_user_id родительского пользователя BSUID . В противном случае оно будет опущено.Аналитика
Без изменений.
Выставление счетов и формирование инвойсов
Без изменений.
Часто задаваемые вопросы
Что мне нужно сделать, чтобы добавить поддержку имен пользователей?
Идентификаторы BSUID и родительские BSUID начнут появляться в полезных нагрузках веб-хуков в марте 2026 года, до того, как имена пользователей станут доступны пользователям WhatsApp. Для обработки сообщений от пользователей, которые включат эту функцию после ее появления, вам потребуется поддерживать 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 .