{"id":50840074,"url":"https://github.com/vimalyad/whatsapp_ai_agent","last_synced_at":"2026-06-14T06:06:37.602Z","repository":{"id":322420728,"uuid":"1089417268","full_name":"vimalyad/whatsapp_ai_agent","owner":"vimalyad","description":"FinPal is an intelligent financial planning assistant that operates through WhatsApp, powered by Google's Gemini AI. It helps users achieve their financial goals through personalized guidance, progressive profile building, and educational conversations.","archived":false,"fork":false,"pushed_at":"2025-11-04T10:16:13.000Z","size":39,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-10T18:38:02.411Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vimalyad.png","metadata":{"files":{"readme":"ReadME.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-04T10:10:33.000Z","updated_at":"2025-12-09T03:28:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vimalyad/whatsapp_ai_agent","commit_stats":null,"previous_names":["yamisukehiro2907/whatsapp_ai_agent","vimalyad/whatsapp_ai_agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/vimalyad/whatsapp_ai_agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimalyad%2Fwhatsapp_ai_agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimalyad%2Fwhatsapp_ai_agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimalyad%2Fwhatsapp_ai_agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimalyad%2Fwhatsapp_ai_agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vimalyad","download_url":"https://codeload.github.com/vimalyad/whatsapp_ai_agent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimalyad%2Fwhatsapp_ai_agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34310813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-14T06:06:36.921Z","updated_at":"2026-06-14T06:06:37.584Z","avatar_url":"https://github.com/vimalyad.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FinPal - WhatsApp AI Financial Assistant 💰\n\nFinPal is an intelligent financial planning assistant that operates through WhatsApp, powered by Google's Gemini AI. It helps users achieve their financial goals through personalized guidance, progressive profile building, and educational conversations.\n\n## Features\n\n- 💬 **WhatsApp Integration** - Chat with FinPal directly through WhatsApp using Twilio\n- 🤖 **AI-Powered Guidance** - Uses Google Gemini 2.0 Flash for intelligent financial advice\n- 👤 **User Profile Building** - Progressively learns about users' financial situations\n- 💾 **Conversation History** - Maintains context across sessions using SQLite\n- 📊 **Personalized Advice** - Tailored recommendations based on user profiles\n- 🔒 **Privacy First** - Never asks for sensitive information like account numbers or SSNs\n\n## Prerequisites\n\n- Node.js (v20.x, 22.x, 23.x, or 24.x)\n- A Twilio account with WhatsApp sandbox or approved number\n- Google Gemini API key\n- Basic understanding of webhooks\n\n## Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/yamiSukehiro2907/whatsapp_ai_agent\n   cd whatsapp_ai_agent\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Set up environment variables**\n   \n   Create a `.env` file in the root directory:\n   ```env\n   # Gemini AI Configuration\n   GEMINI_API_KEY=your_gemini_api_key_here\n\n   # Twilio Configuration\n   TWILIO_ACCOUNT_SID1=your_twilio_account_sid\n   TWILIO_AUTH_TOKEN1=your_twilio_auth_token\n   TWILIO_PHONE_NUMBER=whatsapp:+14155238886\n   ```\n\n4. **Initialize the database**\n   ```bash\n   node config/db.js\n   ```\n\n## Configuration\n\n### Getting Your API Keys\n\n**Gemini API Key:**\n1. Visit [Google AI Studio](https://makersuite.google.com/app/apikey)\n2. Create a new API key\n3. Copy and paste it into your `.env` file\n\n**Twilio Credentials:**\n1. Sign up at [Twilio](https://www.twilio.com/)\n2. Go to Console Dashboard\n3. Copy your Account SID and Auth Token\n4. For WhatsApp, set up the [WhatsApp Sandbox](https://www.twilio.com/console/sms/whatsapp/sandbox) or request approval for a production number\n\n### Setting Up Twilio Webhook\n\n1. Start your server (see Usage section)\n2. Use a tool like [ngrok](https://ngrok.com/) to expose your local server:\n   ```bash\n   ngrok http 3000\n   ```\n3. Copy the ngrok HTTPS URL\n4. In Twilio Console → WhatsApp Sandbox Settings, set the webhook URL:\n   ```\n   https://your-ngrok-url.ngrok.io/whatsapp-hook\n   ```\n\n## Usage\n\n1. **Start the server**\n   ```bash\n   node index.js\n   ```\n   \n   You should see:\n   ```\n   ✅ Database and tables created successfully.\n   Server started on http://localhost:3000\n   ```\n\n2. **Connect to WhatsApp**\n   - Send the join code to your Twilio WhatsApp number\n   - Example: `join \u003cyour-sandbox-code\u003e`\n\n3. **Start chatting**\n   - Send any message to FinPal\n   - The AI will greet you and begin learning about your financial situation\n\n## Project Structure\n\n```\nwhatsapp_ai_agent/\n├── config/\n│   ├── db.js              # Database initialization\n│   ├── llm.config.js      # Gemini AI configuration\n│   └── twilio.config.js   # Twilio setup\n├── controllers/\n│   └── chat.controller.js # Main chat logic\n├── routers/\n│   └── chat.route.js      # Express routes\n├── database.js            # Database connection export\n├── index.js               # Application entry point\n├── chat.db                # SQLite database (auto-generated)\n├── package.json           # Project dependencies\n└── .env                   # Environment variables (create this)\n```\n\n## Database Schema\n\n### Users Table\n- `user_id` - Auto-incrementing primary key\n- `phone_number` - Unique user identifier (WhatsApp number)\n- `financial_profile` - JSON object storing user's financial information\n- `created_at` - Timestamp of user registration\n\n### Messages Table\n- `message_id` - Auto-incrementing primary key\n- `user_id` - Foreign key to Users table\n- `sender_role` - Either 'user' or 'ai'\n- `content` - Message text\n- `created_at` - Timestamp of message\n\n## How It Works\n\n1. **Message Receipt**: When a user sends a WhatsApp message, Twilio forwards it to your webhook endpoint\n2. **User Identification**: The system checks if the user exists; if not, creates a new user profile\n3. **Context Loading**: Retrieves the last 10 messages for conversation context\n4. **AI Processing**: Sends the message with context to Gemini AI\n5. **Profile Updates**: Parses AI responses for profile update markers (e.g., `📝 PROFILE_UPDATE: age_range=30s`)\n6. **Database Storage**: Saves both user and AI messages\n7. **Response Delivery**: Sends AI response back to user via Twilio\n\n## FinPal's Capabilities\n\nFinPal provides guidance on:\n- 🎯 Goal setting (short, medium, and long-term)\n- 💰 Budgeting strategies\n- 💳 Debt management (avalanche vs snowball methods)\n- 🏦 Emergency fund building\n- 📈 Investment principles (NOT specific stocks/funds)\n- 🔄 Asset allocation concepts\n- 📊 Risk tolerance assessment\n\n## Important Disclaimers\n\n⚠️ **FinPal is educational only** - Every response includes: \"💡 Note: This is educational information, not professional financial advice.\"\n\n🚫 **What FinPal NEVER does:**\n- Request sensitive data (SSN, account numbers, passwords)\n- Recommend specific stocks, bonds, or cryptocurrencies\n- Recommend specific mutual funds or ETFs by name\n- Provide exact dollar amounts for specific investments\n\n## Customization\n\n### Modifying AI Behavior\n\nEdit `config/llm.config.js` to change:\n- System instructions\n- Conversation approach\n- Question strategy\n- Profile information to collect\n\n### Changing Conversation History Length\n\nIn `controllers/chat.controller.js`, modify this line:\n```javascript\n\"SELECT sender_role, content FROM Messages WHERE user_id = ? ORDER BY created_at DESC LIMIT 10\"\n```\nChange `LIMIT 10` to your preferred number.\n\n## Troubleshooting\n\n**Database not initializing:**\n```bash\nnode config/db.js\n```\n\n**Twilio webhook not receiving messages:**\n- Check ngrok is running\n- Verify webhook URL in Twilio console\n- Ensure HTTPS (not HTTP) URL\n\n**AI not responding:**\n- Verify GEMINI_API_KEY is correct\n- Check API quota limits\n- Review console logs for errors\n\n**Profile updates not saving:**\n- Check that AI responses include `📝 PROFILE_UPDATE:` markers\n- Verify database write permissions\n\n## API Rate Limits\n\n- **Gemini API**: Check your tier limits at [Google AI Studio](https://ai.google.dev/pricing)\n- **Twilio**: Free trial has message limits; upgrade for production use\n\n## Security Considerations\n\n- Never commit `.env` file to version control\n- Use environment variables for all secrets\n- Implement rate limiting for production\n- Consider adding authentication for webhook endpoint\n- Review and sanitize user inputs\n\n## Future Enhancements\n\nPotential improvements:\n- [ ] Add conversation analytics\n- [ ] Implement multi-language support\n- [ ] Create web dashboard for profile viewing\n- [ ] Add scheduled financial tips/reminders\n- [ ] Implement conversation export feature\n- [ ] Add voice message support\n\n## Dependencies\n\nKey packages:\n- **express**: Web server framework\n- **@google/genai**: Google Gemini AI SDK\n- **twilio**: WhatsApp/SMS integration\n- **better-sqlite3**: Fast SQLite database\n- **body-parser**: Parse incoming request bodies\n- **dotenv**: Environment variable management\n\n## Contributing\n\nContributions are welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Submit a pull request\n\n## Acknowledgments\n\n- **Google Gemini** for AI capabilities\n- **Twilio** for WhatsApp integration\n- **better-sqlite3** for reliable local storage\n\n---\n\n**Built with ❤️ for financial education and empowerment**\n\n*Remember: FinPal is an educational tool. Always consult licensed financial professionals for personalized advice.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvimalyad%2Fwhatsapp_ai_agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvimalyad%2Fwhatsapp_ai_agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvimalyad%2Fwhatsapp_ai_agent/lists"}