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

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

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

# 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

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/ directory.