service-teams-browser-bot/README.md

Teams Bot Service

AI-powered Microsoft Teams meeting bot. Joins meetings, captures live transcripts, monitors chat, and responds via voice and/or chat messages.

Architecture

  ┌───────────────┐                                    ┌───────────────────────┐
  │               │         WebSocket                  │                       │
  │    Gateway    │◄──────────────────────────────────►│      Bot Service      │
  │               │  transcripts, status, chat,        │                       │
  │  ● AI engine  │  audioChunks, voiceGreeting        │  Joins Teams meetings │
  │  ● TTS        │                                    │  as a participant     │
  │  ● Sessions   │  playAudio, sendChatMessage,       │                       │
  │  ● Billing    │  stopAudio                         │  Capabilities:        │
  │               │                                    │  ├ Live transcripts   │
  │               │         HTTP                       │  ├ Chat messages      │
  │               │────────────────────────────────────►  ├ Voice playback     │
  └───────────────┘  join, leave, status               │  └ Audio capture      │
                                                       └───────────────────────┘

Path	Protocol	Purpose
Gateway ↔ Bot	WebSocket	Real-time transcript, chat, audio, status exchange
Gateway → Bot	HTTP	Session control (join, leave, status)

Integration Guide

How It Works

1. Gateway sends a POST to the Bot with a meeting URL and optional credentials
2. Bot joins the meeting and appears as a regular participant
3. A WebSocket connection is established for real-time data exchange
4. Bot streams transcript segments and chat messages to the Gateway
5. Gateway can send TTS audio or chat responses back into the meeting

Step 1: Start a Session

POST /api/bot
Content-Type: application/json

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "meetingUrl": "https://teams.microsoft.com/meet/123456789?p=abc123",
  "botName": "AI Assistant",
  "instanceId": "feature-instance-uuid",
  "gatewayWsUrl": "wss://gateway.example.com/api/teamsbot/ws",
  "language": "de-DE",
  "botAccountEmail": "bot@example.com",
  "botAccountPassword": "decrypted-password",
  "transferMode": "caption"
}

Field	Required	Description
sessionId	Yes	Unique session UUID (generated by Gateway)
meetingUrl	Yes	Teams meeting URL (classic or short format)
botName	No	Display name in meeting (default: env BOT_NAME)
instanceId	No	Feature instance ID for Gateway WebSocket path
gatewayWsUrl	No	Gateway WebSocket base URL (default: env GATEWAY_WS_URL)
language	No	BCP-47 language code (default: de-DE)
botAccountEmail	No	Microsoft account for authenticated join
botAccountPassword	No	Decrypted password for authenticated join
transferMode	No	caption or audio

If botAccountEmail + botAccountPassword are provided, the bot joins as an authenticated user. Otherwise, it joins as an anonymous guest.

Response:

{
  "success": true,
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Bot deployment initiated"
}

Step 2: Receive Data via WebSocket

After deployment, the Bot connects to the Gateway at:

wss://{gatewayHost}/api/teamsbot/{instanceId}/bot/ws/{sessionId}

Messages: Bot → Gateway

Transcript segment:

{
  "type": "transcript",
  "sessionId": "...",
  "transcript": {
    "speaker": "Jane Doe",
    "text": "Hey Bot, can you summarize this?",
    "timestamp": "2026-02-18T10:30:00.000Z",
    "isFinal": true
  }
}

Chat message:

{
  "type": "chatMessage",
  "sessionId": "...",
  "chat": {
    "speaker": "Jane Doe",
    "text": "Please summarize the discussion",
    "timestamp": "2026-02-18T10:31:00.000Z"
  }
}

Status update:

{
  "type": "status",
  "sessionId": "...",
  "status": "joined",
  "message": "Bot joined the meeting"
}

Status values: connecting | in_lobby | joined | left | error

Voice greeting request (bot asks Gateway for TTS):

{
  "type": "voiceGreeting",
  "sessionId": "...",
  "text": "Hello, I am ready.",
  "language": "de-DE"
}

Raw audio chunk (transferMode: "audio" only):

{
  "type": "audioChunk",
  "sessionId": "...",
  "audio": {
    "data": "<base64-encoded PCM16>",
    "sampleRate": 16000,
    "format": "pcm16",
    "timestamp": "2026-02-18T10:30:00.500Z"
  }
}

Keepalive:

{ "type": "ping" }

Messages: Gateway → Bot

Play TTS audio:

{
  "type": "playAudio",
  "sessionId": "...",
  "audio": {
    "data": "<base64-encoded MP3>",
    "format": "mp3"
  }
}

Send chat message:

{
  "type": "sendChatMessage",
  "sessionId": "...",
  "text": "Here is my summary of the discussion..."
}

Stop audio playback:

{ "type": "stopAudio", "sessionId": "..." }

Keepalive response:

{ "type": "pong" }

Step 3: Leave the Meeting

POST /api/bot/:sessionId/leave

{
  "success": true,
  "message": "Leave initiated"
}

Step 4: Check Status

GET /api/bot/:sessionId/status

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "state": "in_meeting",
  "error": null
}

Health Check

GET /health

Returns 200 OK with { "status": "ok", "timestamp": "..." }.

Meeting URL Formats

Both formats are supported:

# Classic
https://teams.microsoft.com/l/meetup-join/19%3ameeting_xxx/0?context=...

# Short
https://teams.microsoft.com/meet/123456789?p=abc123

Running the Service

Local

npm install
cp .env.sample .env   # Configure Gateway URL, bot name, etc.
npm run dev            # Dev mode

Docker

docker build -t teams-bot .

docker run -p 4100:4100 \
  -e GATEWAY_WS_URL=wss://gateway.example.com/api/teamsbot/ws \
  teams-bot

Configuration

Variable	Description	Default
PORT	HTTP server port	4100
GATEWAY_WS_URL	Gateway WebSocket base URL	—
BOT_NAME	Default bot display name	—
LOG_LEVEL	Log level (debug, info, warn, error)	info