Настройка Zoom

к сведению

Dispatch поставляется с поддержкой конференций Zoom. Плагин Zoom создаёт конференцию длительностью до 24 часов (максимум, который допускает Zoom) и генерирует пароль для её защиты. Ссылка, которую плагин возвращает в мессенджер, устроена так, что достаточно по ней перейти — вводить пароль не нужно.

Обновление со старой версии Dispatch

Раньше этот плагин проходил аутентификацию через JWT-приложение Zoom — такой способ Zoom отключил 01.09.2023. Теперь плагин использует Server-to-Server OAuth, а старых полей API Key и API Secret больше нет.

Поэтому уже существующий экземпляр плагина Zoom хранит конфигурацию, которую эта версия прочитать не может, а нечитаемую конфигурацию плагина Dispatch считает отсутствующей и ошибку не выбрасывает. Плагин по-прежнему выглядит включённым, но вместо конференции каждый инцидент получает в хронологию запись "The Zoom plugin configuration could not be read…". Старые JWT-ключ и секрет сконвертировать нельзя, да и для Zoom они в любом случае уже бесполезны.

Чтобы восстановить работу:

1. Создайте приложение Server-to-Server OAuth и настройте плагин, как описано ниже, — отдельно для каждого проекта в каждой организации. Экземпляры плагинов привязаны к проектам, поэтому установке с пятью проектами в двух организациях понадобится десять экземпляров.
2. Заполните заново все поля, включая Zoom API User Id. Сохранённую конфигурацию разобрать невозможно, поэтому форма редактирования откроется пустой — даже для полей, которые не менялись.
3. Удалите или деактивируйте старое JWT-приложение в Marketplace, если оно ещё существует.

Повторное открытие формы плагина стирает client secret

Dispatch возвращает сохранённый client secret в интерфейс замаскированным — как **********, а при сохранении форма записывает обратно то, что в ней лежит. Если открыть плагин Zoom, чтобы поменять любое другое поле — скажем, API User Id, — и сохранить, client secret будет перезаписан этими звёздочками, и аутентификация начнёт падать с ошибкой Invalid client_id or client_secret. Вводите Client Secret заново при каждом сохранении этой формы. Это касается любого плагина с секретным полем, не только Zoom.

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

1. В Zoom App Marketplace войдите как администратор аккаунта и выберите Develop → Build App → Server-to-Server OAuth. (Приложение типа JWT, которое раньше требовалось этому плагину, создать уже нельзя.)

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

3. В разделе Scopes добавьте скоупы для всех четырёх операций, которые выполняет плагин: создание, чтение, обновление и удаление встречи.

   Zoom предлагает два семейства скоупов, и какое из них вы увидите, зависит от приложения. Новым приложениям, как правило, доступны только гранулярные (granular) скоупы, а классические названия могут быть недоступны:

   Операция	Классические	Гранулярные
   Создать встречу	meeting:write:admin	meeting:write:meeting:admin
   Прочитать встречу	meeting:read:admin	meeting:read:meeting:admin
   Обновить список приглашённых	meeting:write:admin	meeting:update:meeting:admin
   Удалить встречу	meeting:write:admin	meeting:delete:meeting:admin

   Гранулярные скоупы делят то, что покрывал классический meeting:write:admin, на три части. Типичная ошибка — выбрать только гранулярную пару на чтение и запись: встречи создаются успешно, а затем каждое обновление списка приглашённых и удаление заканчиваются ошибкой.

   Об отсутствующем скоупе при выдаче токена никто не сообщит: токен выдаётся, а вызов API после этого падает, поэтому добавьте скоупы до настройки Dispatch.

4. На странице App Credentials скопируйте Account ID, Client ID и Client Secret.

Настройка Dispatch

Плагин Zoom настраивается в веб-интерфейсе Dispatch в разделе «Настройки» -> «Проект» -> «Плагины» (Settings -> Project -> Plugins). Добавьте плагин кнопкой NEW, затем откройте его настройки, нажав на три вертикальные точки.

Вводите учётные данные только через эту форму. Не передавайте их в командной строке и не вставляйте в URL: Dispatch хранит client secret в зашифрованной колонке, а любой из этих способов выдаст его в историю оболочки, список процессов или логи прокси.

Zoom API User Id

Email или идентификатор пользователя, от имени которого создаются встречи.

Account ID

Account ID приложения Server-to-Server OAuth со страницы App Credentials.

Client ID

Client ID приложения Server-to-Server OAuth.

Client Secret

Client secret приложения Server-to-Server OAuth. Обращайтесь с ним как с учётными данными: любой, у кого он есть, может действовать от имени аккаунта в пределах скоупов приложения. Если он когда-нибудь утечёт, перевыпустите его в Marketplace.

Default Meeting Duration (Minutes)

Длительность конференций по умолчанию в минутах. По умолчанию 1440 минут (1 день).

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

Создайте тестовый инцидент в проекте с включённым плагином и убедитесь, что появилась ссылка на конференцию. Любой сбой — при аутентификации или в самом вызове создания встречи — записывается в хронологию инцидента вместе с причиной, которую назвал Zoom, а конференция к инциденту не прикрепляется.

Симптом	Причина
HTTP 400: Invalid client_id or client_secret	Неверный Client ID или Client Secret, либо приложение деактивировано. Обратите внимание: эндпоинт токена Zoom отвечает 400, а не 401.
HTTP 400: Invalid account_id (или 400 с упоминанием аккаунта)	Account ID не соответствует аккаунту приложения.
HTTP 400: grant type … is not supported	В запросе токена использован grant, который Zoom здесь не принимает. Server-to-Server OAuth использует account_credentials.
Zoom creation of the meeting failed with HTTP 400 и сообщение с названием скоупа	У приложения не хватает нужного скоупа — чаще всего скоупа на обновление или удаление из гранулярного семейства.
This API does not support client credentials for authorization	Ответ пришёл от API, а не от эндпоинта токена: токен client_credentials предъявлен эндпоинту, которому нужна авторизация аккаунта.
The Zoom plugin configuration could not be read	Плагин всё ещё хранит упразднённые API Key / API Secret. См. примечание об обновлении выше.

Примечания

• Токены доступа живут один час, а refresh-токен Zoom не выдаёт. Dispatch получает токен на каждую операцию и использует его повторно для всех вызовов внутри этой операции; на диск токены не записываются. Ротировать по расписанию ничего не нужно, кроме самого client secret — с той периодичностью, которую требует ваша политика.
• Zoom ограничивает создание встреч 100 в день для настроенного API-пользователя, а обновления встречи — 100 в день на одну встречу. Первый лимит определяет, сколько конференций установка может открыть за 24 часа на весь аккаунт; второй — сколько раз можно менять список приглашённых у одного долгого инцидента. Оба проявляются как ошибки в хронологии, а не как молчаливые сбои.
• add_participant и remove_participant держат список meeting_invitees встречи в соответствии с участниками инцидента. Это метаданные списка приглашённых, а не управление доступом: ссылка для подключения работает у любого, у кого она есть, поэтому добавление в список не даёт ничего сверх опубликованной ссылки, а удаление из него никого не выгоняет и ссылку не отзывает. Поведение зала ожидания — отдельный вопрос, которым этот плагин не управляет.
• Zoom заменяет список приглашённых целиком, поэтому перед каждым изменением Dispatch читает встречу и отправляет существующих приглашённых заново. Сбой записывается в хронологию инцидента и не мешает добавлению или удалению участника во всех остальных местах.
• При чтении Zoom действительно возвращает список приглашённых — это проверено на реальном аккаунте, что и закрыло issue #129, — поэтому список ведётся как обычно: если при создании добавить двух участников реагирования (responders), а затем третьего, при чтении вернутся все трое. Если чтение когда-нибудь вернётся без списка приглашённых, Dispatch оставит список как есть и обновлять его не станет: пересобирать список, который заменяется целиком, из ответа, в котором ничего нет, значило бы выкинуть всех, кто уже был в нём. Это пишется в лог, а не в хронологию инцидента — это не сбой, а первые участники реагирования и так уже в списке. Такого случаться не должно; если всё же случилось, строка лога показывает, в каком виде ответил Zoom, и об этом стоит сообщить. Возможность подключиться ни у кого при этом не меняется.
• Встреча создаётся сразу с начальным списком приглашённых: это участники реагирования, определённые для инцидента, за вычетом тех, кто выключил в своих настройках «Автоматически подключать меня к конференциям инцидентов» (Add me automatically to incident bridges). Список отправляется внутри запроса на создание, а не добавляется потом, поэтому, если Zoom отклонит список, создание завершится ошибкой — а не оставит встречу, о которой Dispatch ничего не знает. Инцидент без таких участников получает встречу без приглашённых, и это не ошибка; запрос, который получает Zoom, в этом случае ровно тот же, каким он был до появления этого списка.
• Поддержка Zoom заявляла на форуме разработчиков, что meeting_invitees используется только их календарными интеграциями, поэтому приглашённый — добавленный при создании или позже — может так и не появиться в клиенте Zoom. Dispatch отправляет то, что описано в документации API. Сотрудники Zoom также заявляли, что заполнение этого списка не порождает писем, так что ни создание конференции, ни обновление её списка приглашённых никого не уведомляет.