Documentation API

Guide complet pour intégrer et automatiser WhatsApp avec notre API puissante et simple d'utilisation. Testez les endpoints directement depuis cette page.

Authentification

Toutes les requêtes à l'API nécessitent deux en-têtes pour l'authentification :

  • X-API-Key: Votre clé API unique
  • X-API-Secret: Votre secret API associé

Ces clés sont générées pour chaque application dans votre dashboard.

Clés d'exemple (fictives)

API Key: wapi_1234567890abcdef1234567890abcdef

API Secret: abcdef1234567890abcdef1234567890abcdef

Ces clés sont fictives et ne fonctionneront pas. Inscrivez-vous pour obtenir des clés réelles et tester l'API.

POST /api/send-message

Envoyez un message texte ou un média (image, vidéo, document) à un numéro WhatsApp spécifié.

Paramètres (JSON body)

  • phone: string (requis) - Numéro de téléphone avec indicatif pays (ex: 24104570040)
  • message: string (optionnel) - Contenu du message texte ou légende pour le média
  • mediaUrl: string (optionnel) - URL publique du média à envoyer (ex: https://example.com/image.jpg)
  • mediaType: string (requis si mediaUrl est fourni) - Type de média: image (JPEG, PNG, GIF), video (MP4, 3GP), document (PDF, DOC, DOCX)

Exemple de requête

{
  "phone": "24104570040",
  "message": "Voici une image de test!",
  "mediaUrl": "https://example.com/sample.jpg",
  "mediaType": "image"
}

Exemple cURL

# Message texte simple
curl -X POST https://apiwx.alissa-ia.ga/api/send-message \
     -H "X-API-Key: wapi_1234567890abcdef1234567890abcdef" \
     -H "X-API-Secret: abcdef1234567890abcdef1234567890abcdef" \
     -H "Content-Type: application/json" \
     -d '{"phone": "24104570040", "message": "Bonjour de test!"}'

# Message avec média (image)
curl -X POST https://apiwx.alissa-ia.ga/api/send-message \
     -H "X-API-Key: wapi_1234567890abcdef1234567890abcdef" \
     -H "X-API-Secret: abcdef1234567890abcdef1234567890abcdef" \
     -H "Content-Type: application/json" \
     -d '{"phone": "24104570040", "message": "Voici une image!", "mediaUrl": "https://example.com/sample.jpg", "mediaType": "image"}'

Exemple de réponse

{
  "success": true,
  "message": "Message envoyé",
  "timestamp": "2025-10-07T12:00:00Z"
}

Tester cet endpoint

GET /api/status

Vérifiez le statut de connexion WhatsApp de votre application.

Paramètres

Aucun paramètre requis.

Exemple cURL

curl -X GET https://apiwx.alissa-ia.ga/api/status \
     -H "X-API-Key: wapi_1234567890abcdef1234567890abcdef" \
     -H "X-API-Secret: abcdef1234567890abcdef1234567890abcdef"

Exemple de réponse

{
  "appName": "Mon App",
  "connected": true,
  "phoneNumber": "24104570040"
}

Tester cet endpoint

GET /api/messages/received

Récupérez la liste des messages WhatsApp reçus.

Paramètres (query)

  • limit: integer (optionnel, default: 50) - Nombre maximum de messages à retourner

Exemple cURL

curl -X GET https://apiwx.alissa-ia.ga/api/messages/received?limit=50 \
     -H "X-API-Key: wapi_1234567890abcdef1234567890abcdef" \
     -H "X-API-Secret: abcdef1234567890abcdef1234567890abcdef"

Exemple de réponse

{
  "success": true,
  "count": 2,
  "messages": [
    {
      "phone": "24104570040",
      "message": "Bonjour!",
      "media_type": null,
      "media_url": null,
      "created_at": "2025-10-07T12:00:00Z"
    },
    ...
  ]
}

Tester cet endpoint

GET /api/messages/sent

Récupérez la liste des messages WhatsApp envoyés.

Paramètres (query)

  • limit: integer (optionnel, default: 50) - Nombre maximum de messages à retourner

Exemple cURL

curl -X GET https://apiwx.alissa-ia.ga/api/messages/sent?limit=50 \
     -H "X-API-Key: wapi_1234567890abcdef1234567890abcdef" \
     -H "X-API-Secret: abcdef1234567890abcdef1234567890abcdef"

Exemple de réponse

{
  "success": true,
  "count": 2,
  "messages": [
    {
      "phone": "24104570040",
      "message": "Bonjour!",
      "media_type": "image",
      "media_url": "https://example.com/sample.jpg",
      "created_at": "2025-10-07T12:00:00Z"
    },
    ...
  ]
}

Tester cet endpoint

POST /api/campaigns/create

Créez une campagne d'envoi en masse avec délais programmés. Envoyez à des centaines de contacts avec un système de lots intelligents.

Paramètres (JSON body)

  • name: string (requis) - Nom de la campagne pour identification
  • phones: array (requis) - Tableau de numéros avec indicatif pays (ex: ["237690000001", "237690000002"])
  • message: string (requis si pas de média) - Texte du message ou légende pour le média
  • delayMinutes: integer (requis) - Délai entre lots : 5, 10 ou 20 minutes
  • mediaUrl: string (optionnel) - URL publique du média (image, vidéo ou document)
  • mediaType: string (requis si mediaUrl) - Type : image, video, document

Comment ça marche :

  • • Envoi par lots de 10 messages
  • • Premier lot envoyé immédiatement
  • • Lots suivants espacés selon le délai choisi
  • • Exemple : 50 numéros avec délai 10min = 5 lots sur 40 minutes
  • • Durée estimée : Math.ceil(total / 10) × delayMinutes

Exemple de requête

{
  "name": "Campagne Marketing Janvier",
  "phones": [
    "237690000001",
    "237690000002",
    "237690000003"
  ],
  "message": "Bonjour ! Découvrez nos offres exclusives 🎉",
  "delayMinutes": 10,
  "mediaUrl": "https://example.com/promo.jpg",
  "mediaType": "image"
}

Exemple cURL

curl -X POST https://apiwx.alissa-ia.ga/api/campaigns/create \
     -H "X-API-Key: wapi_1234567890abcdef1234567890abcdef" \
     -H "X-API-Secret: abcdef1234567890abcdef1234567890abcdef" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Campagne Test",
       "phones": ["237690000001", "237690000002"],
       "message": "Message de test",
       "delayMinutes": 5
     }'

Exemple de réponse

{
  "success": true,
  "message": "Campagne créée et démarrée",
  "campaign": {
    "id": 1,
    "name": "Campagne Marketing Janvier",
    "total_recipients": 3,
    "delay_minutes": 10,
    "batch_size": 10,
    "estimated_duration_minutes": 10,
    "status": "running"
  }
}

GET /api/campaigns/:id/status

Vérifiez le statut et la progression d'une campagne en cours ou terminée.

Paramètres

  • id: integer (requis, dans l'URL) - ID de la campagne retourné lors de la création

Exemple cURL

curl -X GET https://apiwx.alissa-ia.ga/api/campaigns/1/status \
     -H "X-API-Key: wapi_1234567890abcdef1234567890abcdef" \
     -H "X-API-Secret: abcdef1234567890abcdef1234567890abcdef"

Exemple de réponse

{
  "success": true,
  "campaign": {
    "id": 1,
    "name": "Campagne Marketing Janvier",
    "status": "running",
    "total_recipients": 50,
    "sent_count": 30,
    "failed_count": 2,
    "pending_count": 18,
    "delay_minutes": 10,
    "progress_percentage": 60,
    "created_at": "2025-01-15T10:00:00Z",
    "started_at": "2025-01-15T10:00:05Z",
    "completed_at": null
  }
}

Statuts possibles :

  • • pending - En attente de démarrage
  • • running - En cours d'envoi
  • • completed - Terminée avec succès
  • • cancelled - Annulée manuellement
  • • failed - Échec (WhatsApp déconnecté ou erreur)

POST /api/campaigns/:id/cancel

Annulez une campagne en cours. Les messages déjà envoyés ne seront pas affectés, seuls les envois en attente seront stoppés.

Paramètres

  • id: integer (requis, dans l'URL) - ID de la campagne à annuler

Exemple cURL

curl -X POST https://apiwx.alissa-ia.ga/api/campaigns/1/cancel \
     -H "X-API-Key: wapi_1234567890abcdef1234567890abcdef" \
     -H "X-API-Secret: abcdef1234567890abcdef1234567890abcdef"

Exemple de réponse

{
  "success": true,
  "message": "Campagne annulée"
}

Note importante : Les messages déjà envoyés ne peuvent pas être annulés. Seuls les messages en attente (pending) seront ignorés. La campagne passera au statut "cancelled".

Exemple complet : Campagne avec suivi (Node.js)

Script pour créer une campagne et suivre sa progression en temps réel avec affichage stylé dans le terminal.

Installation

npm install axios

Code complet

const axios = require('axios');

const API_KEY = 'wapi_1234567890abcdef1234567890abcdef';
const API_SECRET = 'abcdef1234567890abcdef1234567890abcdef';
const BASE_URL = 'https://apiwx.alissa-ia.ga';

// Fonction pour créer une campagne
async function createCampaign() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/campaigns/create`,
      {
        name: 'Ma Campagne Test',
        phones: [
          '237690000001',
          '237690000002',
          '237690000003',
          // Ajoutez autant de numéros que nécessaire
        ],
        message: 'Bonjour ! Ceci est un message de test.',
        delayMinutes: 10, // 5, 10 ou 20 minutes
        // Optionnel : ajouter un média
        // mediaUrl: 'https://example.com/promo.jpg',
        // mediaType: 'image'
      },
      {
        headers: {
          'X-API-Key': API_KEY,
          'X-API-Secret': API_SECRET,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('✅ Campagne créée :', response.data);
    return response.data.campaign.id;
  } catch (error) {
    console.error('❌ Erreur création :', error.response?.data || error.message);
    throw error;
  }
}

// Fonction pour suivre la progression
async function trackCampaign(campaignId) {
  console.log(`\\n📊 Suivi de la campagne ${campaignId}...\\n`);

  const interval = setInterval(async () => {
    try {
      const response = await axios.get(
        `${BASE_URL}/api/campaigns/${campaignId}/status`,
        {
          headers: {
            'X-API-Key': API_KEY,
            'X-API-Secret': API_SECRET
          }
        }
      );

      const campaign = response.data.campaign;
      
      console.clear();
      console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
      console.log(`📋 Campagne: ${campaign.name}`);
      console.log(`📊 Statut: ${campaign.status.toUpperCase()}`);
      console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
      console.log(`✅ Envoyés: ${campaign.sent_count}/${campaign.total_recipients}`);
      console.log(`❌ Échecs: ${campaign.failed_count}`);
      console.log(`⏳ En attente: ${campaign.pending_count}`);
      console.log(`📈 Progression: ${campaign.progress_percentage}%`);
      console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n');

      // Arrêter si terminée ou annulée
      if (['completed', 'cancelled', 'failed'].includes(campaign.status)) {
        clearInterval(interval);
        console.log(`\\n🏁 Campagne terminée avec le statut: ${campaign.status}\\n`);
      }
    } catch (error) {
      console.error('❌ Erreur suivi :', error.response?.data || error.message);
      clearInterval(interval);
    }
  }, 5000); // Vérifier toutes les 5 secondes
}

// Fonction pour annuler une campagne
async function cancelCampaign(campaignId) {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/campaigns/${campaignId}/cancel`,
      {},
      {
        headers: {
          'X-API-Key': API_KEY,
          'X-API-Secret': API_SECRET
        }
      }
    );
    console.log('🛑', response.data.message);
  } catch (error) {
    console.error('❌ Erreur annulation :', error.response?.data || error.message);
  }
}

// Utilisation
(async () => {
  try {
    // Créer la campagne
    const campaignId = await createCampaign();
    
    // Suivre la progression
    await trackCampaign(campaignId);
    
    // Pour annuler (décommentez si besoin) :
    // setTimeout(() => cancelCampaign(campaignId), 30000); // Annuler après 30s
  } catch (error) {
    console.error('Erreur globale :', error);
  }
})();

Utilisation

  1. Créez un fichier campaign.js
  2. Copiez le code ci-dessus et remplacez les clés API par vos vraies clés
  3. Installez axios : npm install axios
  4. Exécutez : node campaign.js
  5. Observez la progression en temps réel dans votre terminal

Cas d'usage typiques :

  • Marketing : Envoyer des promotions à tous vos clients avec un délai pour éviter le spam
  • Notifications : Rappels d'événements, alertes importantes à grande échelle
  • Communication de masse : Annonces à une communauté ou liste de diffusion
  • Newsletter : Envoi de contenus réguliers à votre audience
  • Éducation : Envoi de ressources pédagogiques à une liste d'élèves

Bonnes pratiques pour les campagnes

  • Choisissez un délai adapté :

    Plus il y a de destinataires, plus le délai doit être élevé. Recommandé : 5 min pour <30 contacts, 10 min pour 30-100 contacts, 20 min pour +100 contacts.

  • Vérifiez votre quota :

    Assurez-vous d'avoir suffisamment de requêtes disponibles dans votre abonnement avant de lancer une campagne. Chaque message compte comme 1 requête.

  • Testez d'abord :

    Envoyez à 2-3 numéros de test avant de lancer la vraie campagne pour vérifier le message et le média.

  • Surveillez le statut :

    Utilisez l'endpoint de statut pour détecter les problèmes rapidement (échecs, déconnexion WhatsApp).

  • Formatez les numéros correctement :

    Format international sans le signe + (ex: 237690000000 pour le Cameroun).

  • Vérifiez la connexion WhatsApp :

    Assurez-vous que votre application est bien connectée à WhatsApp avant de lancer une campagne (utilisez GET /api/status).

  • Respectez la vie privée :

    N'envoyez que des messages à des contacts qui ont consenti à recevoir vos communications. Respectez les lois anti-spam.

GET /api/qr-code

Obtenez le QR code pour connecter WhatsApp ou vérifiez l'état de connexion actuel. Cette route initialise automatiquement la connexion si nécessaire.

Paramètres

Aucun paramètre requis.

Exemple cURL

curl -X GET https://apiwx.alissa-ia.ga/api/qr-code \
     -H "X-API-Key: wapi_1234567890abcdef1234567890abcdef" \
     -H "X-API-Secret: abcdef1234567890abcdef1234567890abcdef"

Exemples de réponses

WhatsApp déjà connecté :

{
  "success": true,
  "connected": true,
  "phoneNumber": "237690000000",
  "message": "WhatsApp déjà connecté"
}

QR Code disponible :

{
  "success": true,
  "connected": false,
  "qrCode": "2@eL9kF3hTvN1pQ8w...",
  "message": "QR code généré"
}

En attente :

{
  "success": true,
  "connected": false,
  "qrCode": null,
  "message": "En attente de QR code"
}

Tip : Utilisez cette route pour implémenter votre propre système de connexion WhatsApp. Pollez toutes les 2-3 secondes pour obtenir le QR code ou détecter quand la connexion est établie.

POST /api/request-pairing-code

Générez un code de pairing pour connecter WhatsApp via numéro de téléphone, sans QR code. Entrez ce code dans WhatsApp sur votre appareil principal (Paramètres > Appareils connectés > Connecter avec numéro de téléphone).

Paramètres (JSON body)

  • phoneNumber: string (requis) - Numéro de téléphone au format international sans '+' (ex: 24104570040)

Important :

  • • Assurez-vous que WhatsApp n'est pas déjà connecté (utilisez /api/disconnect si nécessaire)
  • • Le code expire après 5 minutes
  • • Format du numéro : sans espaces, sans '+', indicatif pays inclus
  • • Limite : Évitez les demandes répétées pour ne pas déclencher un rate-limit

Exemple de requête

{
  "phoneNumber": "24104570040"
}

Exemple cURL

curl -X POST https://apiwx.alissa-ia.ga/api/request-pairing-code \
     -H "X-API-Key: wapi_1234567890abcdef1234567890abcdef" \
     -H "X-API-Secret: abcdef1234567890abcdef1234567890abcdef" \
     -H "Content-Type: application/json" \
     -d '{"phoneNumber": "24104570040"}'

Exemples de réponses

Succès :

{
  "success": true,
  "pairingCode": "12345678",
  "message": "Code de pairing généré. Entrez-le dans WhatsApp sur votre téléphone.",
  "phoneNumber": "24104570040",
  "expiresIn": "5 minutes"
}

Erreurs courantes :

{
  "error": "Numéro non autorisé",
  "message": "Vérifiez le format du numéro (sans + ni espaces)"
}

{
  "error": "Trop de tentatives",
  "message": "Attendez quelques minutes avant de réessayer"
}

{
  "error": "WhatsApp déjà connecté",
  "message": "Déconnectez d'abord pour utiliser un autre numéro (utilisez /api/disconnect)"
}

Étapes sur votre téléphone :

  1. Ouvrez WhatsApp
  2. Allez dans Paramètres > Appareils connectés
  3. Sélectionnez "Connecter avec numéro de téléphone"
  4. Entrez le code à 8 chiffres généré

POST /api/disconnect

Déconnectez WhatsApp de votre application et supprimez définitivement la session. Vous devrez scanner un nouveau QR code pour vous reconnecter.

Paramètres

Aucun paramètre requis.

Exemple cURL

curl -X POST https://apiwx.alissa-ia.ga/api/disconnect \
     -H "X-API-Key: wapi_1234567890abcdef1234567890abcdef" \
     -H "X-API-Secret: abcdef1234567890abcdef1234567890abcdef"

Exemple de réponse

{
  "success": true,
  "message": "WhatsApp déconnecté avec succès"
}

Attention : Cette action supprime définitivement la session WhatsApp. Le dossier d'authentification est supprimé et tous les WebSockets actifs sont fermés. Vous devrez scanner un nouveau QR code pour vous reconnecter.

Exemple : Connexion WhatsApp via API (Node.js)

Script complet pour obtenir le QR code, l'afficher dans le terminal et détecter automatiquement la connexion.

Installation des dépendances

npm install axios qrcode-terminal

Code complet

const axios = require('axios');
const qrcode = require('qrcode-terminal');

const API_KEY = 'wapi_1234567890abcdef1234567890abcdef';
const API_SECRET = 'abcdef1234567890abcdef1234567890abcdef';
const BASE_URL = 'https://apiwx.alissa-ia.ga';

// Fonction pour connecter WhatsApp
async function connectWhatsApp() {
  console.log('🔍 Vérification de la connexion WhatsApp...\n');
  
  let connected = false;
  
  while (!connected) {
    try {
      const response = await axios.get(`${BASE_URL}/api/qr-code`, {
        headers: {
          'X-API-Key': API_KEY,
          'X-API-Secret': API_SECRET
        }
      });

      if (response.data.connected) {
        console.log('✅ WhatsApp connecté !');
        console.log(`📞 Numéro: +${response.data.phoneNumber}`);
        connected = true;
        break;
      }

      if (response.data.qrCode) {
        console.clear();
        console.log('📱 Scannez ce QR Code avec WhatsApp:\n');
        qrcode.generate(response.data.qrCode, { small: true });
        console.log('\n⏳ En attente de la connexion...\n');
      } else {
        console.log('⏳ Génération du QR code en cours...');
      }

      // Attendre 3 secondes avant la prochaine vérification
      await new Promise(resolve => setTimeout(resolve, 3000));
      
    } catch (error) {
      console.error('❌ Erreur:', error.response?.data || error.message);
      break;
    }
  }
}

// Fonction pour déconnecter WhatsApp
async function disconnectWhatsApp() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/disconnect`,
      {},
      {
        headers: {
          'X-API-Key': API_KEY,
          'X-API-Secret': API_SECRET
        }
      }
    );
    console.log('✅', response.data.message);
  } catch (error) {
    console.error('❌ Erreur:', error.response?.data || error.message);
  }
}

// Utilisation
connectWhatsApp();

// Pour déconnecter plus tard :
// disconnectWhatsApp();

Utilisation

  1. Créez un fichier connect-whatsapp.js avec le code ci-dessus
  2. Remplacez API_KEY et API_SECRET par vos vraies clés
  3. Installez les dépendances : npm install axios qrcode-terminal
  4. Exécutez : node connect-whatsapp.js
  5. Scannez le QR code affiché dans votre terminal avec WhatsApp

Avantage : Ce script vérifie automatiquement l'état de connexion toutes les 3 secondes et affiche un nouveau QR code si nécessaire. Une fois connecté, il affiche le numéro de téléphone et arrête le polling.

Automatisation Chatbot (WebSocket + OpenAI)

Testez un chatbot en temps réel qui utilise WebSocket pour recevoir les messages WhatsApp et une route serveur pour générer des réponses avec OpenAI. La clé OpenAI n'est pas stockée.

Configuration

⚠️ Cette clé est envoyée au serveur pour les tests uniquement et n'est pas stockée. Pour une utilisation sécurisée en production, utilisez l'exemple Node.js ci-dessous.

Logs en temps réel


          
          
Guide d'implémentation sécurisée avec Node.js

          

            
Pour une utilisation en production, implémentez le chatbot dans un environnement Node.js sécurisé afin de protéger vos clés API :

            
    
              
  1. Prérequis :
                
      
                  
    • Node.js (version 16 ou supérieure)
      • 
                  
    • Un compte OpenAI avec une clé API (platform.openai.com)
      • 
                  
    • Clés API WAxion (obtenues depuis votre dashboard)
      • 
                
    
              
    2. 
              
  2. Installation des dépendances :
                
    npm install ws openai
    
              
    3. 
              
  3. Créer le script :
                
    Utilisez le code ci-dessous dans un fichier, par exemple chatbot.js. Remplacez les clés par vos valeurs réelles.
    
              
    4. 
              
  4. Exécuter le script :
                
    node chatbot.js
    
              
    5. 
              
  5. Tester :
                
    Envoyez un message WhatsApp au numéro associé à votre application WAxion. Le chatbot recevra le message via WebSocket, générera une réponse avec OpenAI, et répondra automatiquement.
    
              
    6. 
            

            
Note de sécurité : Le script Node.js s'exécute côté serveur, gardant vos clés API (WAxion et OpenAI) sécurisées.

          

          
          
Exemple de code (Node.js)

          
const WebSocket = require('ws');
const { OpenAI } = require('openai');

const API_KEY = 'wapi_0389114cb8edcd50d4570b505e3a8a4b';
const API_SECRET = '52f5a8dfac2d951c0d253756cee8c0f9ca4a2e99dd09fd9e00711f314d30ebe7';
const OPENAI_API_KEY = 'sk-****';
const WS_URL = `wss://apiwx.alissa-ia.ga/ws?apiKey=${API_KEY}&apiSecret=${API_SECRET}`;

const openai = new OpenAI({ apiKey: OPENAI_API_KEY });
const ws = new WebSocket(WS_URL);

ws.on('open', () => {
  console.log('✅ Connecté au WebSocket !');
});

ws.on('message', async (data) => {
  try {
    const event = JSON.parse(data.toString());
    if (event.type === 'new_message') {
      const incomingMessage = event.message;
      console.log(`🤖 Génération IA : "${incomingMessage}"`);
      const completion = await openai.chat.completions.create({
        model: 'gpt-3.5-turbo',
        messages: [
          { role: 'system', content: 'Tu es un assistant WhatsApp amical et concis.' },
          { role: 'user', content: incomingMessage }
        ]
      });
      const reply = completion.choices[0].message.content.trim();
      ws.send(JSON.stringify({
        type: 'reply',
        phone: event.from,
        message: reply
      }));
      console.log(`✅ Réponse envoyée : "${reply}"`);
    }
  } catch (error) {
    console.error('❌ Erreur:', error.message);
  }
});

ws.on('error', (error) => {
  console.error('❌ Erreur WebSocket:', error.message);
});

ws.on('close', () => {
  console.log('🔌 WebSocket fermé.');
});
          

          
Copiez ce code dans un fichier chatbot.js, configurez vos clés, et exécutez-le avec Node.js. Installez les dépendances avec npm i ws openai.