Skip to main content

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.

  1. Open App Connections, add Microsoft Teams, and keep Gravity Rail managed app selected.
  2. Choose an Agent, a Workflow, or both. With both selected, the Workflow runs and the Agent is its assistant identity.
  3. Click Create and approve Sign in with Microsoft. This delegated grant lets Agent and Manager tools browse or post as you in the bound tenant.
  4. An Apps Admin uses Add Gravity Rail to Teams on the connection page to bind inbound routing and install the resident app identity for personal chats, mentions, and Workflow threads.

The delegated member identity ("post as me") and the installed Teams app are separate grants. Their tokens, tenant binding, and routing are local to this Gravity Rail workspace. Tenant policy may require an administrator to approve the requested Microsoft Graph permissions or make the app available in the organization catalog.

Bring your own Teams app​

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
    • Team.ReadBasic.All
    • Channel.ReadBasic.All
    • ChannelMessage.Read.All
    • ChannelMessage.Send
    • Chat.ReadBasic
    • ChatMessage.Read
    • ChatMessage.Send

  8. Click Add permissions. Tenant policy and the broader channel-history permissions may require administrator consent.

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 and/or Workflow: choose either entry point, or both to use the Agent as the Workflow assistant.
    • 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:

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.21/MicrosoftTeams.schema.json",
  "manifestVersion": "1.21",
  "id": "<your-teams-manifest-app-guid>",
  "version": "1.0.0",
  "developer": { "name": "Your Org", "websiteUrl": "https://your-site.example", "privacyUrl": "...", "termsOfUseUrl": "..." },
  "name": { "short": "Gravity Bot", "full": "Gravity Rail Bot" },
  "description": { "short": "AI assistant", "full": "..." },
  "icons": { "color": "color.png", "outline": "outline.png" },
  "bots": [{
    "botId": "<MicrosoftAppId from step 1>",
    "scopes": ["personal", "team", "groupChat"],
    "supportsCalling": false,
    "supportsVideo": false,
    "isNotificationOnly": false,
    "commandLists": [
      {
        "scopes": ["personal", "team", "groupChat"],
        "commands": [
          { "title": "intake", "description": "Start an intake workflow" }
        ]
      }
    ]
  }],
  "permissions": ["identity", "messageTeamMembers"],
  "validDomains": []
}

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​