sitemente/voice-widget-guide.md

🎙️ SiteMente Custom Voice Widget

A custom voice AI chat widget using MiniMax as the brain, Web Speech API for input, and Browser TTS for output.

---

✅ What's Included

1. MiniMaxVoiceWidget.tsx - React component
2. API endpoint - /api/ai/voice-chat

---

🚀 Quick Deploy

1. Copy Files to Production

Copy these files to your SiteMente repo:

• components/MiniMaxVoiceWidget.tsx → SiteMente/components/MiniMaxVoiceWidget.tsx
• app/api/ai/voice-chat/route.ts → SiteMente/app/api/ai/voice-chat/route.ts

2. Update .env.local (if needed)

MINIMAX_API_KEY=your_minimax_key_here

3. Add to Page

In any page (e.g., app/page.tsx or app/demos/[vertical]/page.tsx):

import MiniMaxVoiceWidget from "@/components/MiniMaxVoiceWidget";

export default function DemoPage() {
  return (
    <>
      {/* Your page content */}
      
      <MiniMaxVoiceWidget 
        businessName="Restaurante Ejemplo"
        businessType="restaurant"
        theme="dark"
      />
    </>
  );
}

4. Deploy

git add .
git commit -m "Add custom voice widget"
git push origin develop

---

⚙️ Configuration Options

Prop	Type	Default	Description
businessName	string	"SiteMente"	Name shown in chat
businessType	string	"restaurant"	restaurant, real-estate, clinic, car-rental
theme	string	"dark"	"dark" or "light"
apiUrl	string	"/api/ai/voice-chat"	Custom API endpoint

---

🌍 Language Behavior

• Default: Spanish
• Switch: After first user message, detects language and switches automatically
• Manual toggle: Button in chat header

---

💰 Cost

• Input (Speech → Text): FREE (Web Speech API)
• Output (Text → Speech): FREE (Browser TTS)
• Brain (MiniMax): Your existing API key (~€0.001/msg)

Total cost: Nearly zero for POCs!

---

🔧 Customization

Change Voice

In MiniMaxVoiceWidget.tsx, find speak() function:

// Different voices available
const voices = synthRef.current?.getVoices();
// Spanish voices
const spanishVoice = voices?.find(v => v.lang.includes("es"));
utterance.voice = spanishVoice;

Add More Business Types

Edit SYSTEM_PROMPT in route.ts to customize responses per business type.

---

🐛 Troubleshooting

"Speech recognition not supported"

• Use Chrome, Edge, or Safari (not Firefox)
• HTTPS required (or localhost)

"API request failed"

• Check MiniMax API key is valid
• Check API endpoint is accessible

Widget not showing

• Ensure client-side import: "use client"
• Check for CSS conflicts

---

📦 Next Steps (Optional)

1. Voice cloning - ElevenLabs ($5-15/month)
2. Emotions - Custom prompts for personality
3. Multi-turn - Longer conversation history
4. Vapi integration - For phone calls later

---

Status: Ready to test! 🚀