Microsoft Teams Notifications — Setup Guide

Overview

Orcha can send document processing notifications to Microsoft Teams channels. This works through a bot that Orcha operates — when a document is processed, the bot posts an Adaptive Card message to your chosen Teams channel.

How it works (high-level)

There are two accounts / roles involved:

1. Your organization's Microsoft 365 admin — grants Orcha permission to interact with your Teams (one-time setup)
2. A team member — installs the Orcha bot into a specific Teams team and picks which channel receives notifications

These can be the same person if the admin is also a team member.

What Orcha needs

• Admin consent — your Microsoft 365 admin approves the Orcha app for your organization
• Bot installed in a team — someone adds the Orcha bot to a Teams team
• Channel selected — in Orcha's UI, you pick which channel in that team gets notifications

Step-by-step setup

Step 1: Connect Teams in Orcha

1. Log into Orcha
2. Go to the Notifications page (in the sidebar)
3. Scroll to the Microsoft Teams Notifications section
4. Click "Add to Microsoft Teams"

This redirects you to Microsoft's admin consent page.

Step 2: Grant admin consent

Important: You must be a Microsoft 365 admin (Global Admin or Teams Admin) to complete this step. If you're not an admin, ask your IT department to do this.

1. On Microsoft's consent page, sign in with your work account (the Microsoft 365 account for your organization)
2. You'll see a consent screen asking to approve "Orcha" for your organization
3. Review the permissions:
   • Read channel names — so Orcha can show you a list of channels to pick from
   • Send messages to channels — so Orcha can post notifications
4. Click Accept

You'll be redirected back to Orcha. The Teams card should now show: "Waiting for bot installation"

What if I'm not the admin? Share the Orcha Notifications page URL with your admin and ask them to click "Add to Microsoft Teams" and approve. Once they approve, you can continue from Step 3.

Step 3: Install the Orcha bot in your Teams team

After admin consent, you need to install the Orcha bot into a Teams team. This tells Microsoft which team Orcha should connect to.

1. Open Microsoft Teams (desktop app or web at teams.microsoft.com)
2. Sign in with your work account (same organization that granted consent)
3. Go to Apps (in the left sidebar, near the bottom)
4. Find "Orcha" — it should appear under "Built for your org"
   • If you don't see it, try searching for "Orcha" in the search bar
5. Click on the Orcha app card
6. Click "Add"
7. Important: Teams will ask you to choose where to install it. Select "Add to a team" (not personal)
   • If you only see a simple "Add" button, look for a small dropdown arrow next to it
8. Pick the team you want (e.g., "Finance", "Accounting")
9. Select a channel within that team and confirm

Don't see "Built for your org"? Your admin may need to upload the Orcha app package first. Contact Orcha support for the app package file.

Can't find "Add to a team"? If Orcha was added as a "Personal app" by mistake, go to Manage your apps (in the Apps section), delete it, and start again from step 3. Make sure to select "Add to a team" when prompted.

Step 4: Select a channel in Orcha

1. Go back to the Notifications page in Orcha
2. Refresh the page
3. The Teams card should now show your team name (e.g., "Finance Team")
4. A channel dropdown appears — select the channel where you want notifications (e.g., "General", "Invoices")
5. Click Save / Update

The card should now show as active (green indicator) with the team and channel name.

Step 5: Configure notification routing (optional)

By default, Teams notifications are sent for all document events. To customize which events trigger Teams notifications:

1. On the Notifications page, find the Notification Routing section
2. For each notice type (e.g., "New document received", "Invoice processed"):
   • Add or remove your Teams channel from the routing

Step 6: Test it

Upload a document to the legal entity that has Teams connected. After processing, a notification should appear in your selected Teams channel as an Adaptive Card with the document details.

Troubleshooting

"Waiting for bot installation" — stuck on this screen

The admin consent worked, but the bot hasn't been installed in a team yet. Go to Step 3.

If you already installed the bot but still see this:

• Make sure you installed it in a team, not as a personal app
• Check that you're signed into Teams with the same organization that granted consent
• Try uninstalling and reinstalling the bot (Team settings > Apps > remove Orcha, then re-add)

"Something went wrong" when uploading the app

The app package may already be in your org's catalog. Instead of uploading again:

1. Go to Apps > Built for your org
2. Find Orcha there and click Add

Channel dropdown is empty

The bot needs permissions to list channels. Contact Orcha support — the app registration may need updated API permissions.

Notifications not appearing in Teams

• Verify the channel status shows as "active" (green) in Orcha
• Check that the notification routing includes the Teams channel for the event type you're expecting
• Confirm the document belongs to the legal entity that has Teams configured

I accidentally added it as a personal app

1. Go to Apps > Manage your apps in Teams
2. Find Orcha and delete/remove it
3. Then go to Apps > Built for your org > click Orcha > Add to a team

For developers / technical context

Architecture

Orcha App ──── (Bot Framework API) ───── Microsoft Teams
    │                                         │
    ├── Admin consent (OAuth)                 │
    ├── Bot webhook (receives events)         │
    ├── Graph API (list channels)             │
    └── Bot Framework (send messages) ────────┘

Two Microsoft tenants involved

1. Orcha's Azure tenant (818432d6-...) — owns the Azure Bot and App Registration. This is where the bot credentials live.
2. Customer's Microsoft 365 tenant — the customer's organization. Admin consent grants Orcha's app access to this tenant. The bot is installed in a team within this tenant.

Token types

The bot token uses Orcha's own tenant ID (single-tenant bot auth). The Graph token uses the customer's tenant ID (to access their team's channels).

Webhook flow

When the bot is installed in a Teams team, Microsoft sends a conversationUpdate webhook to Orcha's endpoint (/webhooks/teams). This webhook includes:

• The Microsoft tenant ID
• The team ID and name
• The Bot Framework service URL (region-specific)
• A JWT signed by Bot Framework (verified by Orcha)

Orcha matches this to pending notification channels by Microsoft tenant ID and updates them with the team info.

Multi-tenant considerations

• Multiple Orcha legal entities can connect to the same Microsoft tenant
• Each legal entity independently selects which channel to receive notifications in
• When the bot is installed in a team, ALL pending connections for that Microsoft tenant get updated
• Notification sending is scoped per legal entity — legal entity A's notifications never go to legal entity B's channels

Azure App Registration requirements

See teams-integration.md for complete technical reference including database schema, all endpoints, config values, and SSM parameters.