Microsoft Teams Bots

Connect your Gravity Rail agents to Microsoft Teams. Respond to @mentions, interact via DMs, and surface workflows in channels and group chats — using the same agent + commands model as the Slack integration.

Quick start

1. Get the Microsoft App ID and Microsoft App Password

These two values are the bot's identity. Both come from the same Microsoft Entra (Azure AD) app registration — the App ID is the registration's GUID, the App Password is a client secret you generate under it.

1. Go to Azure portal → Microsoft Entra ID → App registrations → + New registration.
2. Name it (e.g. "Gravity Rail Bot — <workspace-name>").
3. Under Supported account types, choose Accounts in this organizational directory only (Single tenant).
   • Why: multi-tenant Bot Framework registrations were deprecated 2025-07-31. New bots must be single-tenant; cross-tenant reach is achieved later via Teams Store publication, not via the Entra app's tenancy.
4. Leave Redirect URI blank — the bot doesn't need one. (The optional SSO Entra app in step 3 is a different registration that does need a redirect URI.)
5. Click Register.
6. On the Overview page that opens, copy Application (client) ID — this is your MicrosoftAppId.
7. In the left nav of the same registration, click Certificates & secrets → Client secrets → + New client secret.
8. Give it a description and choose an expiry (24 months max). Click Add.
9. Copy the Value column immediately and store it in a password manager. Azure shows the secret value once and only once — refreshing the page hides it forever and you'll have to generate a new one. This is your MicrosoftAppPassword.

CLI shortcut. If you'd rather script it: az ad app create --display-name "Gravity Rail Bot" --sign-in-audience AzureADMyOrg returns the App ID, then az ad app credential reset --id <app-id> prints the password. The full sequence including the bot resource is in Microsoft Learn — Provision an Azure Bot resource.

2. Create the Azure Bot resource

The Entra app from step 1 is just the identity. To actually receive Teams messages, that identity has to be wired to an Azure Bot resource that registers it with the Bot Framework.

1. Azure portal → Create a resource → search "Azure Bot" → Create.

2. Bot handle: any unique name (e.g. gravity-rail-<workspace>).

3. Subscription / Resource group: pick or create.

4. Pricing tier: F0 — free tier, unlimited messages on Microsoft Teams (the standard channel for this integration). The S1 tier only matters for non-Teams channels.

5. Microsoft App ID: choose Use existing app registration and paste the MicrosoftAppId from step 1.6. The app type must match — single-tenant.

6. Click Review + create → Create. Wait for deployment to finish.

7. Open the new bot resource → Settings → Configuration → set Messaging endpoint to:

   https://api.gravityrail.com/api/v2/w/{workspaceUuid}/app-connections/teams/events

   Replace {workspaceUuid} with your Gravity Rail workspace UUID. The exact URL is also shown in the Gravity Rail Teams app detail page after step 4 (Connect tab).

8. Channels blade → click Microsoft Teams → accept the terms → Apply. This is what makes the bot reachable from Teams clients; without it, your messaging endpoint will never receive activities.

3. (Optional) Register an SSO Entra app

Skip this step if your Gravity Rail organization already has Entra OIDC SSO configured (Settings → Authentication → SSO with providerType: azure_ad). The Teams integration auto-resolves member identity through that existing trust boundary — no second Entra app needed.

Set this up only when (a) the org doesn't use Entra SSO, or (b) you want Teams users to link their Gravity Rail account from inside Teams via a "Sign in with Microsoft" Adaptive Card.

1. Azure portal → Microsoft Entra ID → App registrations → + New registration. Distinct registration from step 1 — that one is the bot's identity, this one is for user-side SSO.

2. Name it (e.g. "Gravity Rail Teams SSO — <workspace-name>").

3. Under Supported account types, choose Accounts in any organizational directory (Any Microsoft Entra directory — Multitenant).

4. Under Redirect URI, choose Web and enter:

   https://api.gravityrail.com/api/v2/w/{workspaceUuid}/app-connections/teams/oauth/user/callback

5. Register → on the Overview page, copy Application (client) ID — that's your ssoClientId.

6. Certificates & secrets → + New client secret → copy the Value immediately. That's your ssoClientSecret.

7. API permissions → + Add a permission → Microsoft Graph → Delegated permissions → tick:

   • openid
   • profile
   • email
   • offline_access
   • User.Read

8. Click Add permissions. The permissions list should now show those five entries with green check marks (admin consent isn't required for these — they're user-grantable).

4. Add the Teams app in Gravity Rail

1. In your Gravity Rail workspace, open App Connections → Directory tab.
2. Find the Microsoft Teams card and click Add.
3. In the dialog, fill in:
   • App name: any label (e.g. "Gravity Bot — Production").
   • Agent: the AI agent that will handle bot interactions. Required — the bot is always backed by an agent member.
   • Microsoft App ID: the MicrosoftAppId from step 1.6.
   • Microsoft App Password: the secret value from step 1.9. Stored encrypted at rest with JWE; never shown again in API responses.
   • SSO client id / SSO client secret: only if you registered the optional SSO Entra app in step 3. Leave blank otherwise.
4. Click Create App. The detail page opens. Copy the events endpoint URL it shows and confirm it matches what you set as the Messaging endpoint in step 2.7.

5. Build a Teams app manifest

Create a manifest.json referencing your MicrosoftAppId:

jsonc

Zip manifest.json plus color.png and outline.png together. This is your Teams app package.

6. Distribute the Teams app

Three paths, in increasing reach:

1. Custom upload (sideload) — fastest for design-partner customers. The customer's Teams admin uploads your zip via Teams Admin Center → Manage apps → Upload custom app.
2. Org catalog — admin uploads to their tenant's app catalog and rolls out to selected users.
3. Microsoft Teams Store (AppSource) — required for public/multi-tenant distribution. Submit via Microsoft Partner Center. Initial test report ~24h; full approval can take up to 4 weeks. Note: each manifest update goes through review.

Behavior settings

Same shape as Slack (SlackRespondMode ↔ TeamsRespondMode):

• mentions (default): bot only replies to direct @mentions and personal-scope DMs.
• auto: AI decides whether to respond based on respondWhen prompt.
• off: only manifest commands (and DMs) trigger the bot.

allowDm, replyInThread, and allowedChannelIds mirror their Slack counterparts.

Account linking

Each member of a workspace can link their Microsoft (Entra) identity by clicking Sign in with Microsoft on the Teams app's Connect tab in Gravity Rail. The linkage key is (tenantId, aadObjectId) — tenant-global, so a member's link survives across teams within the tenant.

Notifications and escalation

Phase 1 ships the bot, account linking, and the /events webhook. Workspace notification rules and escalation routing for Teams are part of Phase 2 (the pluggable notification destinations refactor). Until then, Teams interactions remain agent-driven.

PHI / HIPAA

• Adaptive Cards sent to customer M365 tenants default to PHI-minimal: workspace name, workflow name, opaque IDs, and a deeplink back to Gravity Rail. Responders click through into the app where access controls and audit logging apply.
• A workspace-level flag (planned, Phase 2) gates including PHI directly in card bodies for tenants that have explicitly opted in with a signed BAA.
• All Teams installation and account-link events are written to the audit log.

Reference

• API endpoints: see the Teams developer guide.
• CLI: yarn gr teams-apps list/get/create/update/delete/conversations/installations/accounts.
• Bot Framework docs: Send proactive messages, Bot SSO with Entra.