Connect Microsoft Teams

Dexter gives each incident its own Teams channel and posts the investigation there as it happens:

  • a status card that updates live

  • the questions it is investigating, and their answers

  • the decisions it needs from a person

  • the root cause analysis

People reply in the thread, click the cards, or @mention Dexter to open a new incident.

Prerequisites

  • Dexter installed and served on your own domain. See Serve Dexter on your domain.

    Microsoft delivers Teams messages to https://<HOST>/teams/messages, so Dexter must be reachable from the internet over HTTPS. A port-forward is not enough.

  • A Dexter admin account.

  • Permission to register an application in the Microsoft Entra tenant that your Teams organization lives in, and an Azure subscription to hold the Azure Bot resource.

    Before you create anything in a Microsoft portal, check the account and directory shown in its account menu: the portals reuse a cached session even when you pick a different account at sign-in.

  • A team in Microsoft Teams that you own. Only a team owner can grant Dexter the permissions it asks for when the app is added.

  • Custom app upload allowed in your Teams tenant, or a Teams admin who can publish the app to your organization’s app catalog.

Step 1: Register the bot

Dexter appears in Teams as a bot. The bot is an Azure resource that points Teams at Dexter, backed by an Entra app registration that holds the credential.

  1. In the Azure portal, create an Azure Bot resource (Create a resource > Azure Bot):

    • Bot handle: dexter, or any name.

    • Pricing tier: Free (F0) is enough.

    • Type of App: Single Tenant.

    • Creation type: Create new Microsoft App ID. The portal registers the Entra app for you, in the directory you are signed in to.

  2. Open the new bot and go to Settings > Configuration:

    • Set Messaging endpoint to https://<HOST>/teams/messages and apply.

    • Copy the Microsoft App ID. This is the bot ID that Dexter asks for.

    • Click Manage Password next to the App ID. It opens the app registration’s Certificates & secrets page. Add a New client secret and copy its Value right away; it is shown only once.

  3. Go to Settings > Channels, add Microsoft Teams, accept the terms, and apply. Without this channel, Teams never delivers anything to the bot.

The app registration must live in the same Entra tenant as your Teams organization. A bot whose app is registered elsewhere installs normally but can never post.

If your Azure subscription belongs to a different tenant:

  1. In the Teams tenant, register the app under Microsoft Entra ID > App registrations > New registration, single tenant.

  2. Create the Azure Bot with Creation type set to Use existing app registration.

  3. Enter that app ID and the Teams tenant ID.

Without an Azure subscription, the Teams Developer Portal registers the same kind of bot, in the directory you are signed in to.

  1. Under Tools > Bot management, create a bot.

  2. Set its Endpoint address to https://<HOST>/teams/messages.

  3. Add a client secret under Client secrets.

The bot ID it shows is the app ID that Dexter needs.

Step 2: Save the credentials in Dexter

  1. Sign in to Dexter as an admin and open Admin > Integrations.

  2. Under Incident channels, expand Microsoft Teams.

  3. In step 1 on the card, Register the bot, paste the Microsoft App ID as the Bot / app ID and the client secret as the Client secret, then click Save.

The step reads Credentials stored. To rotate the secret later, paste a new one and click Save new secret. Dexter does not ask for the tenant or team: it learns them in the next step.

Step 3: Add Dexter to a team

Teams has no "Add to Teams" button. Dexter generates an app package instead: a zip that names your bot and lists the permissions Dexter needs on the team.

  1. In step 2 on the card, Add it to a team, click Download app package.

    Download it from https://<HOST>, not through a port-forward: the package embeds the address it was downloaded from, and Teams rejects a plain-HTTP address.

  2. In Microsoft Teams, open Apps > Manage your apps > Upload an app > Upload a custom app and choose dexter-teams.zip.

  3. As a team owner, click Add.

  4. When Teams asks Or choose a place to use the app, pick a channel of the team you want incidents in (for example General), and click Go.

    Dexter is added to that team and posts a Connection check card in the channel. Click Confirm connection on it.

    An install by a member who is not an owner grants Dexter no permissions.

Within a few seconds, step 2 on the card names the team. If it still reads Waiting for the install, @mention Dexter in any channel of the team.

If Add opens a personal chat with Dexter instead of asking where to use the app, Teams installed it only for you, and step 2 on the card reads Added for one person only. A package downloaded from a Dexter build released before November 13, 2026 does this: the new Teams client offers no Add to a team option for it.

Remove the personal install under Apps > Manage your apps (expand the app, then delete Personal app), update Dexter, download the package again, and repeat this step.

Teams rejects a package downloaded from a Dexter build released before November 13, 2026 with:

Schema validation failed at 'composeExtensions[0].commands[1].parameters[0].isRequired'

The package declares a manifest property that its schema version does not define. Update Dexter, restart it so it runs the current image, then download the package again.

Each new incident gets its own #inc-… channel in that team.

Dexter also creates a dexter-incidents channel at install, or adopts one of that name, and uses it when it cannot create an incident channel.

To check the connection, click Send test message on the card. Dexter creates or reuses #inc-test-dexter and posts a card there; click Confirm on it in Teams.

If custom app upload is turned off in your tenant, a Teams admin can publish the package instead.

In the Teams admin center, under Teams apps > Manage apps, click Upload new app and choose the zip. A team owner then adds it to the team from Built for your org in the Teams app store.