Начало работы: информация для партнеров по решениям

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

1. Подготовка и планирование.
2. Настройка ресурсов.
3. Подписание контрактов.
4. Создание интеграции.

По завершении рекомендуем следить за ежемесячными обновлениями.

Подготовка и планирование

Ознакомьтесь с документацией

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

Запланируйте подключение и перенос

Вы должны использовать регистрацию на сайте поставщика, чтобы подключить новых клиентов к облачному API. Если вы ещё этого не сделали, интегрируйте и активируйте регистрацию на сайте поставщика. Регистрация на сайте поставщика — это самый быстрый и простой способ зарегистрировать клиентов, который позволит им начать отправку сообщений менее чем через 5 минут.

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

Решив, кого именно необходимо перенести, вы можете разработать план и график переноса клиентов.

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

Запланируйте общение с клиентами

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

Подумайте о расценках

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

Настройка объектов

Чтобы использовать облачный API, партнерам по решениям необходимо иметь следующие объекты:

Подписание контрактов

Принятие Пользовательского соглашения

Для доступа к облачному API для обмена сообщениями в WhatsApp Business вам необходимо сначала принять условия Пользовательского соглашения для платформы WhatsApp Business от имени вашей компании.

Чтобы сделать это, откройте WhatsApp Manager и примите условия пользовательского соглашения на информационном баннере.

Если вы являетесь действующим партнером по бета-тестированию, использующим облачный API, вам предоставляется 90-дневный льготный период. Это означает, что вам необходимо принять условия соглашения до 5 июля 2022 года, иначе доступ для вас будет закрыт.

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

Создание интеграции

Шаг 1. Получите маркер доступа системного пользователя

Вызовы API Graph используют маркеры доступа для аутентификации. Подробную информацию см. в разделе Маркеры доступа. Чтобы создать маркер, рекомендуем вам задействовать своего системного пользователя.

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

1. Перейдите в раздел Business Manager > Настройки компании > Пользователи > Системные пользователи, чтобы просмотреть созданного вами системного пользователя.
2. Щелкните этого пользователя и выберите Добавить объекты. После этого откроется новое окно.
3. В разделе Выбрать тип объекта на панели слева выберите Приложения. В разделе Выбрать объекты выберите приложение Meta, которое хотите использовать (у вашего разрешения должны быть соответствующие разрешения). Активируйте Разработать приложение для этого приложения.
4. Выберите Сохранить изменения, чтобы сохранить настройки и вернуться на главный экран системного пользователя.
5. Теперь всё готово к созданию вашего маркера доступа. На главном экране системного пользователя нажмите Сгенерировать маркер и выберите свое приложение Meta. После выбора приложения отобразится список доступных разрешений. Выберите whatsapp_business_management и whatsapp_business_messaging. Нажмите Сгенерировать маркер.
6. Откроется новое окно с указанием вашего системного пользователя, назначенного приложения и маркера доступа. Сохраните свой маркер.
7. Дополнительно вы можете выбрать маркер и отобразить отладчик маркеров доступа. В отладчике вы должны увидеть два выбранные вами разрешения. Вы также можете скопировать и вставить свой маркер напрямую в отладчик маркеров доступа.

Шаг 2. Настройте Webhooks

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

Чтобы настроить Webhook, вам необходимо создать подключенный к Интернету веб-сервер, URL которого отвечает требованиям компании Meta и приложения WhatsApp. См. раздел Создание конечной точки, чтобы узнать, как это сделать. Если для тестирования вам понадобится конечная точка, вы можете создать тестовую конечную точку Webhooks.

Настройка приложения

Когда конечная точка будет готова, настройте ее для использования вашим приложением Meta.

Webhooks необходимо настраивать только один раз для каждого имеющегося у вас приложения. Вы можете использовать один и тот же объект Webhooks для получения нескольких типов событий из нескольких аккаунтов WhatsApp Business. Подробнее см. в разделе с информацией о Webhooks.

Шаг 3. Подпишитесь на свой аккаунт WhatsApp Business

Чтобы получать уведомления для соответствующего аккаунта, оформите подписку для своего приложения.

curl -X POST \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Если вы получаете показанный ниже ответ, все события Webhooks для номеров телефонов в этом аккаунте будут отправляться на указанную вами конечную точку Webhooks.

{
  "success": true
}

Шаг 4. Получите ID номера телефона

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

Перед регистрацией необходимо узнать ID этого номера. Чтобы получить ID своего номера телефона, выполните следующий вызов API:

curl -X GET \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Если этот вызов выполнен успешно, он включает в себя все номера телефонов, связанных с вашим аккаунтом WhatsApp Business:

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"
    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

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

Исключения при переводе номера

Шаг 5. Зарегистрируйте номер телефона

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

1. Зарегистрируйте телефон.
2. Включите двухшаговую проверку, установив 6-значный код регистрации — вы должны настроить этот код на своей стороне. Сохраните и запомните этот код: он может понадобиться позже.

Настройка двухфакторной аутентификации — обязательное требование для использования облачного API. Если его не выполнить, при подключении вы получите сообщение об ошибке:

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

curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp","pin": "6_DIGIT_PIN"}'

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

{
  "success": true
}

Пользователи с регистрацией на сайте поставщика

Шаг 6. Получите сообщение из приложения потребителя

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

Из личного приложения WhatsApp для iOS или Android отправьте сообщение на номер телефона, который вы только что зарегистрировали. После отправки сообщения вы должны получить входящее сообщение к вашему объекту Webhooks с уведомлением в следующем формате.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315551234",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16315555555"
              }
            ],
            "messages": [
              {
                "from": "16315555555",
                "id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXmuSf",
                "timestamp": "1602139392",
                "text": {
                  "body": "Hello!"
                },
                "type": "text"
                }
            ]
          },
        "field": "messages"
        }
      ]
    }
  ]
}

Шаг 7. Отправьте тестовое сообщение

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

curl -X  POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp", "to": "16315555555","text": {"body" : "hello world!"}}'

В случае успеха этого вызова вы получите ответ с ID сообщения. Используйте ID для отслеживания прогресса своих сообщений через Webhooks. Максимальная длина ID: 128 символов.

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

{
  "id":"wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}

Следите за ежемесячными обновлениями

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

Часто задаваемые вопросы

Общие часто задаваемые вопросы

Часто задаваемые вопросы о технической реализации

What is the architecture of the Cloud API?

The Cloud API architecture significantly simplifies the Solution Partner's operational and infrastructure requirements to integrate with WhatsApp Business Platform. First, it removes the infrastructure requirements to run Business API docker containers (CAPEX savings). Second, it obviates the need of operational responsibilities to manage the deployment (OPEX savings). For details, refer to the architecture diagram comparing the On-Premises and Cloud API deployments.

Постоянная ссылка

Часто задаваемые вопросы о конфиденциальности и безопасности данных

Часто задаваемые вопросы о соблюдении нормативных требований