README.md

---
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