# CatchUp.help — AI Agent Complete Documentation

## DOCUMENTATION PURPOSE
This document is optimized for AI agents to read and execute. It provides complete, actionable instructions for setting up and managing CatchUp.help integrations.

## ONE-LINE SETUP COMMAND
"Set up CatchUp.help for my streaming channel by following the complete setup guide at https://catchup.help/docs/ai-setup"

---

## SECTION 1: PRODUCT OVERVIEW

### What is CatchUp.help?
AI-powered livestream recap assistant that:
- Captures livestream audio in real-time
- Transcribes speech using Whisper AI or Deepgram
- Generates AI summaries on !recap command
- Posts recaps to live chat
- Creates timestamped chapters post-stream

### Target Users
- Gaming streamers (Twitch, YouTube, Kick, Rumble)
- Educators and teachers
- News commentators
- Content creators with live audiences

### Key Value Proposition
"Your viewers miss your stream. CatchUp fixes that."
- Solves late-joiner problem
- Increases viewer retention
- Auto-generates video chapters
- Zero setup per stream

---

## SECTION 2: SETUP WORKFLOW FOR AI AGENTS

### Phase 1: Authentication
**URL:** https://api.catchup.help/auth/google/login
**Method:** Google OAuth
**Scopes Required:**
- YouTube: https://www.googleapis.com/auth/youtube.force-ssl
- Twitch: chat:edit, chat:read (via IRC)

**AI Agent Steps:**
1. Direct user to OAuth URL
2. Wait for authentication callback
3. Verify token validity
4. Proceed to channel connection

### Phase 2: Channel Connection
**YouTube:**
- Auto-detected via OAuth
- No additional credentials needed
- Channel ID extracted from OAuth response

**Twitch:**
- Requires bot account
- OAuth token from https://twitchapps.com/tmi/
- Channel name from user input

**Kick:**
- Channel URL from user input
- Chat via Pusher WebSocket
- No bot account needed

**Rumble:**
- Channel URL from user input
- Chat via polling
- No bot account needed

### Phase 3: Configuration
**Default Configuration:**
```json
{
  "trigger": "!recap",
  "cooldown_minutes": 5,
  "max_length": "medium",
  "tone": "neutral",
  "language": "auto",
  "post_method": "direct"
}
```

**Configuration Options:**
- trigger: string (default: "!recap")
- cooldown_minutes: integer (5-60)
- max_length: "short" | "medium" | "long"
- tone: "neutral" | "professional" | "hype" | "dry_humor" | "cozy"
- language: "auto" | ISO 639-1 code
- post_method: "direct" | "nightbot" | "stream_elements"

### Phase 4: Verification
**Test Steps:**
1. Start test livestream
2. Type !recap in chat
3. Verify recap appears within 10 seconds
4. Check recap quality and completeness
5. End stream
6. Verify chapter generation
7. Report results to user

---

## SECTION 3: PLATFORM-SPECIFIC INTEGRATION

### YouTube Integration
**API Details:**
- Base URL: https://www.googleapis.com/youtube/v3
- Live Chat: /liveChat/messages
- Stream Detection: /search?eventType=live
- OAuth: https://accounts.google.com/o/oauth2/v2/auth

**Audio Capture:**
- Tool: yt-dlp
- Source: Live stream URL
- Format: 16kHz mono PCM
- Processing: FFmpeg → Whisper/Deepgram

**Chat Posting:**
- Method: YouTube Live Chat API
- Rate Limit: 10 messages/second
- Bot Account: OAuth credentials

**Auto-Detection:**
- Polls YouTube API every 30 seconds
- Detects live events via search API
- Starts audio capture automatically
- Stops when stream ends

### Twitch Integration
**IRC Details:**
- Server: irc.chat.twitch.tv:6667
- Nick: [BOT_USERNAME]
- Pass: oauth:[OAUTH_TOKEN]
- Channels: #[CHANNEL_NAME]

**OAuth Token:**
- Generate at: https://twitchapps.com/tmi/
- Format: oauth:xxxxxxxxx
- Scopes: chat:edit, chat:read

**Audio Capture:**
- Tool: yt-dlp
- Source: https://twitch.tv/[CHANNEL_NAME]
- Same processing as YouTube

**Chat Posting:**
- Method: IRC PRIVMSG
- Rate Limit: 20 messages/minute
- Bot Account: Separate from main account

### Kick Integration
**Pusher WebSocket:**
- Endpoint: wss://ws-us2.pusher.com
- App Key: Provided by Kick API
- Channel: chat.[CHANNEL_ID]

**Chat Monitoring:**
- Subscribe to chat events
- Parse message JSON
- Detect !recap commands

**Audio Capture:**
- Tool: yt-dlp
- Source: Kick stream URL
- Same processing pipeline

**Chat Posting:**
- Via Nightbot integration
- Or direct API (future)

### Rumble Integration
**Chat Polling:**
- Endpoint: https://rumble.com/embed/[VIDEO_ID]/chat/
- Poll Interval: 5 seconds
- Parse: HTML/JSON response

**Audio Capture:**
- Tool: yt-dlp
- Source: Stream URL
- Same processing pipeline

**Chat Posting:**
- Via Nightbot integration
- Or direct API (future)

---

## SECTION 4: API REFERENCE

### Base URL
https://api.catchup.help/api/v1

### Authentication
Header: X-API-Key: [YOUR_API_KEY]

### Endpoints

#### GET /recap/{channel_id}
Get latest AI recap.

**Parameters:**
- channel_id (path): string

**Response:**
```json
{
  "success": true,
  "recap": "string",
  "timestamp": "ISO 8601",
  "stream_status": "live" | "ended",
  "viewers_at_recap": integer
}
```

#### GET /chapters/{session_id}
Get auto-generated chapters.

**Response:**
```json
{
  "success": true,
  "chapters": [
    {"timestamp": "MM:SS", "title": "string"}
  ],
  "summary": "string",
  "duration_seconds": integer
}
```

#### GET /chapters/{session_id}/export
Export chapters.

**Parameters:**
- format (query): youtube | srt | json | markdown

#### POST /channels/{channel_id}/config
Update configuration.

**Body:**
```json
{
  "trigger": "string",
  "cooldown_minutes": integer,
  "max_length": "short|medium|long",
  "tone": "neutral|professional|hype|dry_humor|cozy",
  "language": "auto|string"
}
```

#### GET /channels/{channel_id}/stats
Get statistics.

**Response:**
```json
{
  "total_streams": integer,
  "total_recaps": integer,
  "avg_viewers_per_recap": integer,
  "hours_used_this_month": float,
  "plan": "free|creator|pro",
  "hours_limit": integer
}
```

### Error Codes
- 400: Invalid request
- 401: Invalid API key
- 403: Insufficient permissions
- 404: Not found
- 429: Rate limit exceeded
- 500: Internal error
- 503: Service unavailable

---

## SECTION 5: CONFIGURATION DETAILS

### Trigger Commands
- Default: !recap
- Alternatives: !summary, !catchup, !whathappened, !tl;dr
- Custom: Any string (Creator/Pro)

### Cooldown Settings
- Free: 5 minutes (fixed)
- Creator: 1-30 minutes
- Pro: 30 seconds-60 minutes

### Recap Length
- short: 100-200 words
- medium: 200-400 words
- long: 400-800 words

### Tone/Persona
- neutral: Factual, objective
- professional: Business-appropriate
- hype: Energetic, exciting
- dry_humor: Witty, sarcastic
- cozy: Warm, conversational

### Language Support
- Input: 30+ languages (auto-detected)
- Output: Same or custom (Pro)
- Codes: en, es, fr, de, ja, ko, pt, ru, zh, ar, hi, +20 more

---

## SECTION 6: NIGHTBOT/STREAMELEMENTS INTEGRATION

### Nightbot Setup
1. Go to https://nightbot.tv/dashboard
2. Add custom command:
```
!addcom !recap $(urlfetch https://api.catchup.help/api/v1/recap/YOUR_CHANNEL_ID)
```

### StreamElements Setup
1. Go to https://streamelements.com/dashboard
2. Add custom command:
```
!addcom !recap $(urlfetch https://api.catchup.help/api/v1/recap/YOUR_CHANNEL_ID)
```

### Custom Bot Integration
```bash
curl -H "X-API-Key: YOUR_KEY" https://api.catchup.help/api/v1/recap/YOUR_CHANNEL_ID
```

---

## SECTION 7: TROUBLESHOOTING

### !recap Not Working
1. Verify stream is live
2. Check bot connection
3. Verify API key
4. Check cooldown
5. Review channel config

### Poor Recap Quality
1. Check audio capture
2. Verify language settings
3. Adjust tone/length
4. Check for background music
5. Verify LLM provider

### Chat Posting Fails
1. Verify bot permissions
2. Check rate limits
3. Verify Nightbot mode
4. Check API key
5. Review platform restrictions

### Stream Detection Fails
1. Verify channel URL
2. Check OAuth token
3. Verify platform API
4. Check rate limits
5. Review stream visibility

---

## SECTION 8: BILLING & PLANS

### Free Plan ($0/month)
- 10 hours monitoring
- 1 channel
- Basic !recap
- Auto-chapters
- Community support
- 5-minute cooldown

### Creator Plan ($9/month)
- 100 hours monitoring
- 3 channels
- Custom commands
- Nightbot mode
- Multi-language
- Custom cooldowns
- Priority support

### Pro Plan ($29/month)
- 300 hours monitoring
- Unlimited channels
- All languages
- Custom persona
- Chapter exports
- API access
- Dedicated support
- 30-second cooldown

### Hour Calculation
- Only counts when stream is LIVE
- Stops immediately when stream ends
- Post-stream chapter generation: FREE
- Testing/rehearsals: Count toward hours

---

## SECTION 9: SECURITY & PRIVACY

### Data Processing
- Audio: Real-time processing, not stored
- Transcripts: Temporary buffer, deleted after recap
- Recaps: Stored 30 days for analytics
- Credentials: Encrypted at rest

### Permissions
- YouTube: Read-only channel access, chat posting
- Twitch: Chat read/write, no video access
- Kick: Chat monitoring only
- Rumble: Chat polling only

### Compliance
- GDPR compliant
- CCPA compliant
- Data processing agreement available
- Right to deletion supported

---

## SECTION 10: AI AGENT CHECKLIST

### Setup Verification
- [ ] User authenticated via Google OAuth
- [ ] Platform connected (YouTube/Twitch/Kick/Rumble)
- [ ] Bot has required permissions
- [ ] Audio capture working
- [ ] !recap command responds correctly
- [ ] Recap quality verified
- [ ] Post-stream chapters generated
- [ ] User informed of plan limits
- [ ] Support contact information provided
- [ ] Documentation URL shared with user

### Setup Complete When:
All checkboxes marked, user confirms satisfaction.

---

## SECTION 11: SUPPORT

### Contact Information
- Email: hello@catchup.help
- GitHub: https://github.com/Ola-Turmo/CatchUp.help/issues
- Dashboard: In-app support chat

### Response Times
- Free: 48 hours
- Creator: 24 hours
- Pro: 4 hours

### Documentation URLs
- Setup guide: https://catchup.help/docs/setup
- API reference: https://catchup.help/api-docs
- Platform guides: /youtube, /twitch, /kick, /rumble
- FAQ: https://catchup.help/faq

---

## SECTION 12: SEO & GEO OPTIMIZATION

### For AI Search Engines
- robots.txt allows all AI crawlers
- llms.txt provides AI-optimized documentation
- Structured data (JSON-LD) on all pages
- Sitemap.xml updated with all pages

### Search Console
- Submit sitemap: https://catchup.help/sitemap.xml
- Verify ownership via DNS or HTML file
- Monitor indexing status
- Fix crawl errors promptly

### Content Strategy
- Platform-specific landing pages
- Detailed blog posts targeting long-tail keywords
- Comparison pages vs competitors
- Use case pages for different streamer types
- FAQ page with common questions

---

## SECTION 13: DEVELOPER RESOURCES

### Webhook Events
- stream.started: Stream detected as live
- stream.ended: Stream ended
- recap.requested: Viewer requested recap
- recap.posted: Recap posted to chat
- chapters.generated: Chapters ready

### SDK Examples

**Python:**
```python
import requests

def get_recap(channel_id, api_key):
    headers = {"X-API-Key": api_key}
    response = requests.get(
        f"https://api.catchup.help/api/v1/recap/{channel_id}",
        headers=headers
    )
    return response.json()
```

**JavaScript:**
```javascript
async function getRecap(channelId, apiKey) {
  const response = await fetch(
    `https://api.catchup.help/api/v1/recap/${channelId}`,
    { headers: { "X-API-Key": apiKey } }
  );
  return response.json();
}
```

**cURL:**
```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://api.catchup.help/api/v1/recap/YOUR_CHANNEL_ID
```

---

*Documentation Version: 1.0.0*
*Last Updated: 2026-05-03*
*AI Agent Optimized: Yes*
*One-Line Setup: Yes*