Microsoft Teams Channel

Connect Microsoft Teams

Teams runs as an Azure Bot that reuses the same Azure AD app as the Microsoft 365 integration. Install @omadia/integration-microsoft365 first — it owns the app credentials (client id / secret / tenant); this channel only adds Teams-specific knobs.

1. Register the Azure Bot

1. Azure Portal → create an Azure Bot resource.
2. Use the existing app registration from the Microsoft 365 integration (same Microsoft App ID).
3. Configuration → Messaging endpoint: <your-public-base-url>/api/teams/messages.
4. Channels → enable Microsoft Teams.

Multiple bots (optional)

One plugin install can run several Teams bots — one Entra app registration / Azure bot per omadia agent. Configure them as a JSON array in Teams Bots (JSON):

[{"botSlug": "default", "appId": "<entra-app-id>",
  "tenantId": "<entra-tenant-id>",
  "appPasswordSecretRef": "microsoft_app_password",
  "appType": "SingleTenant", "displayName": "Omadia"}]

• appPasswordSecretRef names the vault secret holding that bot's app password — never put the password itself into config.
• appType defaults to SingleTenant (Azure deprecated creating MultiTenant registrations 07/2025); legacy bots may set MultiTenant.
• Each bot's Azure messaging endpoint is <your-public-base-url>/api/teams/<botSlug>/messages. The first entry is the default bot — it also serves the legacy /api/teams/messages and /api/messages endpoints, so existing Azure bot registrations keep working.
• Leave the field empty to keep the classic single-bot setup: the Microsoft 365 integration's app credentials are used as bot default (app type from MICROSOFT_APP_TYPE, default MultiTenant).

2. Upload the Teams app

Upload the Teams app package (manifest.json + icons as a ZIP) in Teams under Apps → Manage your apps → Upload a custom app.

3. Optional knobs

• OAuth Connection Name: if you add a v4 OAuth connection in the Azure Bot Service, put its name here to enable calendar SSO (OBO flow). Empty → calendar tools report sso_unavailable.
• Notify Team ID: the AAD groupId of the team where bell notifications appear — get it via Teams → Team settings → Get link to team (groupId query param) or Graph Explorer (/teams). Empty → log-only.
• Attachment prefix, topic URL and directory label have safe defaults.

4. Auto-invite agent apps (optional Graph consent)

With Agent Apps (JSON) (teams_agent_apps) configured, the channel auto-installs the listed omadia agent apps into a team when one of its bots is added there. That needs two extra Graph application permissions on the shared app registration (admin consent required — note that previously granted consent does not stretch to newly added scopes: re-grant admin consent on the existing registration, otherwise Graph keeps answering 403):

• AppCatalog.ReadWrite.All — resolve the agent app in the tenant app catalog (/appCatalogs/teamsApps)
• TeamsAppInstallation.ReadWriteForTeam.All — install the catalog app into the target team (POST /teams/{team-id}/installedApps)

Grant them under API permissions → Add a permission → Microsoft Graph → Application permissions, then Grant admin consent for <Tenant> — or send an admin through the tenant-wide admin-consent URL (public client id only, never a secret): https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<application-client-id>

Two field-tested gotchas: portal/CLI consent sometimes silently fails to apply (command succeeds, Graph keeps answering 403) — then grant the app roles directly via REST POST /servicePrincipals/{app-sp-object-id}/appRoleAssignments, one call per missing permission. And acquired tokens are cached: restart the middleware after granting consent, or the 403s persist even though consent is in place. Without consent the feature degrades gracefully — the bot posts a fallback card with per-agent install deep links (https://teams.microsoft.com/l/app/<teamsAppId>, public app ids only).