# Teams Browser Bot Service

Browser-based Microsoft Teams Meeting Bot using Playwright. This service joins Teams meetings via the web interface, captures live captions, and plays TTS audio responses.
Last rev. 2026-01-15

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        Browser-based Architecture                           │
│                                                                             │
│  ┌───────────────────┐                    ┌───────────────────────────────┐ │
│  │     Gateway       │                    │    Browser Bot Service        │ │
│  │    (Python)       │                    │    (Node.js + Playwright)     │ │
│  │                   │                    │                               │ │
│  │  - STT (Google)   │    WebSocket       │  - Headless Chrome            │ │
│  │  - AI (OpenAI)    │◄──────────────────►│  - Teams Web App              │ │
│  │  - TTS (Google)   │   Transcripts      │  - Meeting join flow          │ │
│  │  - Session Mgmt   │   + TTS Audio      │  - Captions scraping          │ │
│  │                   │                    │  - Audio playback             │ │
│  └───────────────────┘                    └───────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Features

- **Multi-tenant support**: Can join any Teams meeting (not limited to own tenant)
- **Browser-based**: Uses Teams web app, no Graph Communications SDK needed
- **Captions scraping**: Captures live captions for transcription
- **Audio playback**: Plays TTS audio through the browser into the meeting
- **WebSocket integration**: Real-time communication with Gateway

## Prerequisites

- Node.js 18+
- Docker (for production deployment)

## Quick Start

### Local Development

```bash
# Install dependencies
npm install

# Install Playwright browsers
npx playwright install chromium

# Copy and configure environment
cp .env.sample .env
# Edit .env with your settings

# Run in development mode
npm run dev
```

### Docker

```bash
# Build and run
docker-compose up --build

# Or build image only
docker build -t teams-browser-bot .
```

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | HTTP server port | `4100` |
| `GATEWAY_WS_URL` | Gateway WebSocket URL | `wss://gateway-int.poweron-center.net/api/teamsbot/ws` |
| `BOT_NAME` | Display name in meetings | `PowerOn AI` |
| `BOT_HEADLESS` | Run browser headless | `true` |
| `LOG_LEVEL` | Logging level | `info` |
| `SCREENSHOT_ON_ERROR` | Take screenshots on errors | `true` |

## API Endpoints

### Health Check
```
GET /health
```

### Deploy Bot
```
POST /api/bot
Content-Type: application/json

{
  "sessionId": "uuid",
  "meetingUrl": "https://teams.microsoft.com/meet/...",
  "botName": "PowerOn AI"
}
```

### Leave Meeting
```
POST /api/bot/:sessionId/leave
```

### Get Status
```
GET /api/bot/:sessionId/status
```

## WebSocket Protocol

### Gateway → Bot

```typescript
// Join a meeting
{ type: "joinMeeting", sessionId: "uuid", meetingUrl: "...", botName?: "..." }

// Leave meeting
{ type: "leaveMeeting", sessionId: "uuid" }

// Play audio
{ type: "playAudio", sessionId: "uuid", audio: { format: "mp3", data: "base64..." } }
```

### Bot → Gateway

```typescript
// Transcript
{ type: "transcript", sessionId: "uuid", transcript: { speaker: "...", text: "...", timestamp: "...", isFinal: true } }

// Status
{ type: "status", sessionId: "uuid", status: "joined" | "in_lobby" | "left" | "error", message?: "..." }
```

## Meeting URL Formats

Supports both classic and new (short) URL formats:

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

# New format (since 2025)
https://teams.microsoft.com/meet/36438888781520?p=5fGqrujxzewPFjJacW
```

## Deployment

### Azure Container Instance

```bash
# Create resource group
az group create --name rg-teams-bot --location westeurope

# Create container instance
az container create \
  --resource-group rg-teams-bot \
  --name teams-browser-bot \
  --image <your-registry>/teams-browser-bot:latest \
  --cpu 2 \
  --memory 4 \
  --ports 4100 \
  --environment-variables \
    GATEWAY_WS_URL=wss://gateway-int.poweron-center.net/api/teamsbot/ws \
    BOT_NAME="PowerOn AI"
```

## Debugging

- Logs are written to `output/logs/`
- Screenshots (on error) are saved to `output/screenshots/`
- Set `BOT_HEADLESS=false` for local debugging with visible browser

## Based On

- [Recall.ai Microsoft Teams Meeting Bot](https://github.com/recallai/microsoft-teams-meeting-bot)
- [Recall.ai Blog: How to build a Microsoft Teams Bot](https://www.recall.ai/blog/how-to-build-a-microsoft-teams-bot)