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 →
HttpDiagnosticsControlPlaneandHttpDiagnoseWithChatClientcall 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
Azure Bot resource — create an Azure Bot (single- or multi-tenant) and set its messaging endpoint to
https://<bot-host>/api/teams/bot.App registration — record the Microsoft App ID, put it in
TeamsBot:BotAppId, and use the same GUID asbotIdin the Teams manifest.Build the app package — from
appPackage/:./build-app-package.ps1 -BotAppId <app-id> -OutputDir ./distThis renders
manifest.jsonfrommanifest.template.jsonand zips it with the icons.Publish the app — upload
dist/diagnostic-bot.zipin 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. |