174 lines
5.3 KiB
Markdown
174 lines
5.3 KiB
Markdown
# 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)
|