Chargement des sessions...

Session

Destinataire (JID ou numéro)

Type de message

Message

Historique des messages

📌 Importez un fichier CSV ou Excel avec les colonnes phone et name. Utilisez {name} dans le message pour personnaliser.

Session

Fichier contacts (CSV ou XLSX)

Message (utilisez {name} pour personnaliser)

Média (optionnel)

Délai entre messages (ms) — min 1000ms anti-ban

Session

Destinataire (JID/numéro)

Message

Média (optionnel)

Date & heure

Expression cron Format: minute heure jour mois jour-semaine

Messages planifiés

Session

Sélectionnez une session

Session

Vérifier un numéro

👁️ Les images et vidéos en vue unique sont automatiquement capturées et renvoyées sur votre numéro.

Aucun média capturé pour le moment

🎮 Les jeux se jouent directement dans WhatsApp. Envoyez !aide dans n'importe quel chat pour voir les commandes.

🎯

Trivia

!trivia

🔤

Pendu

!pendu

🔢

Devine le nombre

!nombre

✂️

Pierre Feuille Ciseaux

!pfc

🎮

Morpion

!morpion @joueur

🔀

Anagramme

!anagramme

✅

Vrai ou Faux

!vf

Parties actives

Aucune partie en cours

🏆 Classement global

📱

BotWA Documentation

Automatisation WhatsApp avec Baileys · Node.js · Express · Socket.io

🚀 Démarrage rapide

BotWA est un serveur d'automatisation WhatsApp. Il expose une API REST + un dashboard temps réel pour gérer plusieurs comptes WhatsApp simultanément.

Installation

git clone ...
cd botwa
npm install
cp .env.example .env        # Configurer les variables
npm run dev                 # Lancer en développement

Variables d'environnement

Variable	Défaut	Description
`PORT`	`3000`	Port du serveur HTTP
`OWN_PHONE_NUMBER`	—	Votre numéro pour recevoir les vues uniques (ex: `33612345678`)
`SESSIONS_DIR`	`./sessions`	Dossier de sauvegarde des sessions Baileys
`UPLOADS_DIR`	`./uploads`	Dossier des fichiers uploadés
`MEDIA_DIR`	`./media`	Dossier des médias vue-unique capturés
`GAMES_ENABLED`	`true`	Activer les jeux WhatsApp
`NODE_ENV`	`development`	`production` désactive les logs debug

💡 Le serveur est accessible sur http://localhost:3000. Toutes les routes API commencent par /api/. Le dashboard est servi à la racine /.

🔌 Sessions WhatsApp

Une session représente un compte WhatsApp connecté. Vous pouvez en avoir plusieurs simultanément (multi-comptes).

Créer une session

Cliquez sur + Nouvelle session
Entrez un nom unique (lettres et chiffres uniquement)
Un QR code apparaît automatiquement dans le dashboard
Ouvrez WhatsApp → Appareils liés → Lier un appareil
Scannez le QR — la session passe à l'état connecté

États d'une session

État	Signification
qr	En attente du scan du QR code
connecting	Connexion en cours
connected	Session active et opérationnelle
reconnecting	Reconnexion automatique en cours (max 5 tentatives)
disconnected	Déconnecté (délogué ou erreur)

⚠️ Les sessions sont persistées dans le dossier sessions/. Ne supprimez pas ce dossier, sinon vous devrez rescanner le QR.

💬 Messages

Envoyez tous types de messages WhatsApp depuis le dashboard ou via l'API.

Format du destinataire (JID)

Le dashboard accepte le numéro brut ou le JID complet :

33612345678              → converti en 33612345678@s.whatsapp.net
33612345678@s.whatsapp.net  → utilisé tel quel
120363XXXXXX@g.us           → JID de groupe

Types de messages supportés

Type	Champ `type`	Paramètres requis
💬 Texte	`text`	`text`
🖼️ Image	`image`	fichier image + `caption` (optionnel)
🎥 Vidéo	`video`	fichier vidéo + `caption` (optionnel)
🎵 Audio	`audio`	fichier audio + `ptt` (push-to-talk)
📄 Document	`document`	tout fichier
📍 Localisation	`location`	`latitude`, `longitude`, `name`
👤 Contact	`contact`	`name`, `phone`, `organization`

📤 Envoi en masse

Envoyez un message à une liste de contacts depuis un fichier CSV ou Excel.

Format du fichier CSV

phone,name
33612345678,Jean Dupont
33698765432,Marie Martin
33611223344,Paul Durand

Format Excel (.xlsx)

Colonnes acceptées : phone ou numero, name ou nom.

Personnalisation du message

Utilisez {name} dans le message pour insérer le nom du contact :

Bonjour {name}, votre commande est prête !

⚠️ Anti-ban : le délai minimum entre chaque message est de 1000ms. Recommandé : 3000ms à 5000ms pour les grandes listes.

⏰ Planificateur

Envoyez des messages à une date précise ou de façon récurrente via des expressions cron.

Message unique

Sélectionnez "Une seule fois" et choisissez une date/heure. Le message est envoyé exactement à l'heure indiquée.

Message récurrent (Cron)

Sélectionnez "Récurrent" et entrez une expression cron :

Expression	Signification
`0 9 * * *`	Tous les jours à 9h00
`0 9 * * 1-5`	Lundi au vendredi à 9h00
`0 /2 * *`	Toutes les 2 heures
`0 9 1 * *`	Le 1er de chaque mois à 9h00
`30 12 * * 5`	Chaque vendredi à 12h30

Format : minute heure jour-du-mois mois jour-de-semaine

👥 Groupes

Gérez vos groupes WhatsApp directement depuis le dashboard.

Action	Description
Créer un groupe	Nom + liste de numéros (un par ligne)
Lister les groupes	Affiche tous les groupes de la session
Lien d'invitation	Génère un lien `chat.whatsapp.com/...`
Ajouter/Retirer	Participants via l'API
Promouvoir/Rétrograder	Passer admin ou retirer les droits
Quitter	Quitter le groupe

📋 Contacts

Vérifiez si un numéro est sur WhatsApp et consultez les profils.

Vérifier un numéro

Entrez un numéro (ex: 33612345678) et cliquez Vérifier. La réponse indique si le numéro existe sur WhatsApp et son JID.

Profil d'un contact

Via l'API GET /api/contacts/:sessionId/profile/:jid — retourne la photo de profil et le statut.

👁️ Vue Unique

BotWA intercepte automatiquement les messages en vue unique (images et vidéos) que vous recevez.

Comment ça fonctionne

Quelqu'un vous envoie une image ou vidéo en vue unique
BotWA la télécharge et la sauvegarde dans media/
Le dashboard est notifié en temps réel (badge sur l'icône)
Le média est automatiquement renvoyé sur votre numéro (OWN_PHONE_NUMBER)

💡 Configurez OWN_PHONE_NUMBER dans .env pour recevoir automatiquement les médias capturés sur votre WhatsApp.

Wrappers WhatsApp supportés

viewOnceMessage           (ancienne version)
viewOnceMessageV2         (version intermédiaire)
viewOnceMessageV2Extension (version actuelle)
ephemeralMessage > viewOnceMessage

🎮 Jeux WhatsApp

Les jeux se jouent entièrement dans WhatsApp via des commandes texte. Envoyez !aide dans n'importe quel chat pour afficher l'aide.

Jeu	Lancer	Jouer	Multi-joueur
🎯 Trivia	`!trivia [easy\|medium\|hard]`	`!r A/B/C/D`	✅ Groupe
🔤 Pendu	`!pendu`	`!l X` (lettre)	✅ Groupe
🔢 Nombre	`!nombre`	`!n 42`	✅ Groupe
✂️ Pierre Feuille Ciseaux	`!pfc pierre`	—	❌ Solo vs Bot
🎮 Morpion	`!morpion @joueur`	`!move 1-9`	✅ 2 joueurs
🔀 Anagramme	`!anagramme`	`!a mot`	✅ Groupe
✅ Vrai/Faux	`!vf`	`!v` ou `!f`	✅ Groupe

Scores et classement

!score        → Voir votre score dans ce chat
!classement   → Top 10 du chat

📦 File d'attente

BotWA utilise une file d'attente en mémoire pour envoyer les messages en séquence et éviter les bans WhatsApp. Les jobs sont traités un par un. La file est perdue au redémarrage du serveur.

Actions disponibles : Pause / Reprendre / Vider la file depuis le dashboard.

🔗 Webhooks

BotWA peut notifier une URL externe à chaque message reçu.

Configurer un webhook

Allez dans Webhooks → + Ajouter
Entrez l'URL de votre serveur
Choisissez les événements (all ou message,group)
Ajoutez un secret pour valider les requêtes

Payload envoyé

{
  "event": "message",
  "sessionId": "maSession",
  "timestamp": 1708900000000,
  "payload": {
    "jid": "33612345678@s.whatsapp.net",
    "sender": "33612345678@s.whatsapp.net",
    "text": "Bonjour!"
  }
}

Valider le secret

Le header x-botwa-secret contient le secret configuré. Vérifiez-le côté serveur.

⚡ API Reference

URL de base : http://localhost:3000/api · Toutes les réponses sont en JSON.

Format de réponse standard :

{ "success": true,  "data": { ... } }
{ "success": false, "error": "message d'erreur" }

🔌 Sessions API

GET /api/sessions Lister toutes les sessions

Réponse :

{ "success": true, "data": [
  { "id": "monBot", "status": "connected", "phone_number": "33612345678" }
]}

POST /api/sessions Créer une nouvelle session

Body JSON :

{ "sessionId": "monBot" }

Le QR code est émis via Socket.io sur l'événement session:qr.

GET /api/sessions/:id/status Statut d'une session

{ "success": true, "data": { "sessionId": "monBot", "status": "connected" } }

GET /api/sessions/:id/qr Obtenir le QR code en base64

{ "success": true, "data": { "qr": "data:image/png;base64,..." } }

DELETE /api/sessions/:id Supprimer et déconnecter une session

💬 Messages API

POST /api/messages/send Envoyer un message (multipart/form-data)

Champ	Type	Requis	Description
`sessionId`	string	✅	ID de la session
`jid`	string	✅	JID ou numéro du destinataire
`type`	string	✅	`text` `image` `video` `audio` `document` `location` `contact`
`text`	string	si text	Contenu du message
`media`	file	si media	Fichier à envoyer
`caption`	string	❌	Légende pour image/vidéo
`latitude`	number	si location	Latitude GPS
`longitude`	number	si location	Longitude GPS
`name`	string	si contact	Nom du contact
`phone`	string	si contact	Téléphone du contact

Exemple curl :

curl -X POST http://localhost:3000/api/messages/send \
  -F "sessionId=monBot" \
  -F "jid=33612345678" \
  -F "type=text" \
  -F "text=Bonjour depuis BotWA!"

POST /api/messages/bulk Envoi en masse (multipart/form-data)

Champ	Type	Description
`sessionId`	string	ID de la session
`contacts`	file	Fichier CSV ou XLSX
`message`	string	Message (supporte `{name}`)
`media`	file	Média optionnel
`delayMs`	number	Délai entre envois (min 1000)

POST /api/messages/react Réagir à un message avec un emoji

{ "sessionId": "monBot", "jid": "33612345678@s.whatsapp.net",
  "msgId": "MSG_ID", "emoji": "👍", "fromMe": false }

POST /api/messages/delete Supprimer un message

{ "sessionId": "monBot", "jid": "...", "msgId": "MSG_ID", "fromMe": true }

GET /api/messages/history/:sessionId/:jid Historique des messages

Query params : ?limit=50

👥 Groupes API

GET/api/groups/:sessionIdLister tous les groupes

POST/api/groupsCréer un groupe

{ "sessionId": "monBot", "name": "Mon groupe", "participants": ["33612345678"] }

GET/api/groups/:sessionId/:groupJidInformations d'un groupe

PUT/api/groups/:sessionId/:groupJid/subjectRenommer un groupe

{ "subject": "Nouveau nom" }

PUT/api/groups/:sessionId/:groupJid/descriptionModifier la description

POST/api/groups/:sessionId/:groupJid/participants/addAjouter des participants

{ "participants": ["33612345678", "33698765432"] }

POST/api/groups/:sessionId/:groupJid/participants/removeRetirer des participants

POST/api/groups/:sessionId/:groupJid/participants/promotePromouvoir en admin

POST/api/groups/:sessionId/:groupJid/participants/demoteRetirer les droits admin

GET/api/groups/:sessionId/:groupJid/inviteObtenir le lien d'invitation

DELETE/api/groups/:sessionId/:groupJid/leaveQuitter un groupe

📋 Contacts API

GET/api/contacts/:sessionIdListe des contacts en cache

GET/api/contacts/:sessionId/check/:phoneVérifier si un numéro est sur WhatsApp

{ "success": true, "data": { "phone": "33612345678", "exists": true, "jid": "33612345678@s.whatsapp.net" } }

GET/api/contacts/:sessionId/profile/:jidPhoto de profil et statut

{ "data": { "profilePicture": "https://...", "status": "Disponible" } }

👁️ Médias API

GET/api/media/view-onceLister les médias vue-unique capturés

Query : ?sessionId=monBot (optionnel)

GET/api/media/view-once/:id/fileTélécharger un média vue-unique

DELETE/api/media/view-once/:idSupprimer un média vue-unique

⏰ Scheduler API

GET/api/schedulerLister les messages planifiés

Query : ?sessionId=monBot

POST/api/schedulerPlanifier un message (multipart/form-data)

Champ	Description
`sessionId`	Session à utiliser
`jid`	Destinataire
`message`	Texte du message
`scheduledAt`	ISO 8601 — pour envoi unique (ex: `2025-01-15T09:00:00Z`)
`cronExpression`	Cron — pour envoi récurrent (ex: `0 9 * * *`)
`isRecurring`	`true` ou `false`
`media`	Fichier optionnel

POST/api/scheduler/:id/cancelAnnuler un message planifié

DELETE/api/scheduler/:idSupprimer un message planifié

🔗 Webhook API

GET/api/webhookLister les webhooks

POST/api/webhookCréer un webhook

{ "sessionId": "monBot", "url": "https://monserveur.com/hook",
  "events": "all", "secret": "monsecret", "active": true }

PUT/api/webhook/:idModifier un webhook

POST/api/webhook/test/:idTester un webhook

DELETE/api/webhook/:idSupprimer un webhook

📦 Queue API

GET/api/queue/statsStatistiques de la file

{ "data": { "type": "memory", "waiting": 3, "active": 1, "completed": 0, "failed": 0 } }

POST/api/queue/pauseMettre en pause

POST/api/queue/resumeReprendre

POST/api/queue/clearVider la file

POST/api/queue/addAjouter un message à la file

{ "sessionId": "monBot", "jid": "33612345678@s.whatsapp.net",
  "messageData": { "type": "text", "text": "Bonjour!" },
  "options": { "delay": 5000 } }

🎮 Jeux API

GET/api/games/activeParties en cours

{ "data": [{ "jid": "...", "type": "trivia", "starter": "33612345678@s.whatsapp.net" }] }

GET/api/games/leaderboardClassement global

{ "data": [{ "player": "33612345678@s.whatsapp.net", "total": 42, "wins": 30, "losses": 12 }] }

📌 Les événements Socket.io disponibles : session:qr, session:status, viewonce:new. Connectez-vous sur ws://localhost:3000.