Teams Meeting Pipeline: Summaries, Replay, Graph Subscriptions

The Teams Meeting Pipeline skill turns Microsoft Teams meetings into actionable summaries, action items, and notes, all driven by Microsoft Graph webhooks. You reach for it when a user asks why a meeting summary never arrived, wants to replay a failed job, or needs to validate the Graph setup after a config change. It is a bundled skill in Hermes Agent, so it is installed by default and ready to use.

What it does

This skill is the operational surface for the Teams meeting pipeline. Everything you do with it happens through hermes teams-pipeline subcommands run via the terminal tool. There are no new model tools; the CLI is the only interface. The skill covers four main areas:

Summaries and action items: Pull transcripts and generate meeting summaries, notes, and action items.
Job inspection and replay: List recent meeting jobs, inspect a specific job's full detail, and re-run a stored job that failed or needs a fresh summary.
Graph validation: Check that your Microsoft Graph configuration is correct and that tokens are healthy.
Subscription management: Create, renew, delete, and maintain the Graph webhook subscriptions that feed the pipeline.

The skill works in any language. The trigger examples in the source are just that: examples. English and Turkish are shown, but the skill responds to the intent, not a fixed phrase list.

Before you start

Before the pipeline will work, you need three environment variables set in ${HERMES_HOME:-~/.hermes}/.env:

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

If any of these are missing, the user needs to complete an Azure AD app registration with admin-consented Graph application permissions. Point them to the guide at /docs/guides/microsoft-graph-app-registration. Without that consent, the pipeline cannot authenticate, no matter what else you configure.

Status and inspection (start here)

When you are troubleshooting or just checking that everything is healthy, start with these commands. They give you a snapshot of the pipeline's state without changing anything.

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

Run validate first after any change to env or config. It prints a config snapshot so you can confirm the pipeline sees what you expect. Then token-health tells you whether the Graph token is valid; if it is expired or you suspect a stale token, --force-refresh acquires a fresh one. list shows recent meeting jobs, and --status failed filters to only the failures, which is the fastest way to find a problem. show <job-id> gives you the full detail of one job, including any error. subscriptions lists the current Graph webhook subscriptions, which is critical for diagnosing silent ingestion failures.

Re-running and debugging

When a job fails or you need a fresh summary, use these commands. They let you replay a stored job or dry-run the artifact resolution without persisting anything.

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
hermes teams-pipeline fetch --join-web-url "<url>" --organizer-user-id <id>   # organizer-scoped lookup (required for /meet/ short URLs)

run <job-id> replays a stored job, which re-summarizes and re-delivers the output. This is what you use when a summary failed or the user wants a fresh one. fetch is a dry-run: it resolves the meeting and transcript without persisting a job. Use --meeting-id when you have the meeting ID, or --join-web-url with the join URL. For /meet/ short URLs, you must also pass --organizer-user-id; without it, the lookup will not resolve.

Subscription management

Graph webhook subscriptions are what make the pipeline ingestion-driven. You create one with subscribe, renew it with renew-subscription, delete it with delete-subscription, and automate renewal with maintain-subscriptions.

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 subscription for the communications/onlineMeetings/getAllTranscripts resource, which is what delivers new meeting transcripts to your webhook. The --notification-url must be a public HTTPS endpoint that receives the webhook. The --client-state is a secret string you set to validate that notifications come from Graph; it is read from the MSGRAPH_WEBHOOK_CLIENT_STATE environment variable. renew-subscription extends a subscription to a new expiration time, and delete-subscription removes one. maintain-subscriptions renews any that are near expiry, and --dry-run shows what would be renewed without doing it.

Decision tree for common asks

When a user reports a problem, the source gives a clear decision tree. Here is how to apply it.

"Why didn't I get a summary for today's meeting?" Start with list --status failed to see if the job failed. If there is a row, run show on it to see the error. If the job does not exist at all, check subscriptions; the webhook may have expired, which is the critical pitfall below.
"Is setup working?" Run validate, then token-health, then subscriptions. If all three pass, request a test meeting and check list for a fresh row. That confirms the whole path end to end.
"Re-run summary for meeting X" Use list to find the job ID, then run to replay it. If it fails again, show to inspect the error and fetch --meeting-id to dry-run the artifact resolution.
"Add meeting X to the pipeline" Usually you do not. The pipeline is subscription-driven, not per-meeting. If the user wants a specific past meeting summarized, use fetch to pull the transcript and run after a job is created.

Critical pitfall: Graph subscriptions expire in 72 hours

Microsoft Graph caps webhook subscriptions at 72 hours and will not auto-renew them. If maintain-subscriptions is not scheduled, meeting notifications silently stop arriving three days after any manual subscription creation. This is the most common cause of "the pipeline worked yesterday but nothing is arriving today."

When that happens, follow these steps:

Run hermes teams-pipeline subscriptions. If it is empty or all entries show expirationDateTime in the past, that is the cause.
Recreate the subscription with subscribe as shown above.
Set up automated renewal immediately via hermes cron add, a systemd timer, or plain crontab. The operator runbook at /docs/guides/operate-teams-meeting-pipeline#automating-subscription-renewal-required-for-production has all three options. A 12-hour interval is safe, giving 6x headroom against the 72-hour limit.

Other pitfalls

Transcript not available yet. Teams takes some time after a meeting ends to generate the transcript artifact. fetch --meeting-id on a just-ended meeting may return empty. Wait 2-5 minutes and retry, or let the Graph webhook drive ingestion naturally.
Delivery mode mismatch. If summaries are produced (list shows success) but nothing lands in Teams, check platforms.teams.extra.delivery_mode and the matching target config (incoming_webhook_url OR chat_id OR team_id+channel_id). The writer reads these from config.yaml or TEAMS_* env vars.
Graph app permissions. A token can acquire cleanly (token-health passes) but Graph API calls still return 401/403 when permissions were added but admin consent was not re-granted. Have the user revisit the app registration in the Azure portal and click "Grant admin consent" again.

When not to use it

This skill is for operational questions about the Teams meeting pipeline. If the user wants to configure the pipeline from scratch, point them to the full setup guide at /docs/user-guide/messaging/teams-meetings. If they need to set up the webhook listener itself, that is covered in /docs/user-guide/messaging/msgraph-webhook. This skill assumes the pipeline is already installed and configured; it is not the place to build it.

Related docs

When the user needs more depth than this skill covers, point them to these:

Azure app registration walkthrough: /docs/guides/microsoft-graph-app-registration
Full pipeline setup: /docs/user-guide/messaging/teams-meetings
Operator runbook (renewal automation, troubleshooting, go-live checklist): /docs/guides/operate-teams-meeting-pipeline
Webhook listener setup: /docs/user-guide/messaging/msgraph-webhook

Teams Meeting Pipeline: Summaries, Replay, and Graph Subscriptions