Подключение пользователей приложения WhatsApp Business (так называемое "сосуществование") | Документация для разработчиков
Внедрение приложения WhatsApp Business для новых пользователей (так называемое "сосуществование")
Обновлено: 20 марта 2026 г
Вы можете настроить встроенную регистрацию, чтобы бизнес-клиенты могли регистрироваться, используя свою существующую приложения WhatsApp Business . Клиенты, успешно прошедшие регистрацию после выбора этой опции, смогут использовать ваше приложение для массовой рассылки сообщений своим клиентам, но при этом сохранят возможность отправлять сообщения индивидуально через приложение WhatsApp Business, сохраняя при этом синхронизацию истории переписки между обоими приложениями.
Как это работает
При настройке встроенной регистрации телефонных номеров для приложения WhatsApp Business, корпоративному клиенту, прошедшему соответствующую процедуру, будет предоставлена возможность подключить свою существующую учетную запись приложения WhatsApp Business к Cloud API:
Если они выберут этот вариант и введут номер телефона, указанный в приложении WhatsApp Business, им будет предложен код подтверждения для ввода.
В сообщении компании предлагается скопировать код подтверждения и выполнить следующие действия:
Ожидайте сообщения от официального бизнес-аккаунта Facebook. Нажмите «Подключить»:
Нажмите кнопку «Подключиться к бизнес-платформе», чтобы продолжить процесс подключения.
Нажмите кнопку «Подтвердить» в приложении, чтобы разрешить компании поделиться с вами историей переписки.
Вставьте проверочный код.
Они могут завершить оставшуюся часть процесса встроенной регистрации. Это возвращает их идентификаторы активов и код обмениваемого токена в окно запуска, как обычно. Затем вы можете использовать эту информацию в вызовах API для (1) регистрации бизнес-клиента так же, как и любого другого бизнес-клиента, и (2) синхронизации его контактов и истории сообщений (если это разрешено компанией), чтобы вы могли заполнить ее в своем приложении.
Требования
Ограничения
Неподдерживаемые страны
Номера телефонов учетных записей WhatsApp Business со странами, имеющими коды следующих стран, не поддерживаются:
Цены
После подключения бизнес-клиента к Cloud API сообщения, отправляемые компанией через приложение WhatsApp Business, по-прежнему будут бесплатными, но сообщения, отправляемые через API, будут облагаться тарифами Cloud API .
Ознакомьтесь с нашим API-решения для пользователей приложения WhatsApp Business, где представлены распространенные сценарии ценообразования.
окно обслуживания клиентов
Окна службы поддержки клиентов будут открываться только тогда, когда пользователь WhatsApp отправит сообщение бизнес-клиенту, уже подключенному к Cloud API. Если пользователь WhatsApp отправит сообщение компании непосредственно перед ее подключением к Cloud API, компания сможет ответить только шаблонным сообщением, поскольку окно службы поддержки клиентов еще не было открыто. Если пользователь отправит сообщение компании после ее подключения к Cloud API, окно службы поддержки клиентов откроется в обычном режиме, и компания сможет ответить обычным сообщением.
Ограничение на 24-часовой срок обслуживания клиентов распространяется на сообщения, отправленные через Cloud API. Сообщения, отправленные из приложения WhatsApp Business, не подпадают под действие этого ограничения и не создают, не продлевают и не влияют на сроки обработки сообщений в Cloud API или на цены Cloud API.
Сравнение характеристик
В таблице ниже описаны функции, доступные корпоративным клиентам, подключившимся к Cloud API, а также любые изменения в функциональности приложения WhatsApp Business после подключения.
| Существующая функция в приложении WhatsApp Business | Изменения в функциональности приложения WhatsApp Business ПОСЛЕ подключения к облачному API | Поддерживается ли функция приложения WhatsApp Business в облачном API? |
|---|---|---|
Индивидуальные (1:1) чаты | Теперь поддерживается редактирование/отмена сообщений. | Поддерживается. Все сообщения чата за последние 6 месяцев можно синхронизировать. Сообщения, отправленные и полученные, дублируются между облачным API и приложением WhatsApp Business. |
Контакты | Без изменений. | Поддерживается. Все контакты, имеющие номер WhatsApp, могут быть синхронизированы. |
Групповые чаты | Без изменений. | Не поддерживается. Групповые чаты синхронизироваться не будут. |
Исчезающие сообщения | Функция исчезающих сообщений будет отключена для всех индивидуальных (1:1) чатов | Не поддерживается. |
Функция просмотра сообщений один раз будет отключена для всех индивидуальных (1:1) чатов | Не поддерживается. | |
Сообщение о местоположении в реальном времени | Сообщения о местоположении в реальном времени будут отключены для всех индивидуальных (1:1) чатов | Не поддерживается. |
Списки рассылки | Список рассылок будет отключен. Предприятия не смогут создавать новые списки рассылки. Существующие списки рассылки станут доступны только для чтения. | Не поддерживается. |
Голосовые и видеозвонки | Без изменений. | Не поддерживается. |
Инструменты для бизнеса (например, каталог, заказы, статус) | Без изменений. | Не поддерживается. |
Инструменты обмена сообщениями (например, маркетинговые сообщения, приветственные сообщения, сообщения об отсутствии, быстрые ответы, метки) | Без изменений. | Не поддерживается. |
Профиль компании (например, название компании, адрес, веб-сайт) | Без изменений. | Не поддерживается. |
Каналы | Без изменений. | Не поддерживается. |
Связанные устройства
Компании могут подключить до четырех дополнительных клиентов WhatsApp к своей учетной записи WhatsApp Business на других устройствах ( в нашем Справочном центре подключенными устройствами »
Поддерживаются все сопутствующие приложения, за исключением WhatsApp для Windows и WhatsApp для WearOS .
После того как корпоративный клиент подключится к Cloud API, используя существующую учетную запись и номер приложения WhatsApp Business, все сопутствующие приложения будут отвязаны от учетной записи, и компания сможет повторно подключить любые поддерживаемые сопутствующие приложения.
Пользователи WhatsApp, использующие неподдерживаемое приложение-компаньон для отправки сообщений подключенной компании, могут это сделать, но сообщение не будет запускать сообщений , поэтому компания не сможет отобразить это сообщение в своем собственном приложении.
Сообщения, отправленные зарегистрированной компанией (любым способом) и просмотренные на неподдерживаемом дополнительном устройстве, будут отображаться с текстом-заполнителем, указывающим пользователю WhatsApp на необходимость просмотра сообщения на основном устройстве.
Настройка вашего приложения
Шаг 1: Подпишитесь на веб-хуки
Перейдите в Панель управления приложениями > WhatsApp > конфигурации и подпишите ваше приложение на следующие поля темы веб-перехватчика учетной записи WhatsApp Business, а также убедитесь, что код обратного вызова вашего приложения может обрабатывать данные для каждого из них. Обратите внимание, что эти поля добавляются к любым полям, на которые вы уже подписаны как поставщик решения.
Шаг 2: Настройка встроенной формы регистрации
Добавьте
featureType со значением whatsapp_business_app_onboarding к extras в части кода реализации встроенной регистрации метода launch и обратного // Регистрация метода запуска и функции обратного вызова { "config_id": "<CONFIGURATION_ID> ", "response_type": "code", "override_default_response_type": true, "extras": { setup: {}, "featureType": "whatsapp_business_app_onboarding", // установить значение 'whatsapp_business_app_onboarding' "sessionInfoVersion": "3" } }Чтобы убедиться, что функция включена правильно, получите доступ к вашей реализации встроенной регистрации. Если экран выбора WABA заменен экраном, предоставляющим возможность подключения существующего аккаунта WhatsApp Business, значит, функция включена.
Шаг 3: Регистрация клиентов в Surface Embedded
После подтверждения включения этой функции, предоставьте встроенную форму регистрации вашим бизнес-клиентам.
Обратите внимание, что после завершения процесса компанией и подключения клиента у вас есть 24 часа на синхронизацию истории его сообщений , в противном случае его необходимо будет отключить и повторно подключить. По этой причине мы рекомендуем вам:
Процесс подключения и синхронизации может занять несколько минут, в зависимости от ряда факторов, таких как размер истории сообщений компании, скорость интернет-соединения, скорость обработки веб-хуков и т. д.
После завершения подключения приложение WhatsApp Business автоматически обновится и сообщит компании, что ее номер теперь подключен к API:
После завершения синхронизации истории сообщений компании мы рекомендуем сообщить клиенту о завершении процесса.
Привлечение корпоративных клиентов
Когда корпоративный клиент успешно завершит встроенную процедуру регистрации, его идентификаторы активов и обмениваемый токен будут возвращены в окно, запустившее эту процедуру, как обычно, но в события сессии будет указано
событие FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING :{ data: { waba_id: "<CUSTOMER_WABA_ID> " }, тип: "WA_EMBEDDED_SIGNUP", событие: "FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING", версия: 3 }Получите идентификаторы активов клиента и коды обмениваемых токенов и используйте их для регистрации клиента, как обычно, но пропустите этап регистрации номера телефона , поскольку номер уже зарегистрирован.
После завершения этих этапов регистрации вы можете начать синхронизации истории сообщений .
Проверить статус регистрации (необязательно)
При желании вы можете проверить, зарегистрирован ли рабочий номер телефона клиента для использования как в Cloud API, так и в приложении WhatsApp Business, запросив
is_on_biz_app и platform_type в идентификаторе рабочего номера телефона:Пример запроса:
curl 'https://graph.facebook.com/v25.0/106540352242922?fields=is_on_biz_app,platform_type' \ -H 'Авторизация: Bearer EAAJB...'
Пример ответа:
Если
is_on_biz_app имеет значение true , а platform_type — CLOUD_API , то номер телефона компании может использовать Cloud API и приложение WhatsApp Business:{ "is_on_biz_app": true, "platform_type": "CLOUD_API", "id": "106540352242922" }Синхронизация данных приложения WhatsApp Business
После регистрации бизнес-клиента у вас есть 24 часа на синхронизацию его контактов и истории сообщений, в противном случае его необходимо будет удалить из системы и пройти весь процесс заново. Поэтому мы рекомендуем начинать процесс синхронизации сразу после завершения регистрации бизнес-клиента.
Напоминаем, что при регистрации компании , а также на дополнительные поля веб-хуков , иначе вы пропустите важные веб-хуки.
Шаг 1: Инициировать синхронизацию контактов
Используйте POST /
Если запрос будет успешным, будет запущен набор smb_app_state_sync , описывающих контакты WhatsApp в бизнес-приложении WhatsApp компании. Дальнейшие добавления или изменения контактов WhatsApp будут запускать соответствующий веб-хук smb_app_state_sync.
Обратите внимание, что этот шаг можно выполнить только один раз. Если потребуется повторить его, клиент должен сначала выйти из системы, а затем снова пройти процедуру регистрации в рамках встроенной системы.
Пример запроса
curl -X POST \ 'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /smb_app_data \ -H 'Авторизация:<ACCESS_TOKEN> ' \ -H 'Content-Type: application/json' \ -d ' { "messaging_product": "whatsapp", "sync_type": "smb_app_state_sync" }'Пример ответа
В случае успеха:
{ "messaging_product": "whatsapp", "request_id" : "<REQUEST_ID> " }Мы рекомендуем сохранить
request_id на случай, если вам потребуется связаться со службой поддержки.Шаг 2: Инициировать синхронизацию истории сообщений
Используйте POST /
В случае успеха будет запущен один или несколько веб-хуков истории, в зависимости от того, решила ли компания поделиться с вами своей историей переписки.
Обратите внимание, что этот шаг можно выполнить только один раз. Если потребуется повторить его, клиент должен сначала выйти из системы, а затем снова пройти процедуру регистрации в рамках встроенной системы.
История сообщений, которыми поделились
Если компания решит поделиться с вами историей своих сообщений, будет запущена серия веб-хуков, описывающих каждое сообщение, отправленное пользователям WhatsApp или полученное от них за определенный период времени.
разделе «История» вы найдете описание содержимого этих веб-хуков и того, как они организованы.
История сообщений не передается
Если компания решила не делиться с вами историей переписки, вместо этого будет запущен истории с кодом ошибки
2593109 Пример запроса
curl -X POST \ 'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /smb_app_data \ -H 'Авторизация:<ACCESS_TOKEN> ' \ -H 'Content-Type: application/json' \ -d ' { "messaging_product": "whatsapp", "sync_type": "history" }'Пример ответа
В случае успешного выполнения запроса API отправит следующий JSON-ответ. Обратите внимание, что этот ответ лишь подтверждает успешное принятие запроса и не указывает, поделилась ли компания с вами своей историей переписки.
{ "messaging_product": "whatsapp", "request_id" : "<REQUEST_ID> " }Мы рекомендуем сохранить
request_id на случай, если вам потребуется связаться со службой поддержки.Шаг 3: Отобразите новые сообщения приложения WhatsApp Business
Подключенные компании по-прежнему могут использовать приложение WhatsApp Business и поддерживаемые сопутствующие устройства для отправки и получения сообщений. Каждый раз, когда компания отправляет сообщение с помощью одного из этих приложений, запускается smb_message_echoes , который необходимо обработать и отобразить в истории переписки контактов в вашем приложении.
Отчеты об активности конверсий
Подключенные бизнес-клиенты могут запускать рекламу Click to WhatsApp, поэтому мы рекомендуем вам сообщать о сигналах покупки/генерации лидов от имени компании, используя API конверсий. См. API конверсий для обмена сообщениями с бизнес-клиентами .
Прекращение обслуживания корпоративных клиентов
Вы не можете использовать POST /
Вместо этого ваши корпоративные клиенты могут использовать приложение WhatsApp Business, чтобы отключиться от Cloud API, перейдя в Настройки > Учетная запись > Бизнес-платформа и нажав «Отключить учетную запись» . Когда корпоративный клиент отключается от Cloud API, срабатывает account_update с
PARTNER_REMOVED Ошибки
При подключении бизнес-клиента с использованием номера телефона приложения WhatsApp Business вы можете получить сообщение "Неподдерживаемый веб-перехватчик сообщений" с кодом
131060. Это ожидаемое явление, которое может возникнуть в следующих случаях:Если вы получили это сообщение через веб-перехватчик, попросите компанию проверить приложение WhatsApp Business на наличие этого сообщения.
Вебхуки
account_update
Описывает изменения, внесенные в бизнес-аккаунт WhatsApp («WABA»).
События-триггеры
синтаксис полезной нагрузки
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WABA_ID> ", "время":<WEBHOOK_TIMESTAMP> , "изменения": [ { "значение": { "номер_телефона": "<BUSINESS_PHONE_NUMBER> ", "событие": "<EVENT> ", }, "field": "account_update" } ] } ] }Пример полезной нагрузки
{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "time": 1739212624, "changes": [ { "value": { "phone_number": "15550783881", "event": "PARTNER_REMOVED", }, "field": "account_update" } ] } ] }account_offboarded
В этом документе описываются изменения в бизнес-аккаунте WhatsApp («WABA»), которые происходят при прекращении использования сервиса компанией в связи со сменой устройства или повторной регистрацией.
События-триггеры
синтаксис полезной нагрузки
{ "entry": [ { "id": "<WABA_ID> ", "время": "<WEBHOOK_TIMESTAMP> ", "changes": [ { "value": { "event": "ACCOUNT_OFFBOARDED" }, "field": "account_update" } ] } ], "object": "whatsapp_business_account" }
Пример полезной нагрузки
{ "entry": [ { "id": "862475293675413", "time": 1768477204, "changes": [ { "value": { "event": "ACCOUNT_OFFBOARDED" }, "field": "account_update" } ] } ], "object": "whatsapp_business_account" }
account_reconnected
Описывает ситуацию, когда бизнес-аккаунт WhatsApp («WABA») повторно подключается (возобновляет регистрацию) после того, как ранее был отключен.
События-триггеры
синтаксис полезной нагрузки
{ "entry": [ { "id": "<WABA_ID> ", "время": "<WEBHOOK_TIMESTAMP> ", "changes": [ { "value": { "event": "ACCOUNT_RECONNECTED" }, "field": "account_update" } ] } ], "object": "whatsapp_business_account" }Пример полезной нагрузки
{ "entry": [ { "id": "862475293675413", "time": 1768477203, "changes": [ { "value": { "event": "ACCOUNT_RECONNECTED" }, "field": "account_update" } ] } ], "object": "whatsapp_business_account" }Редактировать
Описывает события редактирования и содержимое полезной нагрузки для веб-перехватчика сообщений бизнес-аккаунта WhatsApp, предназначенного для ответов на интерактивные сообщения.
События-триггеры
синтаксис полезной нагрузки
{ "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> " }, "wa_id": "<WHATSAPP_USER_ID> " } ], "сообщения": [ { "из": "<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> " } } } } ] }, "поле": "сообщения" } ] } ] }Параметры
| Заполнитель | Описание | Пример значения |
|---|---|---|
<BUSINESS_DISPLAY_PHONE_NUMBER> | Номер телефона компании, отображаемый на экране. | 15550783881 |
<BUSINESS_PHONE_NUMBER_ID> | Идентификатор номера служебного телефона. | 106540352242922 |
<WHATSAPP_USER_PROFILE_NAME> | Имя профиля пользователя WhatsApp. | Шина Нельсон |
<WHATSAPP_USER_ID> | Идентификатор пользователя WhatsApp. | 16505551234 |
<WHATSAPP_USER_PHONE_NUMBER> | Номер телефона пользователя WhatsApp. | 16505551234 |
<WHATSAPP_MESSAGE_ID> | Идентификатор сообщения WhatsApp для события редактирования. | wamid.HBgLMTY1MDM4Nzk0MzkV... |
<WEBHOOK_TRIGGER_TIMESTAMP> | Временная метка Unix, когда был активирован веб-перехватчик. | 1739321024 |
<ORIGINAL_WHATSAPP_MESSAGE_ID> | Идентификатор исходного сообщения, которое редактируется. | wamid.HBgLMTQxMjU1NTA4MjkV... |
<CONTEXT_ID> | Идентификатор контекстного сообщения (если применимо). | М0 |
<MEDIA_ASSET_CAPTION> | Подпись к медиафайлу. | Обновлена подпись к изображению |
<MEDIA_ASSET_MIME_TYPE> | MIME-тип медиафайла. | изображение/jpeg |
<MEDIA_ASSET_SHA256_HASH> | Хэш SHA256 медиафайла. | a1b2c3d4e5f6... |
<MEDIA_ASSET_ID> | Идентификатор медиафайла. | 1234567890 |
<MEDIA_ASSET_URL> | URL медиафайла. | https://media.example.com/... |
Пример
В этом примере веб-перехватчика описывается редактирование сообщения пользователем.
{ "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" }, "wa_id": "16505551234" } ], "messages": [ { "from": "16505551234", "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=", "timestamp": "1749854575", "type": "edit", "edit": { "original_message_id": "wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA=", "message": { "context": { "id": "M0" }, "type": "image", "image": { "caption": "Обновленная подпись к изображению", "mime_type": "image/jpeg", "sha256": "a1b2c3d4e5f6...", "id": "1234567890", "url": "https://media.example.com/updated-image.jpg" } } } } ] }, "field": "messages" } ] } ] }Отменить
В данном руководстве описаны события отзыва и содержимое полезной нагрузки для веб-перехватчика сообщений бизнес-аккаунта WhatsApp, предназначенного для ответов на интерактивные сообщения.
События-триггеры
Синтаксис
{ "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> " }, "wa_id": "<WHATSAPP_USER_ID> " } ], "сообщения": [ { "из": "<WHATSAPP_USER_PHONE_NUMBER> ", "идентификатор": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "type": "revoke", "revoke": { "original_message_id": "<ORIGINAL_WHATSAPP_MESSAGE_ID> " } } ] }, "поле": "сообщения" } ] } ] }Параметры
| Заполнитель | Описание | Пример значения |
|---|---|---|
<BUSINESS_DISPLAY_PHONE_NUMBER> | Номер телефона компании, отображаемый на экране. | 15550783881 |
<BUSINESS_PHONE_NUMBER_ID> | Идентификатор номера служебного телефона. | 106540352242922 |
<WHATSAPP_USER_PROFILE_NAME> | Имя профиля пользователя WhatsApp. | Шина Нельсон |
<WHATSAPP_USER_ID> | Идентификатор пользователя WhatsApp. | 16505551234 |
<WHATSAPP_USER_PHONE_NUMBER> | Номер телефона пользователя WhatsApp. | 16505551234 |
<WHATSAPP_MESSAGE_ID> | Идентификатор сообщения WhatsApp, подтверждающего событие отзыва. | wamid.HBgLMTY1MDM4Nzk0MzkV... |
<WEBHOOK_TRIGGER_TIMESTAMP> | Временная метка Unix, когда был активирован веб-перехватчик. | 1739321024 |
<ORIGINAL_WHATSAPP_MESSAGE_ID> | Идентификатор исходного сообщения, которое отзывается (удаляется). | wamid.HBgLMTQxMjU1NTA4MjkV... |
Пример
В этом примере веб-перехватчика описывается удаление сообщения пользователем.
{ "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" }, "wa_id": "16505551234" } ], "messages": [ { "from": "16505551234", "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=", "timestamp": "1749854575", "type": "revoke", "revoke": { "original_message_id": "wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA=" } } ] }, "field": "messages" } ] } ] }История
В данном документе описывается история чатов в приложении WhatsApp Business компании, которая решила поделиться своей историей чатов с поставщиком решений , или же компания приняла решение отказаться от обмена историей чатов.
События-триггеры
Содержимое истории чата
Если компания уже одобрила обмен историей чатов, когда поставщик решения запрашивает историю чатов компании, будет запущена серия веб-хуков истории, описывающих все сообщения, отправленные или полученные в течение 180 дней с момента подключения компании к Cloud API.
Обратите внимание, что в целях повышения эффективности один веб-хук может содержать тысячи сообщений, поэтому мы рекомендуем сначала получить его содержимое, а затем обработать его асинхронно.
Фазы и блоки
Веб-хуки делятся на три этапа истории, где нулевой день обозначает момент подключения компании к Cloud API:
На каждом этапе веб-хуки истории чата могут отправляться отдельными блоками, в зависимости от общего количества сообщений, составляющих цепочку.
chunk_order для упорядочивания этих фрагментов в последовательном порядке, поскольку они могут доставляться не последовательно. фазы можно использовать для отслеживания хода выполнения фазы. Значение 2 указывает на то, что текущая фаза завершена. можно использовать progress . Значение 100 означает, что синхронизация завершена.Если для данного этапа отсутствует история чата, соответствующие веб-хуки отправляться не будут.
Синтаксис полезной нагрузки — разрешен обмен историей чата
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WABA_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "история": [ { "метаданные": { "фаза":<PHASE> , "chunk_order":<CHUNK_ORDER> , "прогресс":<PROGRESS> }, "threads": [ /* Первый объект истории чата */ { "id": "<WHATSAPP_USER_PHONE_NUMBER> ", "messages": [ /* Первый объект сообщения в потоке */ { "from": "<BUSINESS_OR_WHATSAPP_USER_PHONE_NUMBER> ", "к": "<WHATSAPP_USER_PHONE_NUMBER> ", // включается только если сообщение SMB echo "id": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<DEVICE_TIMESTAMP> , "тип": "<MESSAGE_TYPE> ", "<MESSAGE_TYPE> ": {<MESSAGE_CONTENTS> }, "history_context": { "status": "<MESSAGE_STATUS> " } }, /* Дополнительные объекты сообщений в ветке будут добавлены, если таковые имеются */ ] }, /* Дополнительные объекты истории чата будут добавлены, если таковые имеются */ ] } ] }, "поле": "история" } ] } ] }Содержимое полезной нагрузки — разрешено делиться историей чата
| Заполнитель | Описание | Пример значения |
|---|---|---|
<WABA_ID>Нить | Идентификатор бизнес-аккаунта WhatsApp клиента. | 102290129340398 |
<BUSINESS_PHONE_NUMBER>Нить | Рабочий телефонный номер корпоративного клиента. | 15550783881 |
<BUSINESS_PHONE_NUMBER_ID>Нить | Идентификатор номера корпоративного телефона клиента. | 106540352242922 |
<PHASE>Целое число | фазу истории . Возможные значения: 0 — указывает, что сообщения относятся к периоду с 0-го дня (время адаптации нового сотрудника) по 1-й день1 — указывает, что сообщения относятся к периоду с 1-го по 90-й день2 — указывает, что сообщения относятся к периоду с 90-го по 180-й день | 1 |
<CHUNK_ORDER>Целое число | Указывает блока , который можно использовать для упорядочивания наборов веб-хуков в последовательном порядке. | 1 |
<PROGRESS>Целое число | Отображает процент от общего прогресса синхронизации. Минимум 0 , максимум 100 . | 55 |
<WHATSAPP_USER_PHONE_NUMBER>Нить | Номер телефона пользователя WhatsApp. | 16505551234 |
<BUSINESS_OR_WHATSAPP_USER_PHONE_NUMBER>Нить | Номер телефона корпоративного клиента или номер телефона пользователя WhatsApp. Если значением является номер телефона компании, объект сообщения описывает сообщение, отправленное компанией пользователю WhatsApp. Если значением является номер телефона пользователя WhatsApp, то объект сообщения описывает сообщение, отправленное пользователем WhatsApp компании. | 15550783881 |
<WHATSAPP_USER_PHONE_NUMBER>Нить | Номер телефона пользователя WhatsApp. Свойство `to` включается только в том случае, если объект сообщения представляет собой эхо-сообщение SMB . | 16505551234 |
<WHATSAPP_MESSAGE_ID>Нить | Идентификатор сообщения WhatsApp. | wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA |
<DEVICE_TIMESTAMP>Нить | Метка времени Unix, указывающая, когда сообщение было получено устройством получателя. | 1738796547 |
<MESSAGE_TYPE>Нить | Тип сообщения . Обратите внимание, что этот заполнитель встречается в приведенном выше синтаксисе дважды, поскольку он служит заполнителем для значения свойства типа пример полезной нагрузки ниже для потока с различными типами сообщений.Если это значение установлено на media_placeholder , объект сообщения описывает сообщение, содержащее медиафайл. В этом случае содержимое сообщения будет опущено. Вместо этого будет отправлен отдельный веб-перехватчик истории, описывающий содержимое сообщения и идентификатор медиафайла, но только если сообщение было отправлено в течение последних двух недель после вашего запроса. См. пример полезной нагрузки ниже , описывающий содержимое медиасообщения. | текст |
<MESSAGE_CONTENTS>Объект | Объект, описывающий содержимое сообщения. Это значение будет меняться в зависимости от типа сообщения, а также от его содержимого. Например, если компания отправляет с изображением без подписи, объект не будет содержать caption . содержимого сообщений каждого типа см. | {"body":"Вот запрошенная вами информация! https://www.meta.com/quest/quest-3/"} |
<MESSAGE_STATUS>Нить | Отображает последние статистические данные о доставке сообщения. Возможные значения: ДОСТАВЛЕННЫЙОШИБКАВ ОЖИДАНИИИГРАЛЧИТАТЬОТПРАВИЛ | ЧИТАТЬ |
Пример полезной нагрузки — разрешен обмен историей чата
Пример содержимого двух цепочек сообщений: (1) цепочка, содержащая текстовое и видеосообщение, отправленное пользователю WhatsApp, и ответ пользователя WhatsApp, и (2) текстовое сообщение, отправленное пользователю WhatsApp с благодарностью за заказ.
Обратите внимание, что содержимое медиасообщения в первом потоке не описывается. Вместо этого запускается второй веб-перехватчик, описывающий содержимое медиасообщения.
{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "history": [ { "metadata": { "phase": 0, "chunk_order": 1, "progress": 55 }, "threads": [ { "id": "16505551234", "messages": [ { "from": "15550783881", "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA", "timestamp": "1739230955", "type": "text", "text": { "body": "Вот запрошенная вами информация! https://www.meta.com/quest/quest-3/" }, "history_context": { "status": "ПРОЧИТАНО" } }, { "from": "15550783881", "id": "wamid.QyNUEHBgLMTY0NjcwNDM1OTUVAgARGBI1Rj3NEYxMzAzMzQ5MkEA", "timestamp": "1739230970", "type": "media_placeholder", "history_context": { "status": "ВОСПРОИЗВЕДЕНО" } }, { "from": "16505551234", "id": "wamid.N0FCNjMAHBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0", "timestamp": "1739230970", "type": "text", "text": { "body": "Спасибо!" }, "history_context": { "status": "READ" } } ] }, { "id": "12125557890", "messages": [ { "from": "15550783881", "id": "wamid.BIyNDlBOEI5N0FCNjMAHBgLMTY0NjcwNDM1OTUVAgARGQUQ4NDc0", "timestamp": "1739230970", "type": "text", "text": { "body": "Спасибо за ваш заказ! В знак благодарности используйте код THANKS30, чтобы получить скидку 30% на следующий заказ." }, "history_context": { "status": "DELIVERED" } } ] } ] } ] }, "field": "history" } ] } ] }Пример полезной нагрузки для медиа-сообщения
{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "messages": [ { "from": "16505551234", "id": "wamid.QyNUEHBgLMTY0NjcwNDM1OTUVAgARGBI1Rj3NEYxMzAzMzQ5MkEA", "timestamp": "1738796547", "type": "image", "image": { "caption": "Black Prince echeveria", "mime_type": "image/jpeg", "sha256": "3f9d94d399fa61c191bc1d4ca71375a035cd9b9f5b1128e1f0963a415c16b0cc", "id": "24230790383178626" } } ] }, "field": "history" } ] } ] }Синтаксис полезной нагрузки — обмен историей чата отклонен
{ "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "история": [ { "ошибки": [ { "код": 2593109, "заголовок": "Синхронизация истории отключена компанией в приложении WhatsApp Business", "сообщение": "Синхронизация истории отключена компанией в приложении WhatsApp Business", "данные_ошибки": { "подробности": "Обмен историей отключен компанией" } } ] } ] }Пример полезной нагрузки — отклонена отправка истории чата
{ "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "history": [ { "errors": [ { "code": 2593109, "title": "Синхронизация истории отключена компанией в приложении WhatsApp Business", "message": "Синхронизация истории отключена компанией в приложении WhatsApp Business", "error_data": { "details": "Обмен историей отключен компанией" } } ] } ] }smb_app_state_sync
Описывает один или несколько контактов WhatsApp в приложении WhatsApp Business, используемом корпоративными клиентами.
События-триггеры:
синтаксис полезной нагрузки
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WABA_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_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> " }, "действие": "<ACTION> ", "метаданные": { "временная метка": "<WEBHOOK_TIMESTAMP> " } }, * Дополнительные контакты будут добавлены позже, если таковые имеются */ ] }, "field": "smb_app_state_sync" } ] } ] }Содержимое полезной нагрузки
| Заполнитель | Описание | Пример значения |
|---|---|---|
| Идентификатор бизнес-аккаунта WhatsApp клиента. | 102290129340398 |
| Рабочий телефонный номер корпоративного клиента. | 15550783881 |
| Идентификатор номера корпоративного телефона клиента. | 106540352242922 |
| Полное имя контакта, как оно отображается в телефонной адресной книге бизнес-клиента в приложении WhatsApp Business. Не включается в случае удаления контакта из телефонной адресной книги приложения WhatsApp Business корпоративными клиентами. | Пабло Моралес |
| Имя контакта, как оно отображается в телефонной адресной книге бизнес-клиента в приложении WhatsApp Business. Не включается в случае удаления контакта из телефонной адресной книги приложения WhatsApp Business корпоративными клиентами. | Пабло |
| Номер телефона контакта в WhatsApp. | 16505551234 |
| Указывает, добавил ли, отредактировал или удалил ли бизнес-клиент контакт из адресной книги своего телефона в приложении WhatsApp Business. Возможные значения: добавить — компания добавила или отредактировала контактудалить — компания удалила контакт | добавлять |
| Временная метка Unix указывает, когда контакт был добавлен, отредактирован или удален. | 1738346006 |
smb_message_echoes
Описывает сообщение, отправленное корпоративным клиентом пользователю WhatsApp, использующему приложение WhatsApp Business или поддерживаемое сопутствующее устройство .
События-триггеры
синтаксис полезной нагрузки
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WABA_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "message_echoes": [ { "from": "<BUSINESS_PHONE_NUMBER> ", "к": "<WHATSAPP_USER_PHONE_NUMBER> ", "идентификатор": "<WHATSAPP_MESSAGE_ID> ", "временная метка": "<WEBHOOK_TIMESTAMP> ", "тип": "<MESSAGE_TYPE> ", "<MESSAGE_TYPE> ": {<MESSAGE_CONTENTS> } } ] }, "field": "smb_message_echoes" } ] } ] }Содержимое полезной нагрузки
| Заполнитель | Описание | Пример значения |
|---|---|---|
<WABA_ID>Нить | Идентификатор бизнес-аккаунта WhatsApp клиента. | 102290129340398 |
<BUSINESS_PHONE_NUMBER>Нить | Рабочий телефонный номер корпоративного клиента. | 15550783881 |
<BUSINESS_PHONE_NUMBER_ID>Нить | Идентификатор номера корпоративного телефона клиента. | 106540352242922 |
<WHATSAPP_USER_PHONE_NUMBER>Нить | Номер телефона пользователя WhatsApp. | 16505551234 |
<WHATSAPP_MESSAGE_ID>Нить | Идентификатор сообщения WhatsApp. | wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA |
<WEBHOOK_TIMESTAMP>Нить | Временная метка Unix указывает момент срабатывания веб-перехватчика. | 1738796547 |
<MESSAGE_TYPE>Нить | Тип сообщения . Обратите внимание, что этот заполнитель встречается в приведенном выше синтаксисе дважды, поскольку он служит заполнителем для значения свойства типа | текст |
<MESSAGE_CONTENTS>Объект | Объект, описывающий содержимое сообщения. Это значение будет меняться в зависимости от типа , а также от его содержимого.Например, если компания отправляет с изображением без подписи, объект не будет содержать caption . содержимого сообщений каждого типа см. | {"body":"Вот запрошенная вами информация! https://www.meta.com/quest/quest-3/"} |
Пример полезной нагрузки
В этом примере описывается текстовое сообщение (
тип — текст ), отправленное пользователю WhatsApp корпоративным клиентом, использующим приложение WhatsApp Business.{ "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "message_echoes": [ { "from": "15550783881", "to": "16505551234", "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA", "timestamp": "1700255121", "type": "text" "text": { "body": "Вот информация" Вы запросили! https://www.meta.com/quest/quest-3/" } } ] }, "field": "smb_message_echoes" } ] } ] }Нужна помощь?
Для регистрации в выберите:
проблем с API сосуществования выберите: