teams-agent-gateway¶
Status: Current | Last reviewed: 2026-06-16
Receives Microsoft Teams Bot Framework activities for per-agent Teams custom apps and bridges personal chat messages into TrueServe text conversations.
Source¶
Runtime¶
| Aspect | Value |
|---|---|
| Language | TypeScript (Node) |
| Port | 3521 in local dev; Helm sets 3520 explicitly |
| Wire | HTTP POST /teams/agents/{teamsConfigId}/messages |
What it does¶
- Validates Bot Framework requests using the configured per-agent bot app ID and client secret.
- Rejects disabled configs, non-Teams activities, non-
personalTeams scopes, wrong Microsoft tenants, attachments, and empty text. - Creates or reuses
teams_conversation_linksto map a Teams 1:1 conversation to a TrueServe conversation. - Calls
conversation-apiwith the shared surface-internal HMAC stamp; Teams app packages never contain TrueServe API tokens. - Sends a Teams typing indicator and one final text reply.
Provisioning lifecycle¶
Teams package upload is not the first step. The Microsoft bot/app registration must exist before TrueServe can generate a valid app package, because the Teams manifest needs the bot app/client ID.
- Microsoft admin creates a Teams conversation bot or Azure Bot registration.
- Admin gives the TrueServe tenant admin the Microsoft tenant ID, bot app/client ID, and client secret.
- Tenant admin enables Teams on the TrueServe agent and saves those values.
- ai-manager generates
POST /teams/agents/{teamsConfigId}/messagesusingTEAMS_AGENT_GATEWAY_PUBLIC_URL. - Admin configures that URL as the Microsoft bot resource messaging endpoint.
- Tenant admin downloads the Teams package from TrueServe.
- User or admin uploads/publishes the Teams package, depending on Teams custom app policy.
Dependencies¶
| Service | Purpose |
|---|---|
| Postgres | Teams config, integration secrets, conversation links |
| conversation-api | Text conversation creation, message posting, SSE turn collection |
| Microsoft Bot Framework | Request validation and Teams replies |
Environment¶
| Var | Required | Purpose |
|---|---|---|
FEATURE_TEAMS / NEXT_PUBLIC_FEATURE_TEAMS |
yes | Deployment flag. Default false; set FEATURE_TEAMS=true to accept callbacks and set NEXT_PUBLIC_FEATURE_TEAMS=true in ai-manager to show the Settings panel |
TEAMS_AGENT_GATEWAY_PORT |
no | HTTP port, local default 3521; Helm sets 3520 explicitly |
TEAMS_AGENT_GATEWAY_PUBLIC_URL |
yes for packages | Public HTTPS base used by ai-manager to render Teams messaging endpoints |
CONVERSATION_API_URL |
yes | Internal conversation-api HTTP URL |
SURFACE_INTERNAL_HMAC_SECRET |
yes | Shared HMAC secret for conversation-api calls |
MASTER_ENCRYPTION_KEY |
yes | Decrypts bot client secrets from integration_secrets |
TEAMS_ASSISTANT_TIMEOUT_MS |
no | Max wait for final assistant text, default 45000 |
Vanguard¶
overmind restart teams-agent-gateway
overmind connect teams-agent-gateway
The local start script idles unless FEATURE_TEAMS=true or NEXT_PUBLIC_FEATURE_TEAMS=true is present in .env.local, so Overmind stays healthy without exposing Teams in environments that have not opted in.
For Microsoft 365 smoke tests, point TEAMS_AGENT_GATEWAY_PUBLIC_URL at an HTTPS tunnel and paste the per-agent messaging endpoint from ai-manager into the Azure Bot registration.
Production¶
Helm chart at charts/teams-agent-gateway is disabled by default (replicaCount: 0, no Service, FEATURE_TEAMS=false). Expose it publicly over HTTPS only in environments that opt into Teams app packages and Microsoft Bot Framework callbacks.