{"id":28746752,"url":"https://github.com/essogbe/whatsapp-bot","last_synced_at":"2025-06-16T15:13:03.001Z","repository":{"id":297971744,"uuid":"998447117","full_name":"Essogbe/whatsapp-bot","owner":"Essogbe","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-08T16:48:15.000Z","size":311,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-08T17:34:46.874Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Essogbe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-06-08T16:19:18.000Z","updated_at":"2025-06-08T17:34:04.000Z","dependencies_parsed_at":"2025-06-08T17:44:56.485Z","dependency_job_id":null,"html_url":"https://github.com/Essogbe/whatsapp-bot","commit_stats":null,"previous_names":["essogbe/whatsapp-bot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Essogbe/whatsapp-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Essogbe%2Fwhatsapp-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Essogbe%2Fwhatsapp-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Essogbe%2Fwhatsapp-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Essogbe%2Fwhatsapp-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Essogbe","download_url":"https://codeload.github.com/Essogbe/whatsapp-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Essogbe%2Fwhatsapp-bot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260183301,"owners_count":22971204,"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","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":[],"created_at":"2025-06-16T15:13:02.053Z","updated_at":"2025-06-16T15:13:02.989Z","avatar_url":"https://github.com/Essogbe.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WhatsApp AI Chatbot - Baileys \u0026 FastAPI\n\n\u003e Un chatbot WhatsApp intelligent utilisant Baileys pour la connectivité et FastAPI avec DSPy pour le traitement par IA.\n\n## Comment ça fonctionne\n\nCe projet permet de créer un assistant IA sur WhatsApp qui peut :\n- Répondre intelligemment aux messages privés et en groupe\n- Effectuer des recherches web en temps réel\n- Se souvenir des conversations précédentes\n- Filtrer les contacts autorisés à interagir avec le bot\n\n\nL'architecture est simple : les messages WhatsApp passent par un bot Node.js qui les transmet à une API Python FastAPI. L'IA (DSPy + Mistral) génère les réponses en utilisant l'historique des conversations et peut effectuer des recherches web automatiques. Pour des raisons de sécurité ou autre ( prompt injection, safety  etc), un filtre basique est placé avant et après le module de génération \n\n## Diagramme\n\n```mermaid\nflowchart TD\n    A[🚀 Démarrage Bot WhatsApp] --\u003e B[📋 Chargement variables environnement]\n    B --\u003e C[🔧 Configuration filtres contacts]\n    C --\u003e D[🔐 Initialisation authentification]\n    \n    D --\u003e E{Fichiers auth existants?}\n    E --\u003e|Non| F[📱 Génération QR Code]\n    E --\u003e|Oui| G[🔄 Connexion automatique]\n    \n    F --\u003e H[👤 Scan QR utilisateur]\n    H --\u003e I[✅ Bot connecté]\n    G --\u003e I\n    \n    I --\u003e J[👂 Écoute événements]\n    J --\u003e K[📨 Nouveau message]\n    \n    K --\u003e L{Message du bot?}\n    L --\u003e|Oui| J\n    L --\u003e|Non| M[📋 Extraction contenu]\n    \n    M --\u003e N{Contact dans EXCLUDED?}\n    N --\u003e|Oui| O[🚫 Message ignoré]\n    N --\u003e|Non| P{INCLUDED_ONLY défini?}\n    \n    P --\u003e|Non| Q[✅ Contact autorisé]\n    P --\u003e|Oui| R{Contact dans INCLUDED_ONLY?}\n    R --\u003e|Non| O\n    R --\u003e|Oui| Q\n    \n    Q --\u003e S[📖 Marquer comme lu]\n    S --\u003e T{Conversation privée?}\n    \n    T --\u003e|Oui| U[💬 Traitement direct]\n    T --\u003e|Non| V{Bot mentionné ou commande?}\n    V --\u003e|Non| W[🔇 Ignoré groupe]\n    V --\u003e|Oui| U\n    \n    U --\u003e X[⌨️ Indicateur typing]\n    X --\u003e Y[🚀 Appel FastAPI]\n    Y --\u003e Z[🧠 Traitement IA]\n    \n    Z --\u003e AA[⏱️ Délai simulation]\n    AA --\u003e BB{Succès IA?}\n    BB --\u003e|Non| CC[⚠️ Message erreur]\n    BB --\u003e|Oui| DD{Type conversation?}\n    \n    DD --\u003e|Privé| EE[📤 Message simple]\n    DD --\u003e|Groupe| FF[📤 Message avec mention]\n    \n    EE --\u003e J\n    FF --\u003e J\n    CC --\u003e J\n    O --\u003e J\n    W --\u003e J\n    \n    GG[❌ Déconnexion] --\u003e HH{Raison déconnexion?}\n    HH --\u003e|Logout| II[🛑 Arrêt définitif]\n    HH --\u003e|Autre| JJ[🔄 Reconnexion]\n    JJ --\u003e D\n    \n    I -.-\u003e GG\n    \n    style A fill:#e3f2fd\n    style I fill:#c8e6c9\n    style O fill:#ffcdd2\n    style W fill:#ffcdd2\n    style II fill:#ffcdd2\n    style Z fill:#fff3e0\n    style EE fill:#e8f5e8\n    style FF fill:#e8f5e8\n\n```\n### Aperçu visuel du fonctionnement des  filtres\n\n![alt text](image.png)\n\n## Fonctionnalités\n\n### IA Conversationnelle\n- Moteur DSPy avec Mistral AI (configurable)\n- Recherche web intégrée (Wikipedia + recherche générale)\n- Historique de conversation persistant (SQLite)\n- Validation des entrées/sorties par IA\n\n### Gestion des conversations\n- **Messages privés** : Répond automatiquement\n- **Groupes** : Répond uniquement quand mentionné avec `@` ou aux commandes `/`\n- **Filtrage de contacts** : Listes d'inclusion/exclusion configurables\n\n### Contrôle d'accès\n- **INCLUDED_ONLY** : Liste des numéros autorisés uniquement\n- **EXCLUDED** : Liste des numéros à bloquer complètement\n- Support des formats internationaux avec normalisation automatique\n\n## Structure du projet\n\n```\nwhatsapp-simple-bot/\n├── app.js                    # Bot WhatsApp principal (Node.js)\n├── .env                      # Configuration filtrage contacts\n├── api/                      # API FastAPI (Python)\n│   ├── main.py              # Serveur FastAPI + logique IA\n│   ├── chat_history.db      # Base de données SQLite\n│   ├── requirements.txt     # Dépendances Python\n│   └── .env                 # Variables d'environnement IA\n├── auth_info_baileys/       # Données d'authentification WhatsApp\n└── package.json             # Dépendances Node.js\n```\n\n## Installation\n\n### Prérequis\n- Node.js \n- Python 3\n- Clé API Mistral (ou autre provider LLM)\n\n### Setup\n```bash\ngit clone \u003crepo-url\u003e\ncd whatsapp-simple-bot\n\n# Installation Node.js\nnpm install\n\n# Installation Python\ncd api\npip install -r requirements.txt\n```\n\n### Configuration\n\n**Fichier `api/.env` :**\n```env\nMISTRAL_API_KEY=votre_cle_mistral_api\n```\n\n**Fichier `.env` (filtrage contacts) :**\n\nCette configuration permet de définir à qui le bot doit repondre ou non \n```env\n# Autoriser seulement ces numéros (optionnel)\nINCLUDED_ONLY=+33123456789,+33987654321\n\n# Bloquer ces numéros (optionnel)  \nEXCLUDED=+33111111111,+33222222222\n```\n\n## Démarrage\n\n1. **Lancer l'API FastAPI**\n```bash\ncd api\npython main.py\n```\n\n2. **Lancer le bot WhatsApp**\n```bash\nnode app.js\n```\n\n3. **Authentification WhatsApp**\n   - Scanner le QR code affiché\n   - WhatsApp → Paramètres → Appareils liés → Lier un appareil\n\n## Utilisation\n\n### Messages privés\nLe bot répond automatiquement à tous les messages privés sauf ceux qui provenant de contacts que vous définissez vous-meme\n\n### Messages de groupe\nLe bot répond uniquement quand :\n- Il est mentionné avec `@`\n\n\n### Filtrage de contacts \n\n**Bot personnel (famille/amis uniquement) :**\n```env\nINCLUDED_ONLY=+33123456789,+33987654321\nEXCLUDED=\n```\n\n**Bloquer des spammeurs :**\n```env\nINCLUDED_ONLY=\nEXCLUDED=+33111111111,+33999999999\n```\n\n## Configuration avancée\n\n### Changer de modèle IA\n\nDans `api/main.py` :\n```python\n# Mistral (défaut)\nlm = dspy.LM(\"openai/mistral-small-latest\", api_key=\"...\")\n\n# OpenAI\nlm = dspy.LM(\"gpt-4\", api_key=\"...\")\n\n# Ollama local\nlm = dspy.LM('ollama_chat/llama3', api_base='http://localhost:11434')\n```\n\n## API Endpoints\n\n- `POST /chat` : Traitement des messages\n- `GET /health` : État de l'API\n- `GET /stats` : Statistiques d'usage\n- `DELETE /history/{user_id}` : Effacer l'historique\n\n## Dépannage\n\n**Le bot ne répond pas :**\n1. Vérifier l'API : `curl http://localhost:8000/health`\n2. Contrôler la clé API dans `api/.env`\n3. Consulter les logs\n\n**Problèmes WhatsApp :**\n1. Supprimer le dossier `auth_info_baileys`\n2. Relancer et rescanner le QR code\n\n## Améliorations prévues\n\n- Meilleure organisation des fichiers du projet\n- Endpoints FastAPI\n- Support MCP pour plus de flexibilité et d'interopérabilité\n- Sécurité renforcée avec des filtres avancés ( voire [Guardrails AI](https://github.com/guardrails-ai/guardrails) par exemple  )\n- Langraph pour cas d'usage avancés\n- Transcription audio avec Whisper\n- Recherche Web Avancée\n- Analyse d'images \n- Traitement de documents (PDF, Word)\n- Intégrations Google Calendar/Gmail\n- Recherche sémantique avancée\n- Traitement parallèle de tache chronophage avec RabbitMQ-Celery pour maintenir le bot fonctionnel et notifier lorsqu'une tache est terminée\n\n\n## À propos de Baileys\n\n [Baileys](https://github.com/WhiskeySockets/Baileys) est une bibliothèque TypeScript/JavaScript qui permet d'interagir avec WhatsApp Web via WebSockets. Elle offre une alternative légère aux solutions basées sur Selenium ou l'automatisation de navigateur pour créer des bots et applications WhatsApp.\n\n### Caractéristiques principales\n\n- **Performance optimisée** : Consomme significativement moins de ressources qu'une solution basée navigateur (environ 500 Mo de RAM économisés)\n- **Connexion directe** : Communication via WebSocket avec les serveurs WhatsApp Web\n- **Support multi-appareils** : Compatible avec l'API multi-appareils de WhatsApp\n- **Authentification flexible** : QR code ou code de jumelage pour la connexion\n\n### Fonctionnalités supportées\n\n**Messagerie :**\n- Messages texte, images, vidéos, documents, audio\n- Messages avec mentions et réponses citées\n- Gestion des accusés de réception\n- Indicateurs de présence (\"en train d'écrire\", \"en ligne\")\n\n**Gestion des contacts et groupes :**\n- Informations sur les contacts et groupes\n- Métadonnées des messages (expéditeur, horodatage, etc.)\n- Administration des groupes (ajout/suppression de membres, permissions)\n\n**Authentification et sécurité :**\n- Sessions persistantes avec sauvegarde automatique\n- Reconnexion automatique en cas de déconnexion\n- Gestion des événements de connexion en temps réel\n\n### Installation\n\n```bash\nnpm install @whiskeysockets/baileys\n```\n\n### Note importante\n\nLes mainteneurs découragent l'utilisation de Baileys pour des pratiques violant les conditions d'utilisation de WhatsApp, notamment le spam ou la messagerie automatisée en masse.\n\n## Avertissement\n\n**ATTENTION :** Ce bot utilise l'API non-officielle WhatsApp via Baileys. Une utilisation intensive peut entraîner :\n\n- Bannissement temporaire ou permanent de votre numéro WhatsApp\n- Restrictions des fonctionnalités WhatsApp Business\n- Limitations de débit imposées par WhatsApp\n\n### Recommandations\n- Respectez les délais (max 10-15 messages/minute)\n- Usage personnel/familial recommandé plutôt que commercial\n- Évitez le spam et les sollicitations non désirées\n- Surveillez les logs pour détecter les restrictions\n\n**L'auteur décline toute responsabilité** concernant les bannissements WhatsApp, pertes de données ou violations des conditions d'utilisation résultant de l'usage de ce projet.\n\nEn utilisant ce code, vous acceptez ces risques en connaissance de cause.\n\n## Licence\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fessogbe%2Fwhatsapp-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fessogbe%2Fwhatsapp-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fessogbe%2Fwhatsapp-bot/lists"}