AI Recall Bot - Real-time Meeting Transcription & Wake-Phrase Detection

A FastAPI-based application that integrates with Recall.ai to create meeting bots that provide real-time transcription via webhooks, with intelligent wake-phrase detection for AI-powered research assistance.

🚀 Features

• Instant Bot Creation: Create meeting bots for any Google Meet, Zoom, or Teams URL
• Real-time Transcription: Receive live transcripts as people speak in meetings
• Wake-Phrase Detection: Automatically detect "Hey Samantha, can you research..." commands
• AI Research Integration: OpenAI-powered research responses to detected wake phrases
• Webhook Integration: Automatic webhook configuration for transcript delivery
• Real-time Monitoring: Web dashboard to monitor transcripts and research activity
• SQLite Storage: Persistent storage of transcripts and research results
• Multi-platform Support: Works with Google Meet, Zoom, Microsoft Teams, and more
• Auto-deployment: Integrated ngrok tunneling for easy webhook setup

🏗️ Architecture

┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Meeting URL   │───▶│  FastAPI App │───▶│   Recall.ai     │
└─────────────────┘    └──────────────┘    └─────────────────┘
                              │                      │
                              ▼                      ▼
                       ┌──────────────┐    ┌─────────────────┐
                       │    ngrok     │◀───│  Meeting Bot    │
                       │   Webhook    │    │ (Transcribing)  │
                       └──────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────────┐
                    │ Wake-Phrase Engine  │
                    │ "Hey Samantha..."   │
                    └─────────────────────┘
                              │
                              ▼
                    ┌─────────────────────┐    ┌─────────────────┐
                    │   OpenAI Research   │───▶│  SQLite Storage │
                    │     Assistant       │    │ Transcripts &   │
                    └─────────────────────┘    │ Research Results│
                                               └─────────────────┘

📋 Prerequisites

• Python 3.11+
• pyenv (recommended)
• ngrok account
• Recall.ai API key (us-west-2 region)
• OpenAI API key (for research functionality)

🛠️ Installation

1. Set up Python Environment

# Install Python 3.11.7 with pyenv
pyenv install 3.11.7
pyenv virtualenv 3.11.7 recall-poc
pyenv local recall-poc

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment

Create a .env file with your API keys:

# Recall.ai API Configuration (us-west-2 region)
RECALL_API_KEY=your_recall_api_key_here

# OpenAI API Key (for research functionality)
OPENAI_API_KEY=your_openai_api_key_here

# Database URL
DATABASE_URL=sqlite:///./recall_poc.db

# API Configuration
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=false

4. Install and Configure ngrok

# Install ngrok
brew install ngrok/ngrok/ngrok

# Configure your authtoken (get from ngrok.com)
ngrok authtoken YOUR_NGROK_TOKEN

🚀 Quick Start

Option 1: Automated Startup (Recommended)

# Start everything automatically (server + ngrok + interactive CLI)
python start_recall_bot.py

This will:

• Start the FastAPI server on port 8001
• Launch ngrok tunnel automatically
• Provide an interactive CLI for bot management
• Display webhook URLs and monitoring links

Option 2: Manual Setup

1. Start the Application

# Start FastAPI server
python -m src.recall_poc.main

2. Start ngrok Tunnel

# In a separate terminal
ngrok http 8000

🎯 Using the System

Interactive CLI Commands (Automated Startup)

When using python start_recall_bot.py, you get an interactive CLI:

> create https://meet.google.com/your-meeting-url
🤖 Creating bot for meeting: https://meet.google.com/your-meeting-url
   ✅ Bot created successfully!
   📋 Bot ID: abc-123-def
   🔗 Monitor URL: https://your-ngrok.ngrok-free.app/bots/abc-123-def

> status
📊 System Status:
   Server: http://localhost:8001
   Ngrok: https://your-ngrok.ngrok-free.app
   Webhook: https://your-ngrok.ngrok-free.app/webhooks/recall/transcript

> test
🧪 Running wake-phrase test...
   ✅ Test completed successfully!
   📝 Transcript: Hey Samantha, can you research AI safety best practices?
   🔍 Research Command: ai safety best practices

> quit

Manual Bot Creation

# Replace with your actual meeting URL
curl -X POST "http://localhost:8001/bots/quick-create?meeting_url=https://meet.google.com/abc-defg-hij"

📡 API Endpoints

Bot Management

Method	Endpoint	Description
POST	/bots/create	Create a new bot with full configuration
POST	/bots/quick-create	Quick bot creation with defaults
GET	/bots/	List all bots
GET	/bots/{bot_id}	Get specific bot details
DELETE	/bots/{bot_id}	Delete a bot

Webhooks & Monitoring

Method	Endpoint	Description
POST	/webhooks/recall/transcript	Receive real-time transcripts
GET	/webhooks/recall/test	Test webhook accessibility
POST	/webhooks/recall/test-payload	Test with sample data
POST	/webhooks/recall/test-research	Test wake-phrase detection
GET	/monitor/	Real-time monitoring dashboard
GET	/monitor/data	Get monitoring data as JSON

Health & Info

Method	Endpoint	Description
GET	/	API information and endpoints
GET	/health	Health check

🎤 Wake-Phrase Detection & AI Research

How It Works

1. Real-time Monitoring: The system continuously monitors meeting transcripts
2. Wake-Phrase Detection: Detects phrases like "Hey Samantha, can you research..."
3. AI Research: Automatically triggers OpenAI research on the detected topic
4. Storage: Stores both transcripts and research results in SQLite database

Supported Wake Phrases

"Hey Samantha, can you research [topic]?"
"Samantha, research [topic]"
"Hey Samantha, look up [topic]"

Example Usage

In your meeting, say:

"Hey Samantha, can you research AI safety best practices?"

The system will:

1. ✅ Detect the wake phrase
2. 🔍 Extract "AI safety best practices" as the research topic
3. 🤖 Query OpenAI for comprehensive research
4. 💾 Store the result in the database
5. 📊 Display in the monitoring dashboard

Monitoring Dashboard

Visit http://localhost:8001/monitor/ to see:

• Real-time transcripts from your meetings
• Wake-phrase detection highlights
• Research results from AI queries
• System statistics and activity

🤖 Bot Creation Examples

Quick Creation (Recommended)

# Using the interactive CLI
> create https://meet.google.com/abc-defg-hij

# Or via API
curl -X POST "http://localhost:8001/bots/quick-create?meeting_url=https://meet.google.com/abc-defg-hij"

Full Configuration

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "meeting_url": "https://meet.google.com/abc-defg-hij",
    "bot_name": "My Custom Bot",
    "transcription_provider": "meeting_captions",
    "enable_partial_transcripts": true,
    "auto_configure_webhook": true
  }' \
  http://localhost:8001/bots/create

📨 Webhook Payload Format

When transcripts are generated, your webhook receives:

{
  "event": "transcript.data",
  "data": {
    "data": {
      "words": [
        {
          "text": "Hello",
          "start_timestamp": {"relative": 0.0},
          "end_timestamp": {"relative": 0.5}
        }
      ],
      "participant": {
        "id": 1,
        "name": "John Doe",
        "is_host": true,
        "platform": "google_meet"
      }
    },
    "bot": {"id": "bot-123"},
    "recording": {"id": "recording-456"},
    "transcript": {"id": "transcript-789"}
  }
}

🔧 Configuration

Environment Variables

# Required
RECALL_API_KEY=your_recall_api_key_here

# Optional
RECALL_API_BASE_URL=https://us-west-2.recall.ai/api/v1
DATABASE_URL=sqlite:///./recall_poc.db
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=false

Recall.ai Regions

The API key determines the region. Common regions:

• us-west-2.recall.ai (default)
• us-east-1.recall.ai
• eu-central-1.recall.ai
• ap-northeast-1.recall.ai

📁 Project Structure

src/recall_poc/
├── __init__.py
├── main.py              # FastAPI application
├── settings.py          # Configuration management
├── api/
│   ├── __init__.py
│   ├── bots.py         # Bot management endpoints
│   ├── models.py       # Pydantic data models
│   ├── recall_client.py # Recall.ai API client
│   └── webhooks.py     # Webhook endpoints
├── skills/             # Future AI processing modules
└── db/                 # Database modules

🔍 Monitoring & Debugging

Check Bot Status

curl https://your-ngrok-url.ngrok-free.app/bots/{bot_id}

Monitor Webhooks

• ngrok Dashboard: http://127.0.0.1:4040
• Server Logs: Watch terminal output for transcript processing
• Webhook Test: GET /webhooks/recall/test

Common Bot Status Codes

• joining_call - Bot is connecting to meeting
• in_waiting_room - Bot is waiting for admission
• in_call_recording - Bot is actively recording
• call_ended - Meeting has ended
• done - Bot completed successfully

🎯 Workflow Example

1. Create Meeting: Start a Google Meet at https://meet.google.com/abc-defg-hij
2. Create Bot: POST /bots/create with the meeting URL
3. Bot Joins: Bot appears as "Recall POC Bot" in your meeting
4. Start Speaking: Real-time transcripts flow to your webhook
5. Process Data: Your app receives and processes transcript events

🚨 Troubleshooting

Bot Creation Fails

Error: "Invalid API token"

• ✅ Solution: Ensure your Recall.ai API key is for the us-west-2 region
• Check your .env file has the correct RECALL_API_KEY

Error: "Cannot specify realtime endpoint events for artifacts that are not configured"

• ✅ Solution: This is fixed in the current version - uses proper transcript configuration
• The system now correctly configures the transcript artifact before setting up webhooks

Error: "AssemblyAI credentials not configured"

• ✅ Solution: The system now uses meeting_captions by default (no external credentials needed)
• For advanced features, configure transcription providers in your Recall.ai dashboard

No Transcripts in Monitor Dashboard

Monitor shows 0 transcripts

• ✅ Solution: Refresh the page at http://localhost:8001/monitor/
• The JavaScript endpoint was fixed to use the correct API path
• Check that your bot is actually in the meeting and people are speaking

No Webhooks Received

• Verify ngrok tunnel is running (python start_recall_bot.py handles this automatically)
• Check webhook URL in bot configuration
• Test webhook endpoint: curl http://localhost:8001/webhooks/recall/test

Wake-Phrase Not Detected

• Ensure you're saying the exact phrase: "Hey Samantha, can you research [topic]?"
• Check the monitoring dashboard for transcript accuracy
• Verify OpenAI API key is configured in .env

Bot Doesn't Join Meeting

• Check if meeting exists and is active
• Verify meeting platform is supported (Google Meet, Zoom, Teams)
• Use a real meeting URL, not a test URL

Database Issues

# Reset database if needed
rm recall_poc.db
python -c "from src.recall_poc.db import create_tables; import asyncio; asyncio.run(create_tables())"

✅ Current Features

• Real-time transcription via Recall.ai webhooks
• Wake-phrase detection for "Hey Samantha" commands
• AI-powered research using OpenAI integration
• Real-time monitoring dashboard with live transcripts
• SQLite storage for transcripts and research results
• Automated deployment with ngrok integration
• Interactive CLI for easy bot management

🔮 Future Enhancements

• Meeting summaries and action items
• Multi-language support
• Integration with Slack/Teams/Discord
• Calendar integration for automatic bot scheduling
• Speaker identification and analytics
• Custom wake-phrase configuration
• Advanced transcription providers (AssemblyAI, AWS Transcribe)
• Conversation context awareness

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

---

Built with ❤️ using FastAPI, Recall.ai, and ngrok