Microsoft Teams Integration — Reference

Azure App Registration (Entra ID)

Portal URL: https://portal.azure.com → Entra ID → App registrations → "Orcha"

Authentication

For production, add: https://app.getorcha.com/settings/notifications/teams/callback

API Permissions (Microsoft Graph)

Note: Message sending uses Bot Framework API (https://api.botframework.com), not Graph API, so no Graph permission is needed for sending notifications.

Azure Bot Resource

Important: Separate from the App Registration. This is where the messaging endpoint is set.

Portal URL: https://portal.azure.com → search "Azure Bot" or "Bot Services"

When switching between local dev and production, update the messaging endpoint accordingly.

SSM Parameters (AWS Parameter Store)

Local dev values are in scripts/init_aws.clj (lines 71-77). Test values are in test/com/getorcha/test/fixtures.clj.

Config (config.edn)

:teams {:bot-app-id     #orcha/param "/v1-orcha/teams-bot-app-id"
        :bot-app-secret #orcha/param "/v1-orcha/teams-bot-app-secret"
        :bot-tenant-id  "818432d6-b012-47e8-a326-09e010bf22d0"  ;; hardcoded Orcha tenant
        :state-secret   #orcha/param "/v1-orcha/teams-state-secret"}

bot-tenant-id is hardcoded because Bot Framework tokens are always obtained from the app's own tenant, regardless of which customer tenant the bot is installed in.

URLs & Endpoints

Local dev base URL

https://orcha.ngrok.app (configured in config.edn line 20, profile :local-dev)

Production base URL

https://app.getorcha.com

App Routes

Microsoft URLs used by the code

Teams App Manifest

Location: resources/teams-app/manifest.json

To sideload: zip manifest.json + color.png (192x192) + outline.png (32x32) into a .zip.

Database Schema

notification_channel (base table)

notification_channel_teams

Flow Summary

1. User clicks "Add to Microsoft Teams" on /notifications
   → GET /settings/notifications/teams/authorize
   → 302 to https://login.microsoftonline.com/common/adminconsent?...

2. Customer admin grants consent on Microsoft's page
   → Microsoft redirects to /settings/notifications/teams/callback
   → Creates notification_channel (status=pending) + notification_channel_teams (tenant_id only)

3. Customer installs bot in their Teams team (sideload or app store)
   → Microsoft sends POST /webhooks/teams (conversationUpdate)
   → Updates notification_channel_teams with team_id, team_name, service_url, conversation_id

4. User selects a channel on /notifications page
   → GET /settings/notifications/teams/{id}/channels (fetches from Graph API)
   → POST /settings/notifications/teams/{id}/update-channel
   → Updates teams_channel_id, teams_channel_name, sets status=active

5. Notification triggered
   → Bot Framework token obtained from Orcha's tenant
   → Adaptive Card posted to {service_url}/v3/conversations/{channel_id}/activities
   → Message appears in Teams channel

Migrations