Connect Microsoft Teams

Dexter posts each investigation into a Teams channel as it happens: a status card that updates live, the hypotheses it is testing, the questions it needs answered, and the root cause analysis. People reply in the thread, click the cards, or @mention Dexter to open a new incident. One Microsoft Entra app registration is the whole credential: Dexter uses it both to talk to Teams and to create channels.

In This Topic

Prerequisites

  • Dexter installed and served on your own domain with sign-in required (steps 5 and 6 of Install Dexter). 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, and the channel incidents should go to. 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.

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. Users never see it.

    • 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. Dexter requests its tokens from that tenant, so a bot whose app is registered elsewhere installs normally but can never post. If your Azure subscription belongs to a different tenant, register the app in the Teams tenant first (Microsoft Entra ID > App registrations > New registration, single tenant), then create the Azure Bot with Creation type set to Use existing app registration, and 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: under Tools > Bot management, create a bot, set its Endpoint address to https://<HOST>/teams/messages, and add a client secret under Client secrets. The bot ID it shows is the app ID that Dexter needs.

2. Save the credentials in Dexter

  1. Sign in to Dexter as an admin and open Settings > Connections.

  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. Dexter keeps the secret on its persistent volume and never shows it again; to rotate it, paste a new one and click Save new secret. Dexter does not ask for the tenant, team, or channel: it learns them in the next step.

3. Add Dexter to a channel

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. A team owner uploads it and adds it to the channel incidents should go to.

  1. In step 2 on the card, Add it to a channel, 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 package that names a plain-HTTP address.

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

  3. Click the arrow next to Add and choose Add to a team, then pick the team and confirm. Plain Add installs Dexter only for you personally, which tells Dexter nothing about a team. Do this as a team owner: adding the app to the team is what grants Dexter its permissions there, and an ordinary member’s install grants nothing.

Dexter then creates its own channel in that team, dexter-incidents, and posts investigations there. If a channel of that name already exists it is adopted rather than duplicated. Back in Dexter, step 2 on the card names the team and the channel within a few seconds. If it still reads Waiting for the install, post a message in the team that @mentions Dexter; any message from a channel teaches Dexter where it lives.

Dexter can only create the channel once the team install has granted it permission. When it cannot, it falls back to the channel the app was added to and the card says why.

To move incidents elsewhere later, use Change on the card to pick another channel in the team or to create a fresh Dexter-managed one. There is no need to disconnect or re-install. Incidents already running keep the channel they were opened in.
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. The app then appears under Built for your org in the Teams app store, and a team owner adds it to the team from there.

4. Route incidents to Teams

Dexter posts new incidents to one place at a time.

  1. At the top of Incident channels, under Post incidents to, select Teams. The option becomes available once the install from step 3 is known.

  2. On the Microsoft Teams card, under Where incidents live, choose how each incident gets its space:

    • A thread in the channel (default): one post per incident in the channel you added Dexter to; replies form the incident thread. This needs no further permission.

    • A channel per incident: Dexter creates an inc-… channel in the team for each incident, as it does in Slack. This becomes available once a team owner has added the app to the team (step 3). The package asks the team for permission to create channels and to read its own grants, and Dexter confirms the grant itself rather than asking you to tick a box. No tenant admin is involved. Until the grant is confirmed, Dexter uses threads.

Verify

The two halves of the connection fail independently: Dexter posting to Teams, and Teams reaching Dexter. Check both at once with Send test message on the Microsoft Teams card. Dexter posts a card to the channel; click Confirm connection on it in Teams, and the card in Dexter changes to Last verified, naming who confirmed it and when. Until someone clicks, it reads as waiting rather than connected.

Use the same button after anything that moves Dexter, such as a new host or address. A stale messaging endpoint lets cards keep posting while clicks and @mentions silently stop working, and this is what catches it.

Then, in the channel, post @Dexter followed by a one-line description of a problem. Dexter replies with a Start investigation button. Clicking it opens the incident and binds it to that thread.

Working with Dexter in Teams

  • Open an incident from Teams. @mention Dexter with a description of the problem. Dexter offers Start investigation; the incident is then bound to that thread, and every later card lands there whatever the routing setting says. An @mention with a question about your telemetry gets an answer in the thread instead.

  • Follow along. The status card re-renders as hypotheses are tested. Hypotheses and the root cause analysis arrive as their own cards in the thread.

  • Answer Dexter’s questions. When an investigation needs a human decision, Dexter posts the question with numbered options into the thread. Reply with the option number or its text. Other replies are treated as discussion, not as an answer.

  • Act from the cards. The buttons on the cards act with the Dexter role of the person who clicks. Dexter matches people by the email address on their Teams profile, so sign in to Dexter with the same address.

Troubleshooting

  • Step 2 stays on "Waiting for the install". Either the app was added with plain Add, which installs it only for you (remove that personal app and use Add to a team), or Teams cannot reach Dexter. Check that the bot’s messaging endpoint is exactly https://<HOST>/teams/messages, that the Microsoft Teams channel is added on the bot, and that the address answers from the internet:

    curl -i -X POST https://<HOST>/teams/messages -H 'Content-Type: application/json' -d '{}'

    401 Unauthorized is the expected answer: the endpoint is reachable and refuses an unsigned request. A connection error or 404 means the endpoint is wrong or not public.

  • "A channel per incident" stays unavailable. Dexter could not confirm the team-level grant. Most often the installed package is older than the Dexter version you run and does not ask for permission to read its own grants. Download the app package again and upload it over the existing app in Teams, accepting the update as a team owner. Otherwise the app was added by someone who is not a team owner, or with a package that Dexter did not generate: remove it from the team and add it again as an owner, using a package downloaded from Dexter. If you cannot update the package, a tenant admin can instead grant the app the Microsoft Graph application permission ResourceSpecificPermissionGrant.ReadForTeam.All.

  • The card shows the team and channel, but nothing is posted. The app registration is in a different Entra tenant from your Teams organization (step 1), and Dexter’s log shows AADSTS7000229. Register the app in the Teams tenant, save the new app ID and secret in Dexter, and add the newly generated package to the team.

  • Cards post, but clicks and @mentions get no response. Dexter can reach Teams, but Teams cannot reach Dexter, which is what happens after Dexter moves to a new host. Send test message on the card confirms it: the card arrives, and clicking Confirm connection changes nothing in Dexter. Update the messaging endpoint on the bot, then download the app package again from the new host and upload it over the existing app in Teams.

  • Investigations post in the wrong channel. Use Change on the Microsoft Teams card to pick another channel in the team, or to create a Dexter-managed one. Incidents already open keep the channel they started in.