Reuniões do Microsoft Teams

Use o pipeline de reuniões do Teams quando você quiser que o Hermes ingira eventos de reunião do Microsoft Graph, busque primeiro as transcrições, recorra às gravações mais STT quando precisar, e entregue um resumo estruturado aos destinos seguintes.

Pré-requisitos: veja Microsoft Teams para a configuração de bot/credenciais por baixo.

Rode hermes gateway setup e escolha Teams Meetings para um passo a passo guiado.

Esta página foca em configuração e habilitação:

• credenciais do Graph
• configuração do ouvinte de webhook
• modos de entrega no Teams
• formato da configuração do pipeline

Para operação do dia a dia, verificações de entrada em produção e a planilha do operador, use o guia dedicado: Operar o pipeline de reuniões do Teams.

O que este recurso faz

O pipeline:

1. recebe eventos de webhook do Microsoft Graph
2. resolve a reunião e prefere primeiro os artefatos de transcrição
3. recorre ao download da gravação mais STT quando não há transcrição utilizável
4. guarda localmente o estado durável dos jobs e os registros de destino
5. pode escrever resumos no Notion, no Linear e no Microsoft Teams

As ações do operador ficam na CLI (o subcomando teams-pipeline é registrado pelo plugin teams_pipeline — habilite-o com hermes plugins enable teams_pipeline ou defina plugins.enabled: [teams_pipeline] no config.yaml):

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

Pré-requisitos

Antes de habilitar o pipeline de reuniões, garanta que você tem:

• uma instalação do Hermes funcionando
• a configuração de bot do Microsoft Teams já existente, se você quiser entrega de saída pelo Teams
• credenciais de aplicativo do Microsoft Graph com as permissões exigidas pelos recursos de reunião que você pretende assinar
• uma URL HTTPS pública que o Microsoft Graph consiga chamar para entregar os webhooks
• o ffmpeg instalado, se você quiser o fallback de gravação mais STT

Passo 1: adicionar as credenciais do Microsoft Graph

Adicione as credenciais de aplicativo do Graph em ~/.hermes/.env:

MSGRAPH_TENANT_ID=<id-do-tenant>
MSGRAPH_CLIENT_ID=<id-do-cliente>
MSGRAPH_CLIENT_SECRET=<segredo-do-cliente>

Essas credenciais são usadas por:

• a base do cliente do Graph
• os comandos de manutenção de assinaturas
• a resolução de reuniões e a busca de artefatos
• a entrega de saída no Teams pelo Graph, quando você não fornece um token de acesso dedicado do Teams

Passo 2: habilitar o ouvinte de webhook do Graph

O ouvinte de webhook é uma plataforma de gateway chamada msgraph_webhook. No mínimo, habilite-o e defina um valor de client state:

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=<segredo-compartilhado-aleatorio>
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

O host de vínculo é lido do extra.host da plataforma no config.yaml (não existe variável de ambiente MSGRAPH_WEBHOOK_HOST — veja a referência do ouvinte de webhook).

O ouvinte expõe:

• /msgraph/webhook para as notificações do Graph
• /health para uma verificação simples de saúde

Você precisa rotear o seu endpoint HTTPS público para esse ouvinte. Por exemplo, se o seu domínio público é https://ops.example.com, a sua URL de notificação do Graph normalmente seria:

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

Passo 3: configurar a entrega no Teams e o comportamento do pipeline

O pipeline de reuniões lê a configuração de execução da entrada de plataforma teams já existente. Os botões específicos do pipeline ficam sob teams.extra.meeting_pipeline. A entrega de saída no Teams continua na superfície normal de configuração da plataforma Teams.

Exemplo de ~/.hermes/config.yaml:

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

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

      # entrega do resumo de saída
      delivery_mode: "graph" # ou 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

Se você vincular o ouvinte a um host fora do loopback, como 0.0.0.0, também precisa definir allowed_source_cidrs com as faixas de saída de webhook da Microsoft. Vínculos de loopback (127.0.0.1 / ::1) são a configuração pensada para túnel de desenvolvimento e proxy reverso local.

Modos de entrega no Teams

O pipeline suporta dois modos de entrega de resumo no Teams dentro do plugin de Teams já existente.

incoming_webhook

Use este quando você quiser uma postagem simples por webhook no Teams, sem criar mensagem de canal pelo Graph.

Configuração obrigatória:

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

graph

Use este quando você quiser que o Hermes poste o resumo pelo Microsoft Graph em uma conversa ou canal do Teams.

Alvos suportados:

• chat_id
• team_id + channel_id
• team_id + fallback de home_channel para a plataforma Teams já existente

Exemplo:

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

Passo 4: subir o gateway

Suba o Hermes normalmente depois de atualizar a configuração:

hermes gateway run

Ou, se você roda o Hermes em Docker, suba o gateway do mesmo jeito que já faz na sua implantação.

Confira o ouvinte:

curl http://localhost:8646/health

Passo 5: criar as assinaturas do Graph

Use a CLI do plugin para criar e inspecionar assinaturas.

Exemplos:

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"

As assinaturas do Graph expiram em 72 horas

O Microsoft Graph limita as assinaturas de webhook a 72 horas e não as renova sozinho. Você PRECISA agendar o hermes teams-pipeline maintain-subscriptions antes de entrar em produção, ou as notificações param em silêncio três dias depois de qualquer criação manual de assinatura. Veja Automatizar a renovação de assinaturas no manual do operador — três opções (cron do Hermes, timer do systemd, crontab simples).

Para manutenção de assinaturas e fluxos de operação do dia a dia, siga com o guia: Operar o pipeline de reuniões do Teams.

Validação

Rode o retrato de validação embutido:

hermes teams-pipeline validate

Verificações complementares úteis:

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

Resolução de problemas

Problema	O que conferir
A validação do webhook do Graph falha	Confirme que a URL pública está correta e acessível, e que o Graph está chamando exatamente o caminho /msgraph/webhook
Os jobs não aparecem em hermes teams-pipeline list	Confirme que o msgraph_webhook está habilitado e que as assinaturas apontam para a URL de notificação certa
A transcrição nunca vem primeiro	Verifique as permissões do Graph para recursos de transcrição e se o artefato de transcrição existe para aquela reunião
O fallback de gravação falha	Confirme que o ffmpeg está instalado e que o aplicativo do Graph consegue acessar os artefatos de gravação
A entrega do resumo no Teams falha	Reveja o delivery_mode, os IDs de destino e a configuração de autenticação do Teams

Documentos relacionados

• Configuração do bot do Microsoft Teams
• Operar o pipeline de reuniões do Teams

---