Skip to main content

🎓 Voice Deployment Lessons Learned

The 30-Minute Rollback Lesson 🕐​

What Happened​

Used colons (:) in WebSocket route names like voice:session:start, which AWS API Gateway doesn't support. This triggered a 30-minute rollback process.

The Fix​

// ❌ WRONG
'voice:session:start': { ... }

// ✅ CORRECT
'voice.session.start': { ... }

Key Takeaways​

  1. AWS API Gateway WebSocket routes only support: letters, numbers, dots (.), underscores (_), and hyphens (-)
  2. Rollbacks are SLOW: CloudFormation must delete every Lambda, integration, and resource one by one
  3. Test route names early: Better to catch this before full deployment

The Session Connection Issue 🔌​

What Happened​

Voice button showed "connecting" forever because backend returned success before OpenAI created the session.

The Fix​

Added waitForSession() method to ensure OpenAI's session.created event fires before returning:

// In OpenAIRealtimeBackend
async waitForSession(timeout = 5000): Promise<void> {
  if (this.sessionId) return;
  
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => 
      reject(new Error('Session creation timeout')), timeout);
    
    this.once('session.created', () => {
      clearTimeout(timer);
      resolve();
    });
  });
}

// In voiceSessionStart handler
await backend.connect();
await backend.updateSession(sessionConfig);
await backend.waitForSession(); // ← Critical!

Handler Configuration Completeness 🔧​

What Happened​

Voice handlers with incomplete configuration caused "no response from your machine" errors.

The Fix​

Every WebSocket handler needs COMPLETE configuration:

'voice.text.input': {
  function: {
    memorySize: '256 MB',
    timeout: '30 seconds',
    handler: 'path/to/handler.func',
    bind: [secrets.MONGODB_URI, secrets.JWT_SECRET, websocketApi],
    vpc,
  },
  returnResponse: true,
}

Quick Reference Card 📋​

When Things Go Wrong​

  1. Stuck in "connecting": Check if backend waits for session creation
  2. Route deployment fails: Remove colons from route names
  3. "No response from machine": Verify handler has full configuration
  4. Long rollback: Go make coffee ☕ (seriously, it takes 20-30 min)

Always Remember​

  • User runs servers, not SST
  • Test WebSocket routes with simple names first
  • Wait for async operations to actually complete
  • Full handler config or it won't work

The Good News 🎉​

Once these issues are fixed, the voice system works beautifully! Real-time transcription and AI responses feel magical when everything connects properly.