mirror of
https://github.com/Monadical-SAS/reflector.git
synced 2025-12-21 04:39:06 +00:00
docs: add comprehensive Whereby integration user guide
- Complete end-user configuration guide for Whereby video platform
- Covers account setup, API key generation, and webhook configuration
- AWS S3 storage setup with IAM permissions and security best practices
- Room creation, recording options, and meeting feature configuration
- Troubleshooting guide with common issues and debug commands
- Security considerations and performance optimization tips
- Migration guidance from other platforms
🤖 Generated with Claude Code
This commit is contained in:
276
docs/video-whereby.md
Normal file
276
docs/video-whereby.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# Whereby Integration Configuration Guide
|
||||
|
||||
This guide explains how to configure Reflector to use Whereby as your video meeting platform for room creation, recording, and participant tracking.
|
||||
|
||||
## Overview
|
||||
|
||||
Whereby is a browser-based video meeting platform that provides hosted meeting rooms with recording capabilities. Reflector integrates with Whereby's API to:
|
||||
|
||||
- Create secure meeting rooms with custom branding
|
||||
- Handle participant join/leave events via webhooks
|
||||
- Automatically record meetings to AWS S3 storage
|
||||
- Track meeting sessions and participant counts
|
||||
|
||||
## Requirements
|
||||
|
||||
### Whereby Account Setup
|
||||
|
||||
1. **Whereby Account**: Sign up for a Whereby business account at [whereby.com](https://whereby.com/business)
|
||||
2. **API Access**: Request API access from Whereby support (required for programmatic room creation)
|
||||
3. **Webhook Configuration**: Configure webhooks in your Whereby dashboard to point to your Reflector instance
|
||||
|
||||
### AWS S3 Storage
|
||||
|
||||
Whereby requires AWS S3 for recording storage. You need:
|
||||
- AWS account with S3 access
|
||||
- Dedicated S3 bucket for Whereby recordings
|
||||
- AWS IAM credentials with S3 write permissions
|
||||
|
||||
## Configuration Variables
|
||||
|
||||
Add the following environment variables to your Reflector `.env` file:
|
||||
|
||||
### Required Variables
|
||||
|
||||
```bash
|
||||
# Whereby API Configuration
|
||||
WHEREBY_API_KEY=your-whereby-jwt-api-key
|
||||
WHEREBY_WEBHOOK_SECRET=your-webhook-secret-from-whereby
|
||||
|
||||
# AWS S3 Storage for Recordings
|
||||
AWS_WHEREBY_ACCESS_KEY_ID=your-aws-access-key
|
||||
AWS_WHEREBY_ACCESS_KEY_SECRET=your-aws-secret-key
|
||||
RECORDING_STORAGE_AWS_BUCKET_NAME=your-s3-bucket-name
|
||||
```
|
||||
|
||||
### Optional Variables
|
||||
|
||||
```bash
|
||||
# Whereby API URL (defaults to production)
|
||||
WHEREBY_API_URL=https://api.whereby.dev/v1
|
||||
|
||||
# SQS Configuration (for recording processing)
|
||||
AWS_PROCESS_RECORDING_QUEUE_URL=https://sqs.region.amazonaws.com/account/queue
|
||||
SQS_POLLING_TIMEOUT_SECONDS=60
|
||||
```
|
||||
|
||||
## Configuration Steps
|
||||
|
||||
### 1. Whereby API Key Setup
|
||||
|
||||
1. **Contact Whereby Support** to request API access for your account
|
||||
2. **Generate JWT Token** in your Whereby dashboard under API settings
|
||||
3. **Copy the JWT token** and set it as `WHEREBY_API_KEY` in your environment
|
||||
|
||||
The API key is a JWT token that looks like:
|
||||
```
|
||||
eyJ[...truncated JWT token...]
|
||||
```
|
||||
|
||||
### 2. Webhook Configuration
|
||||
|
||||
1. **Access Whereby Dashboard** and navigate to webhook settings
|
||||
2. **Set Webhook URL** to your Reflector instance:
|
||||
```
|
||||
https://your-reflector-domain.com/v1/whereby
|
||||
```
|
||||
3. **Configure Events** to send the following event types:
|
||||
- `room.client.joined` - When participants join
|
||||
- `room.client.left` - When participants leave
|
||||
4. **Generate Webhook Secret** and set it as `WHEREBY_WEBHOOK_SECRET`
|
||||
5. **Save Configuration** in your Whereby dashboard
|
||||
|
||||
### 3. AWS S3 Storage Setup
|
||||
|
||||
1. **Create S3 Bucket** dedicated for Whereby recordings
|
||||
2. **Create IAM User** with programmatic access
|
||||
3. **Attach S3 Policy** with the following permissions:
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"s3:PutObject",
|
||||
"s3:PutObjectAcl",
|
||||
"s3:GetObject"
|
||||
],
|
||||
"Resource": "arn:aws:s3:::your-bucket-name/*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
4. **Configure Environment Variables** with the IAM credentials
|
||||
|
||||
### 4. Room Configuration
|
||||
|
||||
When creating rooms in Reflector, set the platform to use Whereby:
|
||||
|
||||
```bash
|
||||
curl -X POST "https://your-reflector-domain.com/v1/rooms" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $AUTH_TOKEN" \
|
||||
-d '{
|
||||
"name": "my-whereby-room",
|
||||
"platform": "whereby",
|
||||
"recording_type": "cloud",
|
||||
"recording_trigger": "automatic-2nd-participant",
|
||||
"is_locked": false,
|
||||
"room_mode": "normal"
|
||||
}'
|
||||
```
|
||||
|
||||
## Meeting Features
|
||||
|
||||
### Recording Options
|
||||
|
||||
Whereby supports three recording types:
|
||||
- **`none`**: No recording
|
||||
- **`local`**: Local recording (not recommended for production)
|
||||
- **`cloud`**: Cloud recording to S3 (recommended)
|
||||
|
||||
### Recording Triggers
|
||||
|
||||
Control when recordings start:
|
||||
- **`none`**: No automatic recording
|
||||
- **`prompt`**: Prompt users to start recording
|
||||
- **`automatic`**: Start immediately when meeting begins
|
||||
- **`automatic-2nd-participant`**: Start when second participant joins
|
||||
|
||||
### Room Modes
|
||||
|
||||
- **`normal`**: Standard meeting room
|
||||
- **`group`**: Group meeting with advanced features
|
||||
|
||||
## Webhook Event Handling
|
||||
|
||||
Reflector automatically handles these Whereby webhook events:
|
||||
|
||||
### Participant Tracking
|
||||
```json
|
||||
{
|
||||
"type": "room.client.joined",
|
||||
"data": {
|
||||
"meetingId": "room-uuid",
|
||||
"numClients": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Recording Events
|
||||
Whereby sends recording completion events that trigger Reflector's processing pipeline:
|
||||
- Audio transcription
|
||||
- Speaker diarization
|
||||
- Summary generation
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### API Authentication Errors
|
||||
**Symptoms**: 401 Unauthorized errors when creating meetings
|
||||
|
||||
**Solutions**:
|
||||
1. Verify your `WHEREBY_API_KEY` is correct and not expired
|
||||
2. Ensure you have API access enabled on your Whereby account
|
||||
3. Contact Whereby support if API access is not available
|
||||
|
||||
#### Webhook Signature Validation Failed
|
||||
**Symptoms**: Webhook events rejected with 401 errors
|
||||
|
||||
**Solutions**:
|
||||
1. Verify `WHEREBY_WEBHOOK_SECRET` matches your Whereby dashboard configuration
|
||||
2. Check webhook URL is correctly configured in Whereby dashboard
|
||||
3. Ensure webhook endpoint is accessible from Whereby servers
|
||||
|
||||
#### Recording Upload Failures
|
||||
**Symptoms**: Recordings not appearing in S3 bucket
|
||||
|
||||
**Solutions**:
|
||||
1. Verify AWS credentials have S3 write permissions
|
||||
2. Check S3 bucket name is correct and accessible
|
||||
3. Ensure AWS region settings match your bucket location
|
||||
4. Review AWS CloudTrail logs for permission issues
|
||||
|
||||
#### Participant Count Not Updating
|
||||
**Symptoms**: Meeting participant counts remain at 0
|
||||
|
||||
**Solutions**:
|
||||
1. Verify webhook events are being received at `/v1/whereby`
|
||||
2. Check webhook signature validation is passing
|
||||
3. Ensure meeting IDs match between Whereby and Reflector database
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Test Whereby API connectivity
|
||||
curl -H "Authorization: Bearer $WHEREBY_API_KEY" \
|
||||
https://api.whereby.dev/v1/meetings
|
||||
|
||||
# Check webhook endpoint health
|
||||
curl https://your-reflector-domain.com/v1/whereby/health
|
||||
|
||||
# Verify S3 bucket access
|
||||
aws s3 ls s3://your-bucket-name --profile whereby-user
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### API Key Security
|
||||
- Store API keys securely using environment variables
|
||||
- Rotate API keys regularly
|
||||
- Never commit API keys to version control
|
||||
- Use separate keys for development and production
|
||||
|
||||
### Webhook Security
|
||||
- Always validate webhook signatures using HMAC-SHA256
|
||||
- Use HTTPS for all webhook endpoints
|
||||
- Implement rate limiting on webhook endpoints
|
||||
- Monitor webhook events for suspicious activity
|
||||
|
||||
### Recording Privacy
|
||||
- Ensure S3 bucket access is restricted to authorized users
|
||||
- Consider encryption at rest for sensitive recordings
|
||||
- Implement retention policies for recorded content
|
||||
- Comply with data protection regulations (GDPR, etc.)
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Meeting Scaling
|
||||
- Monitor concurrent meeting limits on your Whereby plan
|
||||
- Implement meeting cleanup for expired sessions
|
||||
- Use appropriate room modes for different use cases
|
||||
|
||||
### Recording Processing
|
||||
- Configure SQS for asynchronous recording processing
|
||||
- Monitor S3 storage usage and costs
|
||||
- Implement automatic cleanup of processed recordings
|
||||
|
||||
### Webhook Reliability
|
||||
- Implement webhook retry mechanisms
|
||||
- Monitor webhook delivery success rates
|
||||
- Log webhook events for debugging and auditing
|
||||
|
||||
## Migration from Other Platforms
|
||||
|
||||
If migrating from another video platform:
|
||||
|
||||
1. **Update Room Configuration**: Change existing rooms to use `"platform": "whereby"`
|
||||
2. **Configure Webhooks**: Set up Whereby webhook endpoints
|
||||
3. **Test Integration**: Verify meeting creation and event handling
|
||||
4. **Monitor Performance**: Watch for any issues during transition
|
||||
5. **Update Documentation**: Inform users of any workflow changes
|
||||
|
||||
## Support
|
||||
|
||||
For Whereby-specific issues:
|
||||
- **Whereby Support**: [whereby.com/support](https://whereby.com/support)
|
||||
- **API Documentation**: [whereby.dev](https://whereby.dev)
|
||||
- **Status Page**: [status.whereby.com](https://status.whereby.com)
|
||||
|
||||
For Reflector integration issues:
|
||||
- Check application logs for error details
|
||||
- Verify environment variable configuration
|
||||
- Test webhook connectivity and authentication
|
||||
- Review AWS permissions and S3 access
|
||||
Reference in New Issue
Block a user