Hermes Teams Pipeline Reference

This document covers all operator commands for the hermes teams-pipeline tool. It handles user requests about Microsoft Teams meeting summaries, transcripts, recordings, action items, Graph subscriptions, and operational questions about the Teams meeting pipeline. The tool works in any language.

Prerequisites

Before using any command, ensure the following environment variables are set in the file ${HERMES_HOME:-~/.hermes}/.env:

MSGRAPH_TENANT_ID=...
MSGRAPH_CLIENT_ID=...
MSGRAPH_CLIENT_SECRET=...

You must also have an Azure AD app registration with admin-consented Graph application permissions. See the guide at /docs/guides/microsoft-graph-app-registration for setup instructions.

When to Use

Use hermes teams-pipeline in these situations:

User asks to summarize a Teams meeting, extract action items, or pull meeting notes.
User asks to check pipeline status, inspect a stored meeting job, or see recent meetings.
User asks to replay/re-run a stored job that failed or needs a fresh summary.
User asks to validate Microsoft Graph setup after changing environment or config.
User asks to troubleshoot "meeting summary never arrived" or "no new meetings are ingesting".
User asks to manage Graph webhook subscriptions (create, renew, delete, inspect).
User asks to set up automated subscription renewal.

Pipeline Validation and Health Checks

Run these commands to verify the pipeline is working. Start with validation after any configuration change.

hermes teams-pipeline validate              # config snapshot — run first after any change
hermes teams-pipeline token-health          # Graph token status
hermes teams-pipeline token-health --force-refresh   # force a fresh token acquisition
hermes teams-pipeline list                  # recent meeting jobs
hermes teams-pipeline list --status failed  # only failed jobs
hermes teams-pipeline show <job-id>         # full detail of one job
hermes teams-pipeline subscriptions         # current Graph webhook subscriptions

The validate command checks the pipeline configuration snapshot. token-health checks Graph token status; use --force-refresh to force a fresh token acquisition. list shows recent meeting jobs, optionally filtered by --status (e.g., list --status failed). show displays full detail of a specific job. subscriptions lists current Graph webhook subscriptions.

Procedure: Verify Pipeline Setup is Working

Run hermes teams-pipeline validate.
Run hermes teams-pipeline token-health.
Run hermes teams-pipeline subscriptions.
If all pass, request a test meeting and check hermes teams-pipeline list for a fresh row.

Managing Meeting Jobs

These commands handle fetching, replaying, and inspecting meeting jobs.

hermes teams-pipeline run <job-id>          # replay a stored job (re-summarize, re-deliver)
hermes teams-pipeline fetch --meeting-id <id>   # dry-run: resolve meeting + transcript without persisting
hermes teams-pipeline fetch --join-web-url "<url>"   # dry-run by join URL

The run command replays a stored job, re-summarizing and re-delivering. The fetch command performs a dry-run fetch of the meeting transcript without persisting. Use --meeting-id for a meeting ID or --join-web-url for a join web URL.

Procedure: Re-run Summary for a Specific Meeting

Run hermes teams-pipeline list to find the job ID.
Run hermes teams-pipeline run <job-id> to replay.
If it fails again, run hermes teams-pipeline show <job-id> to inspect error.
Run hermes teams-pipeline fetch --meeting-id <id> to dry-run artifact resolution.

Procedure: Troubleshoot Missing Meeting Summary

Run hermes teams-pipeline list --status failed.
Run hermes teams-pipeline show <job-id> on the relevant row.
If job does not exist, run hermes teams-pipeline subscriptions to check if webhook expired.

Graph Webhook Subscription Management

Manage Graph webhook subscriptions with these commands.

hermes teams-pipeline subscribe \
  --resource communications/onlineMeetings/getAllTranscripts \
  --notification-url https://<your-public-host>/msgraph/webhook \
  --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"

hermes teams-pipeline renew-subscription <sub-id> --expiration <iso-8601>
hermes teams-pipeline delete-subscription <sub-id>
hermes teams-pipeline maintain-subscriptions            # renew near-expiry ones
hermes teams-pipeline maintain-subscriptions --dry-run  # show what would be renewed

The subscribe command creates a new subscription. Required parameters: --resource (e.g., communications/onlineMeetings/getAllTranscripts), --notification-url (public URL where Graph sends webhook notifications), and --client-state (client state string, value from MSGRAPH_WEBHOOK_CLIENT_STATE env var). renew-subscription renews a specific subscription with a new expiration datetime in ISO 8601 format. delete-subscription removes a subscription. maintain-subscriptions renews near-expiry ones; use --dry-run to show what would be renewed without actually renewing.

Procedure: Handle Expired Graph Subscriptions (Pipeline Stopped Working)

Run hermes teams-pipeline subscriptions. If empty or all entries have past expirationDateTime, subscriptions expired.
Recreate subscription using hermes teams-pipeline subscribe with required parameters.
Set up automated renewal via hermes cron add, systemd timer, or crontab (12-hour interval recommended).

Constraints and Caveats

All operator-facing commands are hermes teams-pipeline subcommands run via terminal tool; no new model tools exist.
Graph webhook subscriptions expire in 72 hours and will not auto-renew; must set up automated renewal.
Transcript may not be available immediately after meeting ends; wait 2-5 minutes or let Graph webhook drive ingestion.
If summaries are produced (list shows success) but not delivered to Teams, check delivery mode and target config. Look at platforms.teams.extra.delivery_mode, incoming_webhook_url, chat_id, or team_id and channel_id. Also check TEAMS_* environment variables.
Graph app permissions may require re-granting admin consent in Azure portal even if token-health passes.
Pipeline is subscription-driven, not per-meeting; to summarize a specific past meeting, use fetch then run after job created.

Failure Modes

Meeting summary never arrives: webhook subscription expired (empty or past expirationDateTime).
No new meetings ingesting: webhook subscription expired or not set up.
Transcript fetch returns empty: meeting just ended, transcript not yet generated.
Summaries produced but not delivered to Teams: delivery mode or target config mismatch.
Token-health passes but Graph API calls return 401/403: admin consent not re-granted after permission changes.

Additional Documentation

For user-facing guidance on Teams meetings, see /docs/user-guide/messaging/teams-meetings. For operational pipeline details, see /docs/guides/operate-teams-meeting-pipeline. For webhook setup, see /docs/user-guide/messaging/msgraph-webhook. For automated subscription renewal, see /docs/guides/operate-teams-meeting-pipeline#automating-subscription-renewal-required-for-production.

Example User Requests

The tool handles requests in any language. Examples include:

English: "summarize the Teams meeting", "pipeline status", "replay job X".
Turkish: "Teams meeting özetle", "action item çıkar", "toplantı notu", "pipeline durumu", "replay job".

Teams Meeting Pipeline: Summaries, Replay, and Graph Subscriptions