Voice-first AI assistant accessible via phone call. Find places, make reservations, get directions - no app required.
- Universal Access - Works on any phone (flip phone, landline, smartphone)
- Google Maps - Real-time place search with ratings, hours, and reviews
- Restaurant Reservations - Detects OpenTable, Resy, and other booking platforms
- Google Gemini AI - Natural conversation with context awareness
- SMS Integration - Booking links, directions, and details sent via text
- Fast - Sub-3 second response times
Phone → Twilio → FastAPI → Gemini AI → Google Maps → SMS
# 1. Clone and install
git clone <your-repo>
cd Call2Map
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Using Make (recommended)
make install
make test
# Or manually
pip install -r requirements.txt
# 2. Configure environment
cp .env.example .env
# Edit .env with your API keys
# 3. Start server
make start
# Or: python main.py
# 4. Start ngrok (separate terminal)
ngrok http 8000
# 5. Update Twilio webhook
# Set to: https://your-ngrok-url.ngrok.io/voice/incoming| Command | Description |
|---|---|
make install |
Install all dependencies |
make test |
Run all tests |
make demo |
Run demo test suite |
make start |
Start the server |
make dev |
Start with hot reload (development) |
make clean |
Remove cache files |
make help |
Show all commands |
| Service | Cost | Get Key |
|---|---|---|
| Twilio | ~$2/month | twilio.com/try-twilio |
| Google Gemini | FREE | aistudio.google.com |
| Google Maps | Free tier | console.cloud.google.com |
Find restaurants:
You: "Find sushi near McGill University"
AI: "I found Kazu, rated 4.5 stars, open until 10 PM..."
Make reservations:
You: "Book a table there"
AI: "You can book online through OpenTable. I've texted you the link."
[SMS with booking URL arrives]
Multi-request:
You: "Where's the nearest ATM?"
AI: "TD Bank, 1410 Rue Peel, 2 blocks away, open 24/7."
Call2Map/
├── main.py # FastAPI server
├── config.py # Environment config
├── requirements.txt # Dependencies
├── .env.example # Config template
├── services/
│ ├── llm_service.py # Google Gemini AI
│ ├── maps_service.py # Google Maps + Reservations
│ └── sms_service.py # Twilio SMS
├── models/
│ └── conversation.py # Session management
├── agents/ # AI agent logic
├── utils/ # Helpers
└── demo/ # Demo scripts & documentation
├── HACKATHON_DEMO.md
├── demo_test.py
└── README.md
- Multi-turn conversations with context
- Natural language understanding via Gemini
- Filters by ratings, hours, distance
- Detects OpenTable, Resy, Tock, SevenRooms
- Sends booking URLs via SMS
- Phone fallback for restaurants without online booking
- Formatted place lists with ratings
- Direct booking links
- Google Maps directions
Monthly (1000 calls):
- Twilio: ~$45
- Gemini: FREE
- Maps API: ~$35
- Total: ~$80
Server won't start:
python demo/demo_test.py # Test all APIsTwilio webhook fails:
- Check ngrok is running:
ngrok http 8000 - Update BASE_URL in
.env - Check Twilio webhook URL matches ngrok
View logs:
- Server: Console output from
python main.py - Twilio: console.twilio.com/monitor/logs/calls
- ngrok: http://127.0.0.1:4040
- demo/HACKATHON_DEMO.md - Complete demo script
- demo/RESERVATION_FEATURE.md - Reservation system docs
- QUICKSTART.md - Detailed setup guide
- TROUBLESHOOTING.md - Common issues
- Backend: FastAPI (Python 3.11+)
- AI: Google Gemini 2.5 Flash
- Maps: Google Maps Places API
- Voice: Twilio Voice + Speech Recognition
- SMS: Twilio Messaging
Hackathon project - feel free to fork and extend!
MIT License
Built for voice-first AI accessibility