Встречи Microsoft Teams

Пайплайн для встреч Teams нужен, когда Hermes должен принимать события встреч из Microsoft Graph, сначала тянуть транскрипты, при необходимости откатываться к записям плюс STT и доставлять структурированное саммари в нижестоящие приёмники.

Предварительные требования смотрите в Microsoft Teams — там описана базовая настройка бота и учётных данных.

Запустите hermes gateway setup и выберите Teams Meetings — это проведёт вас по настройке шаг за шагом.

Эта страница посвящена настройке и включению:

учётные данные Graph
конфигурация слушателя вебхуков
режимы доставки в Teams
форма конфига пайплайна

Повседневная эксплуатация, проверки перед запуском и рабочий лист оператора вынесены в отдельный гайд: Эксплуатация пайплайна встреч Teams.

Что делает эта функция

Пайплайн работает так:

получает события вебхуков Microsoft Graph
определяет встречу и в первую очередь предпочитает артефакты транскрипта
при отсутствии пригодного транскрипта откатывается к скачиванию записи плюс STT
хранит устойчивое состояние задач и записи приёмников локально
умеет писать саммари в Notion, Linear и Microsoft Teams

Действия оператора остаются в CLI (подкоманду teams-pipeline регистрирует плагин teams_pipeline — включите его через hermes plugins enable teams_pipeline или пропишите plugins.enabled: [teams_pipeline] в config.yaml):

hermes teams-pipeline validate
hermes teams-pipeline list
hermes teams-pipeline maintain-subscriptions

Предварительные требования

Прежде чем включать пайплайн встреч, убедитесь, что у вас есть:

рабочая установка Hermes
уже настроенный бот Microsoft Teams, если вам нужна исходящая доставка в Teams
учётные данные приложения Microsoft Graph с правами, которые требуются для тех ресурсов встреч, на которые вы планируете подписываться
публичный HTTPS-URL, по которому Microsoft Graph сможет доставлять вебхуки
установленный ffmpeg, если вам нужен откат к схеме «запись плюс STT»

Шаг 1: добавьте учётные данные Microsoft Graph

Пропишите app-only-учётные данные Graph в ~/.hermes/.env:

MSGRAPH_TENANT_ID=<tenant-id>
MSGRAPH_CLIENT_ID=<client-id>
MSGRAPH_CLIENT_SECRET=<client-secret>

Эти учётные данные используют:

основа клиента Graph
команды обслуживания подписок
разрешение встреч и загрузка артефактов
исходящая доставка в Teams через Graph, когда вы не задаёте отдельный access-токен для Teams

Шаг 2: включите слушатель вебхуков Graph

Слушатель вебхуков — это платформа шлюза с именем msgraph_webhook. Минимум, что нужно: включить её и задать значение client state:

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_HOST=127.0.0.1
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=<random-shared-secret>
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

Слушатель отдаёт два эндпоинта:

/msgraph/webhook — для уведомлений Graph
/health — для простой проверки здоровья

Свой публичный HTTPS-эндпоинт нужно завернуть на этот слушатель. Скажем, если ваш публичный домен — https://ops.example.com, то URL уведомлений Graph обычно будет таким:

https://ops.example.com/msgraph/webhook

Шаг 3: настройте доставку в Teams и поведение пайплайна

Свою рантайм-конфигурацию пайплайн встреч читает из уже существующей записи платформы teams. Специфичные для пайплайна параметры лежат под teams.extra.meeting_pipeline. Исходящая доставка в Teams остаётся на обычной поверхности конфига платформы Teams.

Пример ~/.hermes/config.yaml:

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "replace-me"
      accepted_resources:
        - "communications/onlineMeetings"

  teams:
    enabled: true
    extra:
      client_id: "your-teams-client-id"
      client_secret: "your-teams-client-secret"
      tenant_id: "your-teams-tenant-id"

      # исходящая доставка саммари
      delivery_mode: "graph" # или incoming_webhook
      team_id: "team-id"
      channel_id: "channel-id"
      # incoming_webhook_url: "https://..."

      meeting_pipeline:
        transcript_min_chars: 80
        transcript_required: false
        transcription_fallback: true
        ffmpeg_extract_audio: true
        notion:
          enabled: false
        linear:
          enabled: false

Если вы привязываете слушатель к non-loopback-хосту вроде 0.0.0.0, придётся также задать allowed_source_cidrs — диапазоны исходящего трафика вебхуков Microsoft. Привязки к loopback (127.0.0.1 / ::1) рассчитаны на dev-туннель и локальный reverse-proxy.

Режимы доставки в Teams

Пайплайн поддерживает два режима доставки саммари в Teams внутри уже существующего плагина Teams.

`incoming_webhook`

Берите этот вариант, когда нужен простой пост через вебхук в Teams без создания сообщения в канале через Graph.

Обязательный конфиг:

platforms:
  teams:
    enabled: true
    extra:
      delivery_mode: "incoming_webhook"
      incoming_webhook_url: "https://..."

`graph`

Берите этот вариант, когда Hermes должен публиковать саммари через Microsoft Graph в чат или канал Teams.

Поддерживаемые цели:

chat_id
team_id + channel_id
team_id + откат на home_channel для существующей платформы Teams

Пример:

platforms:
  teams:
    enabled: true
    extra:
      delivery_mode: "graph"
      team_id: "team-id"
      channel_id: "channel-id"

Шаг 4: запустите шлюз

После правки конфига запустите Hermes обычным образом:

hermes gateway run

А если вы держите Hermes в Docker, поднимайте шлюз так же, как уже делаете это в своём развёртывании.

Проверьте слушатель:

curl http://localhost:8646/health

Шаг 5: создайте подписки Graph

Подписки создают и просматривают через CLI плагина.

Примеры:

hermes teams-pipeline subscribe \
  --resource communications/onlineMeetings/getAllTranscripts \
  --notification-url https://ops.example.com/msgraph/webhook \
  --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"

hermes teams-pipeline subscribe \
  --resource communications/onlineMeetings/getAllRecordings \
  --notification-url https://ops.example.com/msgraph/webhook \
  --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"

внимание

Подписки Graph истекают через 72 часа

Microsoft Graph ограничивает срок жизни вебхук-подписок 72 часами и не продлевает их автоматически. Перед запуском в бой вы ОБЯЗАНЫ поставить hermes teams-pipeline maintain-subscriptions на расписание, иначе уведомления тихо прекратятся через трое суток после любого ручного создания подписки. Смотрите Автоматизация продления подписок в runbook оператора — там три варианта (cron от Hermes, таймер systemd, обычный crontab).

По обслуживанию подписок и повседневным операторским сценариям переходите к гайду: Эксплуатация пайплайна встреч Teams.

Проверка

Запустите встроенный валидационный снапшот:

hermes teams-pipeline validate

Полезные сопутствующие проверки:

hermes teams-pipeline token-health
hermes teams-pipeline subscriptions

Устранение неполадок

Проблема	Что проверить
Не проходит валидация вебхука Graph	Убедитесь, что публичный URL верный и доступен, а Graph обращается ровно по пути `/msgraph/webhook`
Задачи не появляются в `hermes teams-pipeline list`	Проверьте, что `msgraph_webhook` включён и подписки указывают на правильный URL уведомлений
Схема «сначала транскрипт» никогда не срабатывает	Проверьте права Graph на ресурсы транскриптов и наличие артефакта транскрипта для этой встречи
Падает откат к записи	Убедитесь, что `ffmpeg` установлен и приложение Graph имеет доступ к артефактам записи
Не доставляется саммари в Teams	Перепроверьте `delivery_mode`, целевые ID и конфигурацию авторизации Teams