| --- |
| title: PropAgent |
| emoji: 🤖 |
| colorFrom: blue |
| colorTo: purple |
| sdk: docker |
| pinned: false |
| short_description: WhatsApp AI Agent with Supabase integration |
| --- |
| |
| # PropAgent - WhatsApp AI Agent |
|
|
| A WhatsApp chatbot powered by OpenAI GPT-4 and integrated with Supabase for user management. |
|
|
| ## Features |
|
|
| - 🤖 AI-powered chat responses using OpenAI GPT-4 |
| - 📱 WhatsApp Business API integration |
| - 👥 User management with Supabase database |
| - 🔄 Conversation memory and context |
| - 📊 User activity tracking |
| - 🚀 RESTful API endpoints for user management |
|
|
| ## Setup |
|
|
| ### 1. Environment Variables |
|
|
| Create a `.env` file with the following variables: |
|
|
| ```bash |
| # WhatsApp Business API |
| VERIFY_TOKEN=your_webhook_verify_token |
| PHONE_NUMBER_ID=your_phone_number_id |
| WHATSAPP_API_TOKEN=your_whatsapp_api_token |
| |
| # OpenAI |
| OPENAI_API_KEY=your_openai_api_key |
| |
| # Supabase |
| SUPABASE_URL=your_supabase_project_url |
| SUPABASE_KEY=your_supabase_anon_key |
| ``` |
|
|
| ### 2. Supabase Setup |
|
|
| 1. Create a new Supabase project at [supabase.com](https://supabase.com) |
| 2. Go to the SQL Editor in your Supabase dashboard |
| 3. Run the SQL script from `supabase_setup.sql` to create the users table |
| 4. Copy your project URL and anon key from Settings > API |
|
|
| ### 3. WhatsApp Business API Setup |
|
|
| 1. Create a Meta Developer account |
| 2. Set up a WhatsApp Business app |
| 3. Configure webhook URL: `https://your-domain.com/webhook` |
| 4. Set the verify token in your environment variables |
|
|
| ### 4. Installation |
|
|
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| ### 5. Running the Application |
|
|
| ```bash |
| uvicorn main:app --host 0.0.0.0 --port 8000 |
| ``` |
|
|
| ## API Endpoints |
|
|
| ### Webhook Endpoints |
| - `GET /webhook` - WhatsApp webhook verification |
| - `POST /webhook` - Receive WhatsApp messages |
|
|
| ### User Management |
| - `GET /users/{wa_id}` - Get user by WhatsApp ID |
| - `GET /users` - List all users (with pagination) |
| - `PUT /users/{wa_id}` - Update user name |
|
|
| ### Health & Testing |
| - `GET /ping` - Simple health check |
| - `GET /health` - Detailed service status |
| - `POST /chat` - Direct AI chat endpoint |
|
|
| ## Database Schema |
|
|
| ### Users Table |
| ```sql |
| users |
| ----- |
| - wa_id (TEXT, PRIMARY KEY) - WhatsApp user ID |
| - name (TEXT) - User's display name |
| - created_at (TIMESTAMP) - Account creation time |
| - updated_at (TIMESTAMP) - Last activity time |
| ``` |
|
|
| ## Features |
|
|
| ### User Management |
| - Automatic user creation when first message is received |
| - User name updates from WhatsApp profile |
| - Activity tracking with automatic timestamp updates |
|
|
| ### AI Chat |
| - Context-aware conversations using user names |
| - Conversation memory (last 6 messages) |
| - Error handling and fallback responses |
|
|
| ### Security |
| - Environment variable configuration |
| - Optional Row Level Security (RLS) in Supabase |
| - Input validation and error handling |
|
|
| ## Project Structure |
|
|
| ``` |
| PropAgent/ |
| ├── main.py # Main application entry point |
| ├── config.py # Configuration and client setup |
| ├── database.py # Supabase database operations |
| ├── whatsapp.py # WhatsApp API integration |
| ├── ai_chat.py # LangGraph AI conversation logic |
| ├── api_routes.py # FastAPI route definitions |
| ├── supabase_setup.sql # Database schema setup |
| └── requirements.txt # Python dependencies |
| ``` |
|
|
| ## Development |
|
|
| The application uses a modular architecture: |
| - **main.py** - Clean entry point focusing on core webhook logic |
| - **config.py** - Environment variables and client initialization |
| - **database.py** - All Supabase database operations |
| - **whatsapp.py** - WhatsApp Business API integration |
| - **ai_chat.py** - LangGraph conversation flow and AI processing |
| - **api_routes.py** - REST API endpoints and webhook verification |
|
|
| **Technologies:** |
| - **FastAPI** for the web framework |
| - **LangGraph** for conversation flow management |
| - **OpenAI GPT-4** for AI responses |
| - **Supabase** for user data storage |
| - **WhatsApp Business API** for messaging |
|
|
| ## Deployment |
|
|
| The application includes a Dockerfile for containerized deployment. You can deploy it to: |
| - Hugging Face Spaces |
| - Railway |
| - Heroku |
| - Any container platform |
|
|
| ## License |
|
|
| MIT License |
|
|
