Teams became Hermes's 20th messaging platform in the Foundation Release. The integration is real. The setup is also real. Here's every step, every gotcha, and an honest assessment of whether it's worth your afternoon.
An IT manager in our community spent his entire Tuesday afternoon trying to get Hermes Agent working in Microsoft Teams. He had Azure experience. He'd set up Bot Framework apps before. He knew his way around Graph API permissions.
It still took him nearly two hours. The Azure app registration went smoothly. The bot framework webhook was straightforward. But the part where Hermes's gateway actually processes Teams messages and delivers responses back through the Graph API? Three separate config files. A tunnel requirement (Teams can't deliver to localhost). An allowlist that silently drops messages from unregistered users with no error message.
"The bot was receiving my messages. Hermes was processing them. The response just... disappeared."
His TEAMS_ALLOWED_USERS list was missing his AAD object ID. No log entry. No error. Just silence.
That's the Hermes Agent Microsoft Teams integration in a nutshell. It works. It works well once configured. Getting there requires Azure expertise, patience, and this guide.
What the Teams integration actually includes
Hermes v0.14.0 shipped the full Microsoft Teams stack via PR #13767. It's not a basic webhook. It's a proper enterprise integration with four components:
Microsoft Graph authentication. Azure AD app registration with client credentials for the Bot Framework and Graph API.
Webhook listener. An HTTP endpoint (default port 3978) that receives Teams events. Requires a public HTTPS URL, which means a tunnel for local dev.
Pipeline runtime. Hermes processes incoming Teams messages through the same agent loop as Telegram, Discord, and Slack.
Outbound delivery. Responses go back through the Graph API, supporting text, file attachments, and image uploads.
This is genuine end-to-end support. Not a third-party bridge. Not a Composio wrapper. Native.
Step 1: Register the bot (the quick way)
The official Hermes docs recommend the Teams CLI approach, which skips the Azure portal entirely:
npm install -g @microsoft/teams.cli@preview
teams login
Verify your login and find your AAD object ID:
teams auth show
Save that object ID. You'll need it for the allowlist.
Create the bot registration:
teams app create --name "Hermes Agent" \
--endpoint https://your-tunnel-url/api/messages \
--env ~/.hermes/.env
This command handles AAD app registration, client secret generation, manifest creation, and bot setup in one step. It writes TEAMS_APP_ID, TEAMS_APP_PASSWORD, and TEAMS_BOT_ID to your .env file.
The alternative (Azure portal): If you can't use the CLI (restricted environments, older Node versions), you'll need to manually create an Azure AD app registration, generate a client secret, configure redirect URIs, and note the Client ID and Tenant ID. This takes 15 to 20 minutes with Azure experience. Longer without.
For a comparison of how authentication works across different agent frameworks, our Hermes auth error troubleshooting guide covers the six most common authentication failures.
Step 2: Set up the tunnel (Teams can't reach localhost)
Here's where most people waste time. Teams cannot deliver messages to localhost. You need a public HTTPS URL pointing to your Hermes webhook port.
Three options:
Microsoft Dev Tunnel (recommended for enterprise):
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol https
devtunnel host hermes-bot
ngrok:
ngrok http 3978
Cloudflare Tunnel:
cloudflared tunnel --url http://localhost:3978
Copy the https:// URL from whichever tool you use. Update your bot's messaging endpoint to https://your-tunnel-url/api/messages. Leave the tunnel running.
For production: You can't rely on a development tunnel. You need Hermes running on a server with a stable public URL, HTTPS certificate, and proper DNS. This is where the self-hosting overhead compounds. A development tunnel for testing is one thing. Maintaining a production endpoint for your enterprise Teams bot is another.
Step 3: Configure Hermes for Teams
Add the Teams credentials to your .hermes/.env file:
# Microsoft Teams Bot Framework
TEAMS_APP_ID=your-app-id
TEAMS_APP_PASSWORD=your-client-secret
TEAMS_TENANT_ID=your-tenant-id
TEAMS_BOT_ID=your-bot-id
# Security: only accept messages from these AAD users
TEAMS_ALLOWED_USERS=your-aad-object-id,colleague-aad-id
# Optional: custom port (default 3978)
TEAMS_PORT=3978
Lock down the file permissions:
chmod 600 ~/.hermes/.env
Then enable Teams in the gateway:
hermes gateway setup
# Select Microsoft Teams when prompted
Start the gateway:
hermes gateway run
If the gateway starts without errors, your Teams bot should be listening. But there's a critical security detail.
The silent drop problem (the bug nobody warns you about)
TEAMS_ALLOWED_USERS is not optional. If a user's AAD object ID isn't in that list, their messages are silently dropped. No error in Teams. No log entry in Hermes (by default). The user sends a message, sees it delivered, and gets nothing back.
This is by design for security. But it's the #1 reason enterprise IT managers think the integration is broken when it's actually working perfectly... just ignoring everyone who isn't explicitly allowlisted.
How to find a user's AAD object ID:
# Using Teams CLI
teams auth show
# Using Azure CLI
az ad user show --id user@company.com --query id
Add every user who should be able to talk to the agent. Separate with commas. No spaces.
For the full picture of how Hermes handles authentication across providers and platforms, our Hermes Docker installation guide covers containerized setups that simplify credential management.
Step 4: Test the connection
Send a DM to your Hermes bot in Teams. If everything is configured correctly, you should see the message in your Hermes gateway logs and get a response back in Teams.
If the bot doesn't respond, debug in this order:
Check the tunnel is running and the URL is correct. Check the bot messaging endpoint matches your tunnel URL + /api/messages. Check TEAMS_ALLOWED_USERS includes your AAD object ID. Check the gateway logs: tail -f ~/.hermes/logs/gateway.log. Check TEAMS_APP_PASSWORD hasn't expired (Azure secrets have expiry dates).
Common failure: Graph token 401/403 after adding permissions. You added the Graph API permissions in Azure. The token acquires cleanly. But API calls return 401 or 403. The fix: go back to the Azure portal, find your app registration, and click "Grant admin consent" again. Adding permissions without re-granting admin consent is the most common Azure permissions mistake.
If you're evaluating AI agents for enterprise Teams deployment and the Azure configuration complexity feels like the wrong use of your IT team's time, that's a reasonable reaction. BetterClaw connects to Teams with one-click OAuth. No Azure app registrations. No tunnel configuration. No allowlist management. 50+ companies including Carelon, Grainger, and Robert Half run agents on BetterClaw. The enterprise plan includes SSO, audit logs, and a dedicated CSM.
Step 5: Teams Meeting Pipeline (the advanced feature)
v0.14.0 also includes a Teams Meeting Pipeline that can fetch meeting transcripts, generate summaries, and store them. This requires additional Graph API permissions:
hermes teams-pipeline validate
hermes teams-pipeline token-health
If token-health fails, force a refresh:
hermes teams-pipeline token-health --force-refresh
The pipeline uses Graph application permissions (not delegated), which means your Azure admin needs to grant consent at the organization level. This is the step where many enterprise deployments stall because it requires IT admin approval.
Known issue: Webhook subscriptions for meeting events expire. If summaries stop arriving, check subscription status:
hermes teams-pipeline list --status failed
Expired webhooks need to be renewed. The official docs recommend automation for this, but as of v0.14.0, there's no built-in renewal mechanism.
The honest time estimate
Here's what this actually takes:
With Azure experience: 1 to 2 hours for basic bot setup and testing. Add 30 to 60 minutes for the meeting pipeline.
Without Azure experience: 3 to 5 hours minimum. Azure AD concepts, Graph API permissions, and the tunnel requirement will slow you down significantly.
Ongoing maintenance: Secret rotation (Azure secrets expire). Tunnel management (for non-production setups). Allowlist updates (new employees). Webhook renewal (meeting pipeline). Gateway monitoring.
Compare this to adding Teams on a managed platform: connect OAuth, authorize, done. 60 seconds. No Azure portal. No tunnel. No allowlist.
The real question for enterprise IT: Is the configuration time and ongoing maintenance worth it for the control that self-hosting gives you? For some organizations, yes. For organizations that want AI agents working in Teams this week, not next month, managed deployment is faster by an order of magnitude.
For the broader comparison of how different AI agent platforms handle enterprise integrations, our guide on the best AI agent builders covers Teams support across all major platforms.
What this means for enterprise AI agent adoption
Microsoft Teams is where 320+ million monthly active users do their work. Having an AI agent in Teams isn't a nice-to-have for enterprises. It's the difference between an agent that gets used and an agent that gets forgotten in a Telegram channel nobody checks.
Hermes getting native Teams support is significant. It means the open-source agent space is maturing toward enterprise readiness. But "enterprise-ready" isn't just about platform support. It's about how quickly you can deploy, how much maintenance it requires, and whether your IT team is spending time on Azure configurations or on actual agent workflows.
If your organization is exploring AI agents for Microsoft Teams but not sure where to start, we offer a free AI readiness audit. We identify the highest-impact use cases for your specific operations, share a clear proposal, and if it makes sense, implement it for you on the BetterClaw platform. No commitment required to get the audit. 50+ companies have gone through this process, and the first agent is typically live within a week of approval.
Frequently Asked Questions
Does Hermes Agent work with Microsoft Teams?
Yes. Hermes v0.14.0 (released May 16, 2026) added native Microsoft Teams support as its 20th messaging platform. The integration includes Microsoft Graph authentication, webhook-based message ingestion, the standard Hermes agent pipeline, and outbound delivery via Graph API. Setup requires an Azure AD app registration, a public HTTPS endpoint (tunnel for development), and explicit user allowlisting.
How long does it take to set up Hermes Agent with Microsoft Teams?
With Azure experience, expect 1 to 2 hours for basic bot setup and testing. Without Azure experience, plan for 3 to 5 hours. The Teams CLI (@microsoft/teams.cli) simplifies bot registration, but you still need a tunnel, credential configuration, and user allowlisting. The meeting pipeline adds another 30 to 60 minutes. BetterClaw's Teams integration takes about 60 seconds via one-click OAuth.
Why doesn't my Hermes Teams bot respond to messages?
The most common cause is the TEAMS_ALLOWED_USERS list. Hermes silently drops messages from users whose AAD object ID isn't in the allowlist. No error appears in Teams or in the default Hermes logs. Find your AAD object ID with teams auth show or az ad user show, then add it to TEAMS_ALLOWED_USERS in your .env file. Other common causes: tunnel not running, messaging endpoint URL mismatch, and Azure Graph permissions added without admin consent being re-granted.
How much does running Hermes Agent with Teams cost?
Hermes Agent is free (MIT license). But the Teams integration requires: a server with a public HTTPS endpoint ($10 to $50/month VPS), a tunnel tool for development, Azure AD (included with Microsoft 365 business plans), and your LLM API costs. Ongoing maintenance includes secret rotation, allowlist management, and webhook renewal. BetterClaw's free tier includes Teams support at $0/month. Pro is $19/agent/month. Enterprise pricing is custom with SSO and audit logs.
Is Hermes Agent secure enough for enterprise Microsoft Teams?
Hermes includes TEAMS_ALLOWED_USERS for message filtering and stores credentials in .env with recommended 600 permissions. However, CrowdStrike published a security advisory on OpenClaw enterprise risks, and the recent "Claw Chain" vulnerabilities (May 2026, 245,000 exposed servers) affected the broader ecosystem. For enterprise deployments, BetterClaw offers isolated Docker containers per agent, secrets auto-purge after 5 minutes (AES-256), verified skills with 4-layer security audit, and SOC-2 aligned security practices. Companies like Carelon, Grainger, and Robert Half use BetterClaw in production.
