{"id":30197653,"url":"https://github.com/t0mer/greenapi-n8n-router","last_synced_at":"2025-08-13T06:35:43.188Z","repository":{"id":293683585,"uuid":"984820077","full_name":"t0mer/greenapi-n8n-router","owner":"t0mer","description":"A lightweight Python-based relay that connects Green-API WhatsApp messages to dynamic n8n webhook URLs based on chat IDs.","archived":false,"fork":false,"pushed_at":"2025-08-10T11:57:32.000Z","size":91,"stargazers_count":8,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-10T12:29:01.580Z","etag":null,"topics":["automation","green-api","n8n","n8n-webhook","python"],"latest_commit_sha":null,"homepage":"https://medium.com/@tomer.klein","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/t0mer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-05-16T15:02:18.000Z","updated_at":"2025-08-10T11:57:36.000Z","dependencies_parsed_at":"2025-08-10T12:16:19.414Z","dependency_job_id":"6f5af268-d4e7-4f84-bb57-c1d217ef13a0","html_url":"https://github.com/t0mer/greenapi-n8n-router","commit_stats":null,"previous_names":["t0mer/greenapi-n8n-router"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/t0mer/greenapi-n8n-router","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t0mer%2Fgreenapi-n8n-router","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t0mer%2Fgreenapi-n8n-router/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t0mer%2Fgreenapi-n8n-router/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t0mer%2Fgreenapi-n8n-router/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/t0mer","download_url":"https://codeload.github.com/t0mer/greenapi-n8n-router/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t0mer%2Fgreenapi-n8n-router/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270196775,"owners_count":24543454,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"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":["automation","green-api","n8n","n8n-webhook","python"],"created_at":"2025-08-13T06:34:34.862Z","updated_at":"2025-08-13T06:35:37.785Z","avatar_url":"https://github.com/t0mer.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Green API n8n Router\n\nA powerful WhatsApp message router that forwards incoming messages to multiple n8n webhook endpoints with a beautiful web management interface.\n\n![Green API n8n Router](https://img.shields.io/badge/WhatsApp-Router-25D366?style=for-the-badge\u0026logo=whatsapp)\n![Python](https://img.shields.io/badge/Python-3.8+-3776AB?style=for-the-badge\u0026logo=python)\n![FastAPI](https://img.shields.io/badge/FastAPI-Web%20Interface-009688?style=for-the-badge\u0026logo=fastapi)\n![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge\u0026logo=docker)\n\n## ✨ Features\n\n### 🌐 **Modern Web Interface**\n- **Visual Dashboard**: Trello-like card interface for managing routes\n- **Real-time Logging**: Live WebSocket-based log viewer with drag-and-drop positioning\n- **Responsive Design**: Works perfectly on desktop, tablet, and mobile devices\n- **Dark/Light Theme**: Professional UI with smooth animations\n\n### 🔄 **Smart Routing System**\n- **Multiple Webhooks**: Route single chat to multiple webhook endpoints\n- **Dynamic Configuration**: Hot-reload configuration without restart\n- **Route Management**: Add, edit, delete routes through the web interface\n- **Bulk Operations**: Manage multiple webhook URLs per chat ID\n\n### ⚡ **Advanced Features**\n- **Bot-Only Restart**: Restart WhatsApp bot without affecting web interface\n- **Environment Detection**: Automatic Docker/native environment detection\n- **Health Monitoring**: Built-in health check endpoints\n- **Error Handling**: Comprehensive error handling with retry logic\n- **Cross-Platform**: Works on Windows, Linux, macOS, and Docker\n\n### 🛠️ **Developer Experience**\n- **API-First**: RESTful API for all operations\n- **WebSocket Logs**: Real-time log streaming to web interface\n- **Configuration Watching**: Automatic reload on config file changes\n- **Type Safety**: Full TypeScript-like type hints in Python\n\n## 🚀 Quick Start\n\n### Option 1: Docker Compose (Recommended)\n\n1. **Create the docker-compose.yml file:**\n\n```yaml\nversion: '3.8'\nservices:\n  greenapi-n8n-router:\n    image: techblog/greenapi-n8n-router\n    container_name: greenapi-n8n-router\n    volumes:\n      - ./app/config/:/app/config/\n    restart: unless-stopped\n    ports:\n      - \"8000:8000\"\n```\n\n2. **Start the application:**\n\n```bash\n# Start the container\ndocker-compose up -d\n\n# View logs (optional)\ndocker-compose logs -f greenapi-n8n-router\n```\n\n**Note:** An empty configuration file will be automatically created on first startup at `app/config/config.yaml`. You can then configure your Green API credentials and routes through the web interface.\n\n3. **Access the web interface:**\n\nOpen your browser and navigate to `http://localhost:8000`\n\n### Option 2: Docker Run\n\n```bash\n# Create config directory\nmkdir -p app/config\n\n# Run the container\ndocker run -d \\\n  --name greenapi-n8n-router \\\n  -p 8000:8000 \\\n  -v $(pwd)/app/config:/app/config \\\n  --restart unless-stopped \\\n  techblog/greenapi-n8n-router\n```\n\n**Note:** An empty configuration file will be automatically created on first startup. Configure your settings through the web interface at `http://localhost:8000`.\n\n### Option 3: Build from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/t0mer/greenapi-n8n-router.git\ncd greenapi-n8n-router\n\n# Build and run with Docker Compose\ndocker-compose up -d --build\n```\n\n### Option 4: Native Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/t0mer/greenapi-n8n-router.git\ncd greenapi-n8n-router/app\n\n# Install dependencies\npip install -r requirements.txt\n\n# Start the application\npython app.py\n```\n\n## 📋 Configuration\n\nEdit `app/config/config.yaml`:\n\n```yaml\ngreen_api:\n  instance_id: 'YOUR_INSTANCE_ID'\n  token: 'YOUR_TOKEN_HERE'\n\nroutes:\n  # Single webhook per chat\n  972523531857@c.us:\n    - https://your-n8n.example.com/webhook/chat1\n  \n  # Multiple webhooks for the same chat\n  972501234567@c.us:\n    - https://n8n-primary.example.com/webhook/support\n    - https://n8n-backup.example.com/webhook/support\n    - https://analytics.example.com/webhook/tracking\n  \n  # Group chat routing\n  120363025623@g.us:\n    - https://n8n.example.com/webhook/group-notifications\n    - https://slack-integration.example.com/webhook/groups\n```\n\n### Configuration Options\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `green_api.instance_id` | Your Green API instance ID | `7103251345` |\n| `green_api.token` | Your Green API token | `c4e60a46f75f...` |\n| `routes` | Chat ID to webhook URL mappings | See examples above |\n\n## 🎯 Usage\n\n### 1. **Access Web Interface**\nNavigate to `http://localhost:8000` to access the management dashboard.\n\n### 2. **Configure Green API Settings**\n- Click the \"⚙️ Settings\" button\n- Enter your Instance ID and Token\n- Click \"Update \u0026 Restart\" - only the bot component restarts\n\n### 3. **Manage Routes**\n- **Add Route**: Click the \"+\" card to create new routes\n- **Edit Route**: Click on any route card to view/edit details\n- **Multiple Webhooks**: Add multiple webhook URLs per chat\n- **Delete Route**: Use the 🗑️ button to remove routes\n\n### 4. **Monitor Activity**\n- Click \"Show Logger\" to view real-time logs\n- Drag the logger window to reposition it\n- See live message forwarding activity\n\n## 🔧 Container Management\n\n### Docker Compose Commands\n\n```bash\n# Start the service\ndocker-compose up -d\n\n# Stop the service\ndocker-compose down\n\n# Restart the service\ndocker-compose restart\n\n# View logs\ndocker-compose logs -f greenapi-n8n-router\n\n# Update to latest image\ndocker-compose pull\ndocker-compose up -d\n\n# Check service status\ndocker-compose ps\n```\n\n### Configuration Updates\n\nAfter modifying `app/config/config.yaml`:\n\n```bash\n# Restart only the bot component (recommended)\ncurl -X POST http://localhost:8000/restart\n\n# Or restart the entire container\ndocker-compose restart greenapi-n8n-router\n```\n\n## 🔧 API Reference\n\n### Core Endpoints\n\n#### Get All Routes\n```http\nGET /routes\n```\n\n#### Add New Route\n```http\nPOST /routes\nContent-Type: application/json\n\n{\n  \"chat_id\": \"972523531857@c.us\",\n  \"target_urls\": [\n    \"https://n8n.example.com/webhook/chat1\",\n    \"https://backup.example.com/webhook/chat1\"\n  ]\n}\n```\n\n#### Update Route\n```http\nPUT /routes/{chat_id}\nContent-Type: application/json\n\n{\n  \"chat_id\": \"972523531857@c.us\",\n  \"target_urls\": [\n    \"https://n8n.example.com/webhook/updated\"\n  ]\n}\n```\n\n#### Delete Route\n```http\nDELETE /routes/{chat_id}\n```\n\n#### Update Settings\n```http\nPOST /settings\nContent-Type: application/json\n\n{\n  \"instance_id\": \"your_instance_id\",\n  \"token\": \"your_token\"\n}\n```\n\n#### Restart Bot\n```http\nPOST /restart\n```\n\n#### Health Check\n```http\nGET /health\n```\n\n### WebSocket Endpoints\n\n#### Live Logs\n```javascript\nconst ws = new WebSocket('ws://localhost:8000/ws/logs');\nws.onmessage = (event) =\u003e {\n  const logData = JSON.parse(event.data);\n  console.log(`[${logData.timestamp}] ${logData.level}: ${logData.message}`);\n};\n```\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   WhatsApp      │    │  Green API       │    │  Router App     │\n│   Messages      │───▶│  Webhook         │───▶│  (FastAPI)      │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n                                                        │\n                                                        ▼\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   n8n Instance  │    │   n8n Instance   │    │  n8n Instance   │\n│   Webhook #1    │◀───│   Webhook #2     │◀───│  Webhook #3     │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n```\n\n### Components\n\n- **WhatsApp Bot**: Handles incoming messages via Green API\n- **Web Interface**: FastAPI-based management dashboard\n- **Router Engine**: Forwards messages to configured webhooks\n- **Configuration Manager**: Hot-reload configuration system\n- **Logger**: Real-time WebSocket logging system\n\n## 🐳 Docker Support\n\n```yaml\nversion: '3.8'\nservices:\n  greenapi-n8n-router:\n    image: techblog/greenapi-n8n-router\n    container_name: greenapi-n8n-router\n    volumes:\n      - ./app/config/config.yaml:/app/config/config.yaml\n    restart: unless-stopped\n    ports:\n      - \"8000:8000\"\n    environment:\n      - PYTHONUNBUFFERED=1\n    healthcheck:\n      test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8000/health\"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n      start_period: 40s\n```\n\n\n## 🛠️ Development\n\n### Project Structure\n```\ngreenapi-n8n-router/\n├── app/\n│   ├── app.py                 # Main application entry point\n│   ├── web_manager.py         # FastAPI web interface\n│   ├── config_loader.py       # Configuration management\n│   ├── config_watcher.py      # Hot-reload configuration\n│   ├── restart_app.py         # Bot restart utility\n│   ├── requirements.txt       # Python dependencies\n│   ├── static/\n│   │   ├── css/routes.css     # Stylesheet\n│   │   └── js/routes.js       # Frontend JavaScript\n│   ├── templates/\n│   │   └── routes.html        # Main web interface\n│   └── config/\n│       └── config.yaml        # Configuration file\n├── docker-compose.yml\n├── Dockerfile\n└── README.md\n```\n\n### Key Features Implementation\n\n#### 1. **Bot-Only Restart**\nThe application separates the WhatsApp bot and web server, allowing bot restarts without affecting the web interface:\n\n```python\ndef restart_bot_component():\n    \"\"\"Restart only the bot component.\"\"\"\n    global bot, bot_thread\n    \n    # Stop existing bot\n    bot = None\n    bot_thread = None\n    \n    # Reload config and restart bot\n    config = load_config(CONFIG_PATH)\n    bot = initialize_bot()\n    bot_thread = start_bot_thread(bot)\n```\n\n#### 2. **Real-time Logging**\nWebSocket-based logging provides instant feedback:\n\n```javascript\nconnectWebSocket() {\n    const ws = new WebSocket('ws://localhost:8000/ws/logs');\n    ws.onmessage = (event) =\u003e {\n        const logData = JSON.parse(event.data);\n        this.addLogEntry(logData.message, logData.level);\n    };\n}\n```\n\n#### 3. **Hot Configuration Reload**\nAutomatic configuration reloading without restart:\n\n```python\ndef reload_config(new_config):\n    global config\n    old_credentials = (config[\"green_api\"][\"instance_id\"], config[\"green_api\"][\"token\"])\n    new_credentials = (new_config[\"green_api\"][\"instance_id\"], new_config[\"green_api\"][\"token\"])\n    \n    config = new_config\n    \n    if old_credentials != new_credentials:\n        restart_bot_component()  # Only restart bot if credentials changed\n```\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n#### Port Already in Use\n```bash\n# Check what's using port 8000\nsudo lsof -i :8000\n\n# Kill the process\nsudo kill -9 \u003cPID\u003e\n\n# Or use different port in docker-compose.yml\nports:\n  - \"8001:8000\"  # Use port 8001 instead\n```\n\n#### Configuration Issues\n```bash\n# Check if config file exists and is valid\ncat app/config/config.yaml\n\n# Validate YAML syntax\npython -c \"import yaml; yaml.safe_load(open('app/config/config.yaml'))\"\n\n# Check container logs\ndocker-compose logs greenapi-n8n-router\n```\n\n#### Bot Restart\n```bash\n# Manual bot restart via API\ncurl -X POST http://localhost:8000/restart\n\n# Restart entire container\ndocker-compose restart greenapi-n8n-router\n\n# Check health status\ncurl http://localhost:8000/health\n```\n\n#### Docker Issues\n```bash\n# View container logs\ndocker-compose logs -f greenapi-n8n-router\n\n# Restart container\ndocker-compose restart greenapi-n8n-router\n\n# Rebuild and restart\ndocker-compose down\ndocker-compose pull\ndocker-compose up -d\n\n# Check container status\ndocker-compose ps\n```\n\n#### Green API Issues\n- Ensure `instance_id` and `token` are correct\n- Verify Green API account is active\n- Check webhook URLs are accessible from the internet\n- Test webhooks manually with curl/Postman\n\n## 📝 Requirements\n\n### System Requirements\n- Docker and Docker Compose\n- 1GB RAM minimum\n- Network access to Green API and target webhooks\n- Modern web browser for management interface\n\n### Python Dependencies (for development)\n```\nfastapi\u003e=0.104.1\nuvicorn\u003e=0.24.0\nwhatsapp-chatbot-python\u003e=0.0.5\nhttpx\u003e=0.25.0\npydantic\u003e=2.4.2\npython-multipart\u003e=0.0.6\njinja2\u003e=3.1.2\npyyaml\u003e=6.0.1\nloguru\u003e=0.7.2\nwatchdog\u003e=3.0.0\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Green API](https://green-api.com/) for WhatsApp Business API\n- [n8n](https://n8n.io/) for workflow automation\n- [FastAPI](https://fastapi.tiangolo.com/) for the web framework\n- [SweetAlert2](https://sweetalert2.github.io/) for beautiful alerts\n\n## 📞 Support\n\n- 🐛 Issues: [GitHub Issues](https://github.com/t0mer/greenapi-n8n-router/issues)\n\n---\n\nMade with ❤️ for the automation community\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft0mer%2Fgreenapi-n8n-router","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ft0mer%2Fgreenapi-n8n-router","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft0mer%2Fgreenapi-n8n-router/lists"}