Skip to main content
Пользовательские приложения позволяют предоставить интеграции доступ к выбранным телефонным номерам 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.
Страница пользовательских приложений в панели управления 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 присваивает приложению неизменяемый идентификатор приложения. Новое приложение отключено, пока вы явно не включите его. Настройте его ресурсы, доступ к API и события Webhook перед включением.

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

Назначайте только те телефонные номера, к которым интеграции нужен доступ.
  1. Откройте приложение и выберите Assets.
  2. Нажмите Add phone numbers.
Раздел Assets пользовательского приложения с кнопкой Add phone numbers.
  1. Найдите номер по названию Business Manager, идентификатору WABA, названию 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

Настройте отдельный адрес назначения для событий, необходимых этому приложению. Webhook приложений отделены от эндпоинтов 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.
Диалоговое окно добавления событий Webhook с доступными событиями контактов.
YCloud доставляет только выбранные события на активный эндпоинт приложения. События WhatsApp фильтруются по назначенным приложению телефонным номерам или их родительским WABA. Настройки области данных для конкретных событий могут дополнительно ограничивать доставку данными, относящимися к этому приложению. События контактов и отписок относятся к уровню арендатора (tenant-level), поскольку они не связаны с ресурсами WhatsApp. Ваш эндпоинт должен проверять подпись YCloud перед обработкой запроса и своевременно возвращать успешный ответ 2xx. См. раздел Настройка вебхуков для получения инструкций по валидации подписи, обработке доставки и безопасности. См. раздел Полезная нагрузка событий вебхуков для ознакомления со схемами событий.

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

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