You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
109 lines
2.9 KiB
Markdown
109 lines
2.9 KiB
Markdown
# Task WhatsApp Chatbot
|
|
|
|
A WhatsApp chatbot for task management, designed to work with Evolution API in a secure internal network environment.
|
|
|
|
## 📌 Overview
|
|
This service provides a WhatsApp interface for task management within WhatsApp groups. It:
|
|
- Listens for `/tarea` commands in WhatsApp groups
|
|
- Stores tasks in a SQLite database
|
|
- Manages user permissions and group membership
|
|
- Integrates with Evolution API for WhatsApp connectivity
|
|
|
|
## 🔐 Security Model
|
|
- **Internal Networking**: The webhook only accepts connections from Evolution API via internal Docker networking
|
|
- **Environment Variables**: Sensitive configuration is managed through environment variables
|
|
- **Group Restrictions**: Only operates within pre-approved WhatsApp groups
|
|
- **Input Validation**: Sanitizes and validates all user inputs
|
|
|
|
## 🧱 Architecture
|
|
```mermaid
|
|
graph TD
|
|
A[Webhook Received] --> B{Valid Payload?}
|
|
B -->|No| C[Ignore]
|
|
B -->|Yes| D{From Known Group?}
|
|
D -->|Yes| E[Update User Last Seen]
|
|
D -->|No| F{Private Chat + Known User?}
|
|
F -->|No| C
|
|
F -->|Yes| E
|
|
E --> G{/tarea Command?}
|
|
G -->|No| C
|
|
G -->|Yes| H{New User?}
|
|
H -->|Yes| I[Add to DB]
|
|
H -->|No| J[Process Command]
|
|
```
|
|
|
|
## ✅ Current Features
|
|
- Task creation with optional due dates
|
|
- Basic command parsing (`/tarea nueva`, `/tarea mostrar`)
|
|
- Group membership tracking
|
|
- SQLite database persistence
|
|
- Health check endpoint
|
|
- Environment validation
|
|
- Input validation for dates and commands
|
|
|
|
## 🛠️ Setup
|
|
### Environment Variables
|
|
```env
|
|
EVOLUTION_API_URL=http://evolution-api:3000
|
|
EVOLUTION_API_KEY=your-api-key
|
|
EVOLUTION_API_INSTANCE=main
|
|
WHATSAPP_COMMUNITY_ID=your-community-id
|
|
CHATBOT_PHONE_NUMBER=1234567890
|
|
WEBHOOK_URL=https://your-webhook.com
|
|
PORT=3007
|
|
NODE_ENV=production
|
|
```
|
|
|
|
### Development Setup
|
|
```bash
|
|
# Install dependencies
|
|
bun install
|
|
|
|
# Start development server
|
|
bun run dev
|
|
|
|
# Run tests
|
|
bun test
|
|
```
|
|
|
|
## 📅 Roadmap
|
|
### High Priority
|
|
- [ ] Implement ResponseQueue processing logic with retries
|
|
- [ ] Add database schema validation and migrations
|
|
- [ ] Add error recovery with transaction rollback
|
|
- [ ] Implement group sync delta updates
|
|
|
|
### Medium Priority
|
|
- [ ] Add task assignment and ownership
|
|
- [ ] Implement user permissions system
|
|
- [ ] Add rate limiting for API calls
|
|
- [ ] Create task history tracking
|
|
|
|
### Low Priority
|
|
- [ ] Add task reminders system
|
|
- [ ] Implement multi-language support
|
|
- [ ] Create analytics dashboard
|
|
- [ ] Add user-friendly task list UI
|
|
|
|
## 🧪 Testing
|
|
### Running Tests
|
|
```bash
|
|
bun test
|
|
```
|
|
|
|
### Test Coverage
|
|
- Webhook validation
|
|
- Command parsing
|
|
- Environment checks
|
|
- Basic error handling
|
|
- Input validation
|
|
|
|
## 🧑💻 Contributing
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Add tests for new functionality
|
|
4. Submit a pull request
|
|
|
|
## 📚 Documentation
|
|
For detailed API documentation and architecture decisions, see the [docs/](docs/) directory.
|