From b79ef8827fdcbe46064ea0ea5fd9b7dc2b1cba54 Mon Sep 17 00:00:00 2001 From: Dilee Date: Thu, 7 May 2026 17:27:11 +0300 Subject: [PATCH] docs(teams): split meetings setup from operator runbook --- .../guides/operate-teams-meeting-pipeline.md | 193 +++++++++++++++ website/docs/user-guide/messaging/index.md | 3 +- .../user-guide/messaging/teams-meetings.md | 227 ++++++++++++++++++ website/docs/user-guide/messaging/teams.md | 7 + 4 files changed, 429 insertions(+), 1 deletion(-) create mode 100644 website/docs/guides/operate-teams-meeting-pipeline.md create mode 100644 website/docs/user-guide/messaging/teams-meetings.md diff --git a/website/docs/guides/operate-teams-meeting-pipeline.md b/website/docs/guides/operate-teams-meeting-pipeline.md new file mode 100644 index 0000000000..7686e40aa0 --- /dev/null +++ b/website/docs/guides/operate-teams-meeting-pipeline.md @@ -0,0 +1,193 @@ +--- +title: "Operate the Teams Meeting Pipeline" +description: "Runbook, go-live checklist, and operator worksheet for the Microsoft Teams meeting pipeline" +--- + +# Operate the Teams Meeting Pipeline + +Use this guide after you have already enabled the feature from [Teams Meetings](/docs/user-guide/messaging/teams-meetings). + +This page covers: +- operator CLI flows +- routine subscription maintenance +- failure triage +- go-live checks +- rollout worksheet + +## Core Operator Commands + +### Validate the config snapshot + +```bash +hermes teams-pipeline validate +``` + +Use this first after any config change. + +### Inspect token health + +```bash +hermes teams-pipeline token-health +hermes teams-pipeline token-health --force-refresh +``` + +Use `--force-refresh` when you suspect stale auth state. + +### Inspect subscriptions + +```bash +hermes teams-pipeline subscriptions +``` + +### Renew near-expiry subscriptions + +```bash +hermes teams-pipeline maintain-subscriptions +hermes teams-pipeline maintain-subscriptions --dry-run +``` + +### Inspect recent jobs + +```bash +hermes teams-pipeline list +hermes teams-pipeline list --status failed +hermes teams-pipeline show +``` + +### Replay a stored job + +```bash +hermes teams-pipeline run +``` + +### Dry-run meeting artifact fetches + +```bash +hermes teams-pipeline fetch --meeting-id +hermes teams-pipeline fetch --join-web-url "" +``` + +## Routine Runbook + +### After first setup + +Run these in order: + +```bash +hermes teams-pipeline validate +hermes teams-pipeline token-health --force-refresh +hermes teams-pipeline subscriptions +``` + +Then trigger or wait for a real meeting event and confirm: + +```bash +hermes teams-pipeline list +hermes teams-pipeline show +``` + +### Daily or periodic checks + +- run `hermes teams-pipeline maintain-subscriptions --dry-run` +- inspect `hermes teams-pipeline list --status failed` +- verify the Teams delivery target is still the correct chat or channel + +### Before changing webhook URLs or delivery targets + +- update the public notification URL or Teams target config +- run `hermes teams-pipeline validate` +- renew or recreate affected subscriptions +- confirm new events land in the expected sink + +## Failure Triage + +### No jobs are being created + +Check: +- `msgraph_webhook` is enabled +- the public notification URL points to `/msgraph/webhook` +- the client state in the subscription matches `MSGRAPH_WEBHOOK_CLIENT_STATE` +- subscriptions still exist remotely and are not expired + +### Jobs stay in retry or fail before summarization + +Check: +- transcript permissions and availability +- recording permissions and artifact availability +- `ffmpeg` availability if recording fallback is enabled +- Graph token health + +### Summaries are produced but not delivered to Teams + +Check: +- `platforms.teams.enabled: true` +- `delivery_mode` +- `incoming_webhook_url` for webhook mode +- `chat_id` or `team_id` plus `channel_id` for Graph mode +- Teams auth config if Graph posting is used + +### Duplicate or unexpected replays + +Check: +- whether you manually replayed a job with `hermes teams-pipeline run` +- whether the sink record already exists for that meeting +- whether you intentionally enabled a resend path in your local config + +## Go-Live Checklist + +- [ ] Graph credentials are present and correct +- [ ] `msgraph_webhook` is enabled and reachable from the public internet +- [ ] `MSGRAPH_WEBHOOK_CLIENT_STATE` is set and matches subscriptions +- [ ] transcript subscription is created +- [ ] recording subscription is created if STT fallback is required +- [ ] `ffmpeg` is installed if recording fallback is enabled +- [ ] Teams outbound delivery target is configured and verified +- [ ] Notion and Linear sinks are configured only if actually needed +- [ ] `hermes teams-pipeline validate` returns an OK snapshot +- [ ] `hermes teams-pipeline token-health --force-refresh` succeeds +- [ ] a real end-to-end meeting event has produced a stored job +- [ ] at least one summary has reached the intended delivery sink + +## Delivery-Mode Decision Guide + +| Mode | Use when | Tradeoff | +|------|----------|----------| +| `incoming_webhook` | you only need simple posting into Teams | simplest setup, less control | +| `graph` | you need channel or chat posting through Graph | more control, more auth and target config | + +## Operator Worksheet + +Fill this out before rollout: + +| Item | Value | +|------|-------| +| Public notification URL | | +| Graph tenant ID | | +| Graph client ID | | +| Webhook client state | | +| Transcript resource subscription | | +| Recording resource subscription | | +| Teams delivery mode | | +| Teams chat ID or team/channel | | +| Notion database ID | | +| Linear team ID | | +| Store path override, if any | | +| Owner for daily checks | | + +## Change Review Worksheet + +Use this before changing the deployment: + +| Question | Answer | +|----------|--------| +| Are we changing the public webhook URL? | | +| Are we rotating Graph credentials? | | +| Are we changing Teams delivery mode? | | +| Are we moving to a new Teams chat or channel? | | +| Do subscriptions need to be recreated or renewed? | | +| Do we need a fresh end-to-end verification run? | | + +## Related Docs + +- [Teams Meetings setup](/docs/user-guide/messaging/teams-meetings) +- [Microsoft Teams bot setup](/docs/user-guide/messaging/teams) diff --git a/website/docs/user-guide/messaging/index.md b/website/docs/user-guide/messaging/index.md index 866fcc1d33..24970ac235 100644 --- a/website/docs/user-guide/messaging/index.md +++ b/website/docs/user-guide/messaging/index.md @@ -427,5 +427,6 @@ Each platform has its own toolset: - [QQBot Setup](qqbot.md) - [Yuanbao Setup](yuanbao.md) - [Microsoft Teams Setup](teams.md) +- [Teams Meetings Pipeline](teams-meetings.md) - [Open WebUI + API Server](open-webui.md) -- [Webhooks](webhooks.md) \ No newline at end of file +- [Webhooks](webhooks.md) diff --git a/website/docs/user-guide/messaging/teams-meetings.md b/website/docs/user-guide/messaging/teams-meetings.md new file mode 100644 index 0000000000..9e231a5a80 --- /dev/null +++ b/website/docs/user-guide/messaging/teams-meetings.md @@ -0,0 +1,227 @@ +--- +sidebar_position: 6 +title: "Teams Meetings" +description: "Set up the Microsoft Teams meeting summary pipeline with Microsoft Graph webhooks" +--- + +# Microsoft Teams Meetings + +Use the Teams meeting pipeline when you want Hermes to ingest Microsoft Graph meeting events, fetch transcripts first, fall back to recordings plus STT when needed, and deliver a structured summary to downstream sinks. + +This page focuses on setup and enablement: +- Graph credentials +- webhook listener configuration +- Teams delivery modes +- pipeline config shape + +For day-2 operations, go-live checks, and the operator worksheet, use the dedicated guide: [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline). + +## What This Feature Does + +The pipeline: +1. receives Microsoft Graph webhook events +2. resolves the meeting and prefers transcript artifacts first +3. falls back to recording download plus STT when no usable transcript is available +4. stores durable job state and sink records locally +5. can write summaries to Notion, Linear, and Microsoft Teams + +Operator actions stay in the CLI: + +```bash +hermes teams-pipeline validate +hermes teams-pipeline list +hermes teams-pipeline maintain-subscriptions +``` + +## Prerequisites + +Before enabling the meetings pipeline, make sure you have: + +- a working Hermes install +- the existing [Microsoft Teams bot setup](/docs/user-guide/messaging/teams) if you want Teams outbound delivery +- Microsoft Graph application credentials with the permissions required for the meeting resources you plan to subscribe to +- a public HTTPS URL that Microsoft Graph can call for webhook delivery +- `ffmpeg` installed if you want recording-plus-STT fallback + +## Step 1: Add Microsoft Graph Credentials + +Add Graph app-only credentials to `~/.hermes/.env`: + +```bash +MSGRAPH_TENANT_ID= +MSGRAPH_CLIENT_ID= +MSGRAPH_CLIENT_SECRET= +``` + +These credentials are used by: +- the Graph client foundation +- subscription maintenance commands +- meeting resolution and artifact fetches +- Graph-based Teams outbound delivery when you do not provide a dedicated Teams access token + +## Step 2: Enable the Graph Webhook Listener + +The webhook listener is a gateway platform named `msgraph_webhook`. At minimum, enable it and set a client state value: + +```bash +MSGRAPH_WEBHOOK_ENABLED=true +MSGRAPH_WEBHOOK_PORT=8646 +MSGRAPH_WEBHOOK_CLIENT_STATE= +MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings +``` + +The listener exposes: +- `/msgraph/webhook` for Graph notifications +- `/health` for a simple health check + +You need to route your public HTTPS endpoint to that listener. For example, if your public domain is `https://ops.example.com`, your Graph notification URL would typically be: + +```text +https://ops.example.com/msgraph/webhook +``` + +## Step 3: Configure Teams Delivery and Pipeline Behavior + +The meeting pipeline reads its runtime config from the existing `teams` platform entry. Pipeline-specific knobs live under `teams.extra.meeting_pipeline`. Teams outbound delivery stays on the normal Teams platform config surface. + +Example `~/.hermes/config.yaml`: + +```yaml +platforms: + msgraph_webhook: + enabled: true + extra: + 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" + + # outbound summary delivery + delivery_mode: "graph" # or 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 +``` + +## Teams Delivery Modes + +The pipeline supports two Teams summary-delivery modes inside the existing Teams plugin. + +### `incoming_webhook` + +Use this when you want a simple webhook post into Teams without channel-message creation through Graph. + +Required config: + +```yaml +platforms: + teams: + enabled: true + extra: + delivery_mode: "incoming_webhook" + incoming_webhook_url: "https://..." +``` + +### `graph` + +Use this when you want Hermes to post the summary through Microsoft Graph into a Teams chat or channel. + +Supported targets: +- `chat_id` +- `team_id` + `channel_id` +- `team_id` + `home_channel` fallback for the existing Teams platform + +Example: + +```yaml +platforms: + teams: + enabled: true + extra: + delivery_mode: "graph" + team_id: "team-id" + channel_id: "channel-id" +``` + +## Step 4: Start the Gateway + +Start Hermes normally after updating config: + +```bash +hermes gateway run +``` + +Or, if you run Hermes in Docker, start the gateway the same way you already do for your deployment. + +Check the listener: + +```bash +curl http://localhost:8646/health +``` + +## Step 5: Create Graph Subscriptions + +Use the plugin CLI to create and inspect subscriptions. + +Examples: + +```bash +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" +``` + +For subscription maintenance and day-2 operator flows, continue with the guide: [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline). + +## Validation + +Run the built-in validation snapshot: + +```bash +hermes teams-pipeline validate +``` + +Useful companion checks: + +```bash +hermes teams-pipeline token-health +hermes teams-pipeline subscriptions +``` + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| Graph webhook validation fails | Confirm the public URL is correct and reachable, and that Graph is calling the exact `/msgraph/webhook` path | +| Jobs do not appear in `hermes teams-pipeline list` | Confirm `msgraph_webhook` is enabled and that subscriptions point at the right notification URL | +| Transcript-first never succeeds | Check Graph permissions for transcript resources and whether the transcript artifact exists for that meeting | +| Recording fallback fails | Confirm `ffmpeg` is installed and the Graph app can access recording artifacts | +| Teams summary delivery fails | Re-check `delivery_mode`, target IDs, and Teams auth config | + +## Related Docs + +- [Microsoft Teams bot setup](/docs/user-guide/messaging/teams) +- [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline) diff --git a/website/docs/user-guide/messaging/teams.md b/website/docs/user-guide/messaging/teams.md index d37c9704cd..ee90fec3bb 100644 --- a/website/docs/user-guide/messaging/teams.md +++ b/website/docs/user-guide/messaging/teams.md @@ -8,6 +8,8 @@ description: "Set up Hermes Agent as a Microsoft Teams bot" Connect Hermes Agent to Microsoft Teams as a bot. Unlike Slack's Socket Mode, Teams delivers messages by calling a **public HTTPS webhook**, so your instance needs a publicly reachable endpoint — either a dev tunnel (local dev) or a real domain (production). +Need meeting summaries from Microsoft Graph events rather than normal bot conversations? Use the dedicated setup page: [Teams Meetings](/docs/user-guide/messaging/teams-meetings). + ## How the Bot Responds | Context | Behavior | @@ -243,3 +245,8 @@ Treat `TEAMS_CLIENT_SECRET` like a password — rotate it periodically via the A - Store credentials in `~/.hermes/.env` with permissions `600` (`chmod 600 ~/.hermes/.env`) - The bot only accepts messages from users in `TEAMS_ALLOWED_USERS`; unauthorized messages are silently dropped - Your public endpoint (`/api/messages`) is authenticated by the Teams Bot Framework — requests without valid JWTs are rejected + +## Related Docs + +- [Teams Meetings](/docs/user-guide/messaging/teams-meetings) +- [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline)