A professional, production-ready Flutter application for real-time voice conversations with AI assistants. Built with the VAPI (Voice AI Platform Integration) SDK, this app provides a seamless voice interaction experience with a beautiful, responsive dark theme.
- Real-time Voice Calls: High-quality voice conversations with AI assistants
- Live Transcription: Real-time speech-to-text display during conversations
- Smart Call Management: Automatic connection handling with retry logic
- Audio Controls: Mute/unmute functionality with visual feedback
- Animated Avatar: Responsive avatar with glow effects that react to call states
- Dark Theme: Professional dark UI with blue accent colors
- Responsive Design: Optimized for both mobile and web platforms
- Smooth Animations: Fluid transitions and state changes throughout the app
- Environment Configuration: Secure API key management via .env files
- Mobile Optimized: Connection timeout handling and network resilience
- Error Handling: Comprehensive error management with user-friendly messages
- Performance Monitoring: Debug tools for development and troubleshooting
- Clean Architecture: Well-organized codebase with proper separation of concerns
ai_voice_assistant/
├── lib/
│ ├── main.dart # 🚀 App entry point & initialization
│ ├── core/ # 🏗️ Core application infrastructure
│ │ ├── constants/
│ │ │ └── app_constants.dart # 📋 App-wide constants & configuration
│ │ └── theme/
│ │ └── app_theme.dart # 🎨 Dark theme & color definitions
│ ├── screens/ # 📱 Application screens
│ │ └── voice_assistant_screen.dart # 🎙️ Main voice assistant interface
│ ├── services/ # ⚙️ Business logic & API integration
│ │ └── vapi_service.dart # 🔌 VAPI SDK integration & call management
│ └── widgets/ # 🧩 Reusable UI components
│ ├── animated_avatar.dart # 👤 Animated user avatar with glow effects
│ ├── call_button.dart # 📞 Call control button with animations
│ └── transcript_widget.dart # 📝 Real-time conversation transcript
├── .env # 🔐 Environment variables (API keys)
├── .env.example # 📄 Environment template
├── pubspec.yaml # 📦 Dependencies & project configuration
├── README.md # 📖 Project documentation
└── BEGINNER_TUTORIAL.md # 🎓 Complete beginner's code guide
The app follows a clean architecture pattern with clear separation of concerns:
main.dart: Application bootstrap and configurationcore/: Shared utilities, constants, and themingscreens/: UI screens and user interface logicservices/: Business logic, API integration, and state managementwidgets/: Reusable UI components with specific functionality
- Flutter SDK (3.8.1 or higher)
- Dart SDK (included with Flutter)
- VAPI Account with API credentials
- IDE (VS Code, Android Studio, or IntelliJ)
# Clone the repository
git clone <repository-url>
cd ai_voice_assistant
# Install dependencies
flutter pub get# Copy the environment template
cp .env.example .env
# Edit .env file with your VAPI credentials
VAPI_PUBLIC_KEY=your_actual_public_key_here
VAPI_ASSISTANT_ID=your_actual_assistant_id_here
⚠️ Security Note: Never commit your.envfile to version control. It contains sensitive API keys.
# For mobile development
flutter run
# For web development
flutter run -d chrome
# For specific device
flutter devices # List available devices
flutter run -d <device-id>- Launch the app on your device/emulator
- Tap the call button to start a voice conversation
- Speak naturally - the AI will respond and transcript will appear
- Use mute button to control microphone during calls
- Tap end call to finish the conversation
Core voice AI integration service
- VAPI Client Management: Initializes and manages VAPI SDK connections
- Call Lifecycle: Handles start, end, and status tracking of voice calls
- Real-time Events: Processes speech events, messages, and errors from VAPI
- Transcript Management: Captures and stores conversation history
- Mobile Optimization: Connection timeouts, retry logic, and error handling
- State Notifications: Notifies UI components of state changes via ChangeNotifier
Interactive user avatar with visual feedback
- Glow Animation: Pulsing glow effect during active calls
- State Responsiveness: Visual changes based on call status (idle, listening, speaking)
- Smooth Transitions: Fluid animations between different states
- Performance Optimized: Efficient animation controllers with proper disposal
Primary call control interface
- State-based Styling: Blue for start call, red for end call
- Touch Feedback: Scale animation on press for tactile response
- Loading States: Shows spinner during connection attempts
- Accessibility: Proper semantic labels for screen readers
Real-time conversation display
- Live Updates: Shows messages as they're transcribed
- Speaker Identification: Different styling for user vs assistant messages
- Auto-scrolling: Automatically scrolls to show latest messages
- Timestamps: Shows when each message was recorded
- Responsive Layout: Adapts to different screen sizes
Comprehensive theming system
- Dark Theme: Professional dark color scheme
- Color Palette: Consistent blue (#4A90E2) primary with red (#FF4444) accents
- Typography: Hierarchical text styles for different UI elements
- Component Theming: Consistent styling for buttons, cards, and other elements
| Variable | Description | Example |
|---|---|---|
VAPI_PUBLIC_KEY |
Your VAPI public API key | pk_1234567890abcdef... |
VAPI_ASSISTANT_ID |
Your VAPI assistant identifier | asst_9876543210fedcba... |
- Sign up at VAPI Dashboard
- Create an Assistant or use an existing one
- Copy the Public Key from your dashboard
- Copy the Assistant ID from your assistant settings
- Add them to your
.envfile
- Clean Architecture: Separation of concerns with clear layer boundaries
- Comprehensive Documentation: Every class and method is thoroughly documented
- Error Handling: Robust error management with user-friendly messages
- Performance Optimized: Efficient animations and memory management
- Mobile First: Optimized for mobile devices with network resilience
# Run with hot reload
flutter run
# Run tests
flutter test
# Build for production
flutter build apk # Android
flutter build ios # iOS
flutter build web # Web
# Code analysis
flutter analyze
# Format code
dart format .The app includes comprehensive logging and error handling:
- Debug Logs: Detailed console output in debug mode
- Error Messages: User-friendly error dialogs
- State Tracking: Complete call lifecycle logging
- Performance Monitoring: Built-in performance tracking
- Environment Variables: Sensitive data stored in
.envfiles - Git Ignore:
.envfile excluded from version control - No Hardcoded Secrets: All credentials loaded from environment
- Secure Communication: HTTPS/WSS connections to VAPI servers
- Permission Handling: Proper microphone permission management
- ✅ API keys stored in environment variables
- ✅
.envfile added to.gitignore - ✅ No sensitive data in source code
- ✅ Secure network connections
- ✅ Proper error handling without exposing internals
- BEGINNER_TUTORIAL.md: Complete line-by-line code explanation
- Flutter Documentation: Official Flutter guides
- VAPI Documentation: VAPI SDK reference
- Dart Language Tour: Dart programming guide
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
If you encounter any issues:
- Check the logs for detailed error messages
- Verify your
.envconfiguration - Ensure stable internet connection
- Check VAPI service status
- Open an issue with detailed information
Built with ❤️ using Flutter and VAPI