An enchanting AI-powered Santa experience that allows children (and adults!) to have real-time voice conversations with Santa Claus. Built with SignalWire's AI Agent technology, this application features dynamic gift searching, real-time product displays, and a magical Christmas atmosphere.
- Real-time conversations with Santa using SignalWire's AI Agent
- ElevenLabs voice synthesis for authentic Santa voice
- Natural language processing for understanding gift requests
- WebRTC video/audio streaming with festive backgrounds
- Real-time Amazon product search via RapidAPI
- Visual gift gallery with product images and details
- Interactive gift selection with 3D card effects
- Smart product recommendations based on conversation context
- Animated snowfall with accumulation effect
- Twinkling Christmas lights with individual bulb animations
- Aurora Borealis background effects
- Christmas countdown timer
- Background holiday music with volume controls
- Nice list checker with animated results
- Gift selection confirmation with confetti effects
- Responsive design for all devices
- Python 3.9+
- SignalWire account with AI Agent access
- RapidAPI account for Amazon product search
- Clone the repository:
git clone https://github.com/signalwire/santa.git
cd santa- Create a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- Install dependencies:
pip install -r requirements.txt- Create
.envfile:
# SignalWire Configuration
SIGNALWIRE_PROJECT_ID=your_project_id
SIGNALWIRE_TOKEN=your_auth_token
SIGNALWIRE_SPACE=your_space.signalwire.com
# RapidAPI Configuration
RAPIDAPI_KEY=your_rapidapi_key
RAPIDAPI_HOST=real-time-amazon-data.p.rapidapi.com
# Optional: Custom domain
HTTP_USERNAME=your_username
HTTP_PASSWORD=your_password
HTTP_DOMAIN=your-domain.com
# Server Configuration
PORT=5000
HOST=0.0.0.0- Start the application:
python santa_ai.py-
Access the application:
- Open your browser to
http://localhost:5000 - Click "Talk to Santa!" to begin
- Open your browser to
-
Configure SignalWire phone number:
- Point your SignalWire number to:
https://your-domain.com/swml - Set the webhook type to "Voice"
- Point your SignalWire number to:
- Click the green "Talk to Santa!" button
- Allow microphone/camera permissions when prompted
- Santa will greet you with his jolly voice
- Tell Santa what gifts you'd like for Christmas
- Say something like: "I want a toy robot"
- Santa will search his workshop catalog
- 4 gift options will appear with images and details
- Say "option 1", "option 2", "option 3", or "option 4" to select
- Mute Button: Toggle your microphone during the call
- Snow Effect: Watch snow accumulate at the bottom
- Christmas Lights: Individual bulbs twinkle independently
- Gift Cards: Hover for 3D effects, click to select
santa_ai.py
├── SantaAI class (SignalWire AI Agent)
├── SWAIG Functions
│ ├── search_gifts()
│ ├── select_gift()
│ └── check_nice_list()
├── RapidAPI Integration
└── WebSocket Communication
web/
├── index.html # Main application page
├── app.js # SignalWire SDK integration
├── styles.css # Festive styling & animations
└── media/ # Audio/video assets
- Gift State: Tracks search results and selections
- Conversation Context: Manages dialogue flow
- Frontend Events: Real-time UI updates via WebSocket
- Create a Dokku app:
dokku apps:create santa-ai- Set environment variables:
dokku config:set santa-ai SIGNALWIRE_PROJECT_ID=xxx
dokku config:set santa-ai SIGNALWIRE_TOKEN=xxx
dokku config:set santa-ai RAPIDAPI_KEY=xxx- Deploy:
git remote add dokku dokku@your-server:santa-ai
git push dokku main- SSL/TLS: Required for WebRTC connections
- CORS: Configure for your domain
- Rate Limiting: Implement for API endpoints
- Monitoring: Add logging and error tracking
- Scaling: Use load balancer for multiple instances
Edit voice ID in santa_ai.py:
voice_id = 'uDsPstFWFBUXjIBimV7s' # Santa voiceModify CSS variables in styles.css:
--christmas-red: #C41E3A;
--christmas-green: #165B33;
--christmas-gold: #FFD700;Adjust product count in santa_ai.py:
for i, product in enumerate(products[:4], 1): # Shows 4 productsNo Audio/Video
- Ensure HTTPS is enabled (required for WebRTC)
- Check browser permissions for microphone/camera
- Verify SignalWire credentials
Search Not Working
- Confirm RapidAPI key is valid
- Check API rate limits
- Verify network connectivity
Mute Button Issues
- Refresh browser to clear cache
- Check console for WebRTC errors
POST /swml
- Receives SignalWire AI Agent requests
- Returns SWML instructions
GET /swml
- Alternative webhook endpoint for SignalWire
GET /health
- Health check endpoint
- Returns:
{"status": "healthy"}
GET /api/info
- System information endpoint
- Returns API version and status
Events sent via WebSocket:
gifts_found: Products found from searchgift_selected: User selected a giftnice_list_checked: Nice list verification completesearching: Search in progresssearch_failed: Search encountered an error
We welcome contributions!
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
- SignalWire - AI Agent platform and WebRTC infrastructure
- ElevenLabs - Voice synthesis technology
- RapidAPI - Real-time Amazon product data
- Open Source Community - Various libraries and tools
- Live Demo - Try Santa's Workshop
- SignalWire Documentation
- Project Repository
- Report Issues
For questions and support:
- Open an issue on GitHub
- Join our Discord Community
- Contact SignalWire support
🎄 Happy Holidays from SignalWire! 🎅
Built with ❤️ and holiday magic by the SignalWire team.