Платформа WhatsApp Business > Облачный API > Руководства

Перенос с локального API в облачный

В этом документе рассказывается, как перенести номера телефонов компаний с локального API в облачный.

Примечание. Перенос номера телефона компании с одного API в другой и перенос номера из одного аккаунта WhatsApp Business в другой — это разные процессы.

Информацию о переносе с облачного API на локальный см. в этом разделе.

Принцип работы

Процесс переноса подразумевает генерацию метаданных о номере телефона компании и использование этих данных для регистрации номера для использования облачного API. При этом регистрация номера телефона для использования с локальным API отменяется, поскольку одновременно номер может быть зарегистрирован только для использования с одним API.

Перенос НЕ влияет на следующее:

отображаемое имя, статус проверки и показатель качества номера телефона компании;
используемые этим номером телефона шаблоны и их статусы;
владение аккаунтом WhatsApp Business, его статус официального бизнес-аккаунта и ограничение на количество сообщений.

Для поддержки переноса вам следует знать о различиях между API и выполнить соответствующие действия до начала процесса переноса, описанного в этом документе.

Требования

Приложение Meta

У вас должно быть приложение Meta для бизнеса, которое может использовать облачный API и Business Management API для работы с данными подключенного клиента, а также Webhooks облачного API и Business Management API. Кроме того, приложение должно быть связано с подтвержденным бизнес-аккаунтом Meta либо такой аккаунт должен заявить свои права на него.

Если у вас нет приложения Meta для бизнеса или в нем не настроен продукт WhatsApp, выполните действия из нашего руководства по началу работы с облачным API. При этом будут сгенерированы все объекты, необходимые для тестирования облачного API и Business Management API.

Проверка приложения

Ваше приложение Meta должно пройти проверку и быть одобрено (т. е. иметь расширенный доступ) для использования разрешений whatsapp_business_messaging и whatsapp_business_management.

Различия между API

Следующие функции локального API либо не поддерживаются в облачном API, либо реализованы иначе. До начала переноса убедитесь, что ваше приложение может обработать все эти различия.

Webhooks

Структуры полезных данных Webhooks облачного API и Business Management API отличаются от структур данных локального API. Рекомендуем создать новую конечную точку Webhooks, которая может обрабатывать исключительно облачный API и Business Management API.

Информацию о различиях в полезной нагрузке и о том, как настроить Webhooks в приложении с использованием панели приложений, см. в следующих документах:

настройка: Webhooks для WhatsApp;
полезная нагрузка Webhooks облачного API — Полезная нагрузка уведомлений Webhooks;
полезная нагрузка Webhooks Business Management API: Настройка Webhooks.

Примечание. После переноса номера телефона компании в облачный API необходимо воспользоваться конечной точкой Аккаунт WhatsApp Business > Подписанные приложения и подписать ваше приложение Meta на Webhooks аккаунта WhatsApp Business, связанного с этим номером телефона.

Синтаксис запроса

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

После завершения переноса в облачный API Webhooks локального API перестанут доставляться. Вместо этого начнут доставляться Webhooks облачного API.

Медиафайлы

ID медиафайлов, загруженных в локальный API, нельзя использовать для отправки сообщений через облачный API, поэтому вам необходимо заново загрузить медиафайлы с использованием облачного API, чтобы сгенерировать новые ID, или использовать URL медиафайлов, если они размещены на общедоступном сервере. См. разделы Сообщения с медиафайлами и Шаблоны сообщений с медиафайлами.

Примечание. Чтобы обеспечить целостность сообщений, некоторые домены для размещения медиафайлов, допустимые в локальном API, запрещены в облачном. Если вы пользуетесь услугами хостинга для своих медиафайлов, рекомендуем до переноса проверить URL медиафайлов в сообщениях в свободной форме и сообщениях с шаблонами. Если вы думаете, что ваш хост блокируется по ошибке, обратитесь в поддержку.

Коды ошибок

Коды ошибок облачного API и Business Management API отличаются от кодов ошибок локального API. См. следующие документы:

Проверка свойств

Локальный API допускает неизвестные свойства в полезных данных тела публикации сообщения, однако облачный API отклоняет такие запросы, поэтому в ваших запросах на отправку сообщений должны использоваться только поддерживаемые свойства.
Локальный API допускает отсутствие индексов кнопок при отправке сообщений с одной кнопкой, однако облачный API будет отклонять такие запросы, поэтому в ваших запросах на отправку сообщений с кнопками должны использоваться индексы и их значения.
Локальный API допускает текстовые строки, которые начинаются или заканчиваются пробелами (или состоят только из пробелов) в свойствах объектов действий и кнопок при отправке интерактивных сообщений, однако облачный API будет отклонять такие запросы.

Сообщения Push-To-Talk

Локальный API идентифицирует сообщения Push-To-Talk (PTT) в Webhooks, устанавливая для параметра messages.type значение voice, а облачный API — устанавливая для параметра messages.audio.voice значение true.

Наборы стикеров

Облачный API не поддерживает наборы стикеров.

Время простоя

Время простоя начинается, как только вы выполните последний шаг переноса (регистрацию номера для использования с облачным API). Оно составит несколько секунд. Сообщения, отправленные на номер телефона пользователями WhatsApp в это время, будут отклоняться без уведомления.

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

Пропускная способность

Если номер телефона компании в локальном API использует два и более сегмента, ему будет автоматически назначена высокая пропускная способность в облачном API.

Официальные бизнес-аккаунты

Если вы переносите номер телефона компании, которая имеет официальный бизнес-аккаунт (OBA) , статус аккаунта сохранится, если вы добавите метаданные (сгенерированные на шаге 2) при регистрации номера телефона (шаг 3). Если вы пропустите эти данные, номер потеряет статус официального.

Поддержка в процессе перехода

Если у вас возникнут вопросы о переносе или понадобится помощь с ним, отправьте заявку в прямую поддержку и укажите:

тему WABiz: облачный API;
тип запроса Локальный API -> Проблемы с переходом на облачный API.

Шаг 1. Отключение двухшаговой проверки

Если вы знаете PIN номера телефона компании, этот шаг можно пропустить.

PIN номера телефона понадобится на шаге 3. Если у вас нет PIN, сначала отключите двухшаговую проверку для номера телефона компании. Если номером телефона владеете не вы, попросите владельца отключить эту проверку.

Шаг 2. Генерация метаданных для номера телефона

Чтобы сгенерировать метаданные о номере телефона компании, воспользуйтесь Backup and Restore API.

Синтаксис запроса

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

<PASSWORD> — произвольная строка. Это значение будет использоваться для кодирования метаданных, поэтому запишите его. Оно понадобится на следующем шаге.

Ответ

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

API вернет закодированную строку, описывающую ваш номер телефона компании и его настройки, в свойстве data. Сохраните это значение. Оно понадобится на следующем шаге.

<METADATA> — это закодированная строка, описывающая номер телефона компании и его настройки. Сохраните это значение. Оно понадобится на следующем шаге.
<API_STATUS> — статус развертывания локального API.
<API_VERSION> — номер версии используемого у вас локального API.

Пример запроса

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

Пример ответа

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

Шаг 3. Регистрация номера

Одноразовый пароль (OTP) не требуется, если метаданные резервного копирования из шага 2 выше на шаге 3 (этом шаге) правильно и без изменений передаются в облачный API.

Чтобы зарегистрировать номер в облачном API, используйте конечную точку Номер телефона WhatsApp Business > Зарегистрировать этого API.

Добавьте закодированные метаданные номера телефона компании и пароль с предыдущего шага. Номер телефона можно зарегистрировать и без этих данных, однако в этом случае данные профиля номера телефона будут утеряны, что повлияет на статус аккаунта WhatsApp Business как официального.

Синтаксис запроса

POST /<BUSINESS_PHONE_NUMBER_ID>/register

Тело публикации

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}

<NEW_OR_EXISTING_PIN> — существующий PIN или PIN, который вы хотите установить для номера телефона компании.
<PASSWORD> — пароль, который вы использовали для генерации метаданных номера телефона на предыдущем шаге.
<METADATA> — закодированная строка, которая описывает ваш номер телефона и его настройки, сгенерированная на предыдущем шаге.

Ответ

{
  "success": <SUCCESS>
}

В случае успешной регистрации параметр success в ответе API будет иметь значение true, а в случае ошибки — false.

Пример запроса

curl 'https://graph.facebook.com/v21.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

Пример ответа

{
  "success": true
}

Шаг 4. Проверка работоспособности обмена сообщениями (необязательно)

Запросите поле health_status для номера телефона компании и убедитесь, что его можно использовать для отправки сообщений через облачный API. См. статью Работоспособность обмена сообщениями.

Платформа WhatsApp Business | Облачный API | API Business Management

Перенос с локального API в облачный

Принцип работы

Требования

Приложение Meta

Проверка приложения

Рекомендации

Различия между API

Webhooks

Синтаксис запроса

Медиафайлы

Коды ошибок

Проверка свойств

Сообщения Push-To-Talk

Наборы стикеров

Время простоя

Пропускная способность

Официальные бизнес-аккаунты

Поддержка в процессе перехода

Шаг 1. Отключение двухшаговой проверки

Шаг 2. Генерация метаданных для номера телефона

Синтаксис запроса

Ответ

Пример запроса

Пример ответа

Шаг 3. Регистрация номера

Синтаксис запроса

Тело публикации

Ответ

Пример запроса

Пример ответа

Шаг 4. Проверка работоспособности обмена сообщениями (необязательно)