Table of Contents

Diagnostic Bot

The diagnostic bot is a standalone Microsoft Teams diagnostics bot for the Reignite control plane. It owns the Teams-facing surface only:

  • the Bot Framework activity endpoint (POST /api/teams/bot),
  • intent routing and adaptive-card rendering,
  • the Teams app package,
  • the bot host (ASP.NET Core).

The diagnostics control plane itself lives in the api repository. The bot queries it read-only and asks it to start a diagnosis; it never issues destructive commands.

Request path

sequenceDiagram
  autonumber
  participant User as Teams user
  participant BF as Bot Framework
  participant Bot as Diagnostic Bot
  participant API as Reignite API
  participant SQL as Azure SQL Server
  User->>BF: "What is the status of app X?"
  BF->>Bot: POST /api/teams/bot (JWT)
  Bot->>Bot: Validate JWT and route the intent
  Bot->>API: GET /api/diagnostics/control-plane/*
  API->>SQL: Read control-plane state
  API-->>Bot: Status JSON
  Bot->>BF: POST /v3/conversations/{id}/activities
  BF-->>User: Adaptive card

The generated diagnostic bot request flow is the canonical version of this diagram.

Reply delivery

POST /api/teams/bot acknowledges every accepted activity with an empty 200. The reply is not in the HTTP body. BotConnectorReplyDispatcher posts it to:

{serviceUrl}/v3/conversations/{conversationId}/activities

using an OAuth2 client-credentials token minted from TeamsBot:BotAppId and TeamsBot:BotAppPassword. The token provider caches the token and refreshes it five minutes before expiry.

A connector failure is logged and not rethrown. A non-2xx response would make Bot Framework replay the activity and start a duplicate diagnosis.

Control-plane selection

DiagnosticsControlPlane:BaseUrl selects where the data comes from:

  • Set → HttpDiagnosticsControlPlane and HttpDiagnoseWithChatClient call the API deployment (api/diagnostics/control-plane/*).
  • Blank → an in-memory, feedable stub is used, so a local run is self-contained.

A control-plane failure is rendered as an "unavailable" card with the underlying message, never as a 500 back to Teams.

Configuration

Setting Meaning
TeamsBot:TenantId Entra tenant id; also selects the token authority (blank = multi-tenant botframework.com).
TeamsBot:BotAppId Azure Bot / app registration id; also the Teams botId and the inbound-token audience. Required — startup fails without it.
TeamsBot:BotAppPassword Client secret used to post replies through the Bot Connector.
TeamsBot:BotTokenEndpoint Optional OAuth2 token-endpoint override.
TeamsBot:BotTokenMetadataAddress Optional OpenID metadata override.
TeamsBot:BotTokenIssuer Optional accepted-issuer override.
TeamsBot:DiagnoseEnabled When false, the diagnose action returns a disabled notice.
TeamsBot:MaxListItems Caps the rows rendered per card.
DiagnosticsControlPlane:BaseUrl API base URL; blank uses the in-memory stub.
DiagnosticsControlPlane:ApiToken Bearer token presented to the control plane.
DiagnosticsControlPlane:RequestTimeoutSeconds Per-request timeout (default 30).

Install into Teams

  1. Azure Bot resource — create an Azure Bot (single- or multi-tenant) and set its messaging endpoint to https://<bot-host>/api/teams/bot.

  2. App registration — record the Microsoft App ID, put it in TeamsBot:BotAppId, and use the same GUID as botId in the Teams manifest.

  3. Build the app package — from appPackage/:

    ./build-app-package.ps1 -BotAppId <app-id> -OutputDir ./dist
    

    This renders manifest.json from manifest.template.json and zips it with the icons.

  4. Publish the app — upload dist/diagnostic-bot.zip in the Teams admin center (Teams apps → Manage apps → Upload new app), then install it for the intended users, or sideload it for testing.

The generated diagnostic bot installation flow shows the operator path.

Production checklist

Piece Where it comes from
TeamsBot:BotAppId / TeamsBot:BotAppPassword The Azure Bot's app registration.
DiagnosticsControlPlane:BaseUrl / ApiToken The bot host and the API deployment must agree on the token.
Messaging endpoint https://<bot-host>/api/teams/bot The Azure Bot resource.

Common failures

Symptom Cause and fix
Connector reply returns 401 The token authority does not match the Azure Bot's msaAppType (tenant vs multi-tenant). Check TeamsBot:TenantId, BotTokenEndpoint and the app registration.
Connector reply returns 400 MissingProperty The reply activity has no Activity.From. Bot Framework requires the sender identity; build the outbound activity with From populated.
The bot refuses to start PublicListing=true on a tenant-scoped bot, or TeamsBot:BotAppId is blank. A blank BotAppId is deliberately fatal.
The card says "unavailable" The control plane returned an error. Check DiagnosticsControlPlane:BaseUrl, the Bearer token and the API's health.
Teams does not deliver the message The messaging endpoint is wrong, JWT validation rejects the token, or the app is not installed for the user.