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

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

Убедитесь, что:
  • В вашем аккаунте используется платный тарифный план YCloud. Пользовательские приложения недоступны на бесплатном плане Free.
  • Ваша роль имеет доступ к разделу Developers > Custom apps в панели управления YCloud.
  • Телефонные номера WhatsApp Business, необходимые приложению, уже добавлены в ваш аккаунт YCloud.
  • Вы знаете, какие разрешения API требуются интеграции.
  • У вас есть общедоступная конечная точка HTTPS, если приложению требуются события Webhook.
Храните API-ключ приложения и секрет подписи Webhook в менеджере секретов. Никогда не размещайте их в клиентском коде, логах, на скриншотах или в системе контроля версий.

Создание приложения

  1. Войдите в панель управления YCloud.
  2. Перейдите в Developers > Custom apps.
  3. Нажмите Create app.
Страница Custom apps в панели управления YCloud с кнопкой Create app.
  1. Введите App name. Название может содержать до 64 символов.
  2. Необязательно: введите Description длиной до 512 символов, чтобы ваша команда понимала назначение приложения.
  3. Нажмите Create.
Диалоговое окно создания приложения с полями App name и Description.

Enter an app name and, optionally, a description before selecting Create.

YCloud присваивает приложению идентификатор app ID только для чтения. Новое приложение отключено, пока вы явно не включите его. Настройте его ресурсы, доступ к API и события Webhook перед включением.

Назначение телефонных номеров WhatsApp

Назначайте только те телефонные номера, к которым интеграции необходим доступ.
  1. Откройте приложение и выберите Assets.
  2. Нажмите Add phone numbers.
Раздел Assets пользовательского приложения с кнопкой Add phone numbers.
  1. Найдите номер по названию Business Manager, WABA ID, имени WABA или номеру телефона.
  2. Выберите один или несколько телефонных номеров WhatsApp Business.
  3. Нажмите Confirm.
В окне выбора также отображаются статус привязки каждого номера и рейтинг качества, если эта информация доступна.
Диалоговое окно Add phone numbers с доступными телефонными номерами WhatsApp Business, статусом привязки и рейтингом качества.
Выбранные номера теперь отображаются в списке ресурсов приложения.

Настройка API-ключа и разрешений

YCloud отображает API-ключ приложения в разделе API key & permissions. Ключи пользовательских приложений начинаются с yc_ak_. Скопируйте ключ, чтобы сохранить его в безопасном месте, а затем добавьте только те разрешения, которые требуются интеграции.
Раздел API key and permissions для пользовательского приложения.
  1. Выберите API key & permissions.
  2. В подразделе API permissions нажмите Add permissions.
  3. Отфильтруйте по категории или выполните поиск по названию разрешения или области действия (scope).
  4. Выберите каждое необходимое разрешение. Например, разрешения для контактов разделены на области чтения, создания или обновления, а также удаления.
  5. Нажмите Confirm.
Диалоговое окно Edit permissions с областями действия разрешений для контактов.
Передавайте сгенерированный ключ в заголовке X-API-Key и используйте его только из доверенного серверного кода. YCloud проверяет, активно ли приложение и соответствует ли запрос одному из выбранных им разрешений API. Когда API работает с ресурсом WhatsApp, YCloud также проверяет, есть ли у приложения доступ к соответствующему номеру телефона или WABA. Не все API YCloud доступны для пользовательских приложений. Запрос к API, отсутствующему в списке выбора разрешений, будет отклонен при использовании ключа пользовательского приложения. Ключи пользовательских приложений также нельзя сочетать с заголовком X-Managed-Account-ID. Рекомендации по заголовкам запросов и работе с учетными данными см. в разделе Authentication.
В разделе API-ключа есть возможность сгенерировать новый ключ взамен текущего. В зависимости от выбранного при перегенерации варианта предыдущий ключ либо отзывается немедленно, либо остается доступным в течение переходного периода длительностью один час. Обновите все сервисы, использующие этот ключ, до окончания переходного периода.

Настройка вебхуков

Настройте отдельную точку назначения для событий, необходимых этому приложению. Вебхуки приложения функционируют отдельно от конечных точек Webhook, настроенных в разделе Developers > Webhooks.
  1. Выберите Webhook.
  2. Введите вашу публичную конечную точку HTTPS в поле Endpoint URL и сохраните ее.
  3. Сохраните сгенерированный секрет Signing secret в безопасном месте.
  4. В подразделе Added events нажмите Add events.
Раздел Webhook с параметрами Endpoint URL, Signing secret и Added events.
  1. Отфильтруйте по категории или выполните поиск по названию или типу события.
  2. Выберите события, которые должна получать ваша конечная точка.
  3. Если для события предусмотрены параметры области данных (data-scope), выберите вариант, соответствующий вашей интеграции.
  4. Нажмите Confirm.
Диалоговое окно Add webhook events с доступными событиями контактов.
YCloud доставляет только выбранные события на эндпоинт активного приложения. События WhatsApp фильтруются по назначенным приложению телефонным номерам или их родительским WABA. Настройки области данных конкретных событий позволяют дополнительно ограничить доставку только теми данными, которые привязаны к приложению. События контактов и отписок относятся к уровню арендатора (tenant), поскольку они не связаны с активом WhatsApp. Ваш эндпоинт должен проверять подпись YCloud перед обработкой запроса и оперативно возвращать успешный ответ со статусом 2xx. О проверке подписи, обработке доставки и рекомендациях по безопасности см. в разделе Configure webhooks. Схемы событий приведены в разделе Webhook event payloads.

Включение и проверка приложения

Перед использованием приложения в рабочей среде:
  1. Убедитесь, что приложение содержит ожидаемые телефонные номера WhatsApp Business.
  2. Проверьте каждое разрешение API и отзовите доступ, который не требуется интеграции.
  3. Вернитесь в раздел Developers > Custom apps и включите приложение в меню действий.
Список пользовательских приложений с действием Enable для неактивного приложения.
  1. Убедитесь, что приложение находится в статусе Active.
  2. Отправьте тестовый запрос с ключом API приложения из безопасной серверной среды.
  3. Инициируйте выбранное событие и убедитесь, что ваш эндпоинт успешно проверяет и обрабатывает его.
Только активные приложения могут аутентифицировать запросы API или получать события Webhook. Существующее приложение можно найти по его названию или идентификатору приложения. Откройте Edit , чтобы просмотреть или изменить его конфигурацию.