Logo
Retour

Documentation API Wazzap AI - Envoi de Messages WhatsApp

Documentation complète de l'API Wazzap pour automatiser l'envoi de messages WhatsApp de manière programmatique

Dernière mise à jour :

Documentation API Wazzap AI - Envoi de Messages WhatsApp

Table des matières

  1. Introduction
  2. Prérequis et obtention de la clé API
  3. Authentification
  4. Envoi de messages
  5. Désactivation de la réponse automatique de l'IA
  6. Tracking et Statistiques
  7. Rate Limiting et Queue
  8. Exemples de code
  9. Gestion des erreurs
  10. Bonnes pratiques

Introduction

Cette API permet d'envoyer des messages WhatsApp de manière programmatique en utilisant une clé API.

Caractéristiques principales

  • Authentification sécurisée par clé API
  • Envoi de messages texte
  • Rate limiting : 1230 requêtes/minute
  • Détection automatique du compte WhatsApp
  • Support format international des numéros

Prérequis et obtention de la clé API

Étape 1 : Avoir un compte Premium Wazzap AI

Vous ou vos utilisateurs devez disposer d'un abonnement Premium actif sur Wazzap AI.

Étape 2 : Créer un agent IA

  1. Connectez-vous à votre compte Wazzap AI
  2. Créez un nouvel agent IA depuis votre dashboard
  3. Configurez votre agent selon vos besoins

Étape 3 : Connecter votre numéro WhatsApp

  1. Depuis la page de votre agent, connectez votre numéro WhatsApp
  2. Scannez le QR Code avec WhatsApp
  3. Attendez que la connexion soit établie

Étape 4 : Générer votre clé API

  1. Rendez-vous dans Paramètres de votre compte
  2. Accédez à la section API Keys
  3. Cliquez sur Générer une nouvelle clé
  4. Donnez un nom à votre clé (ex: "Intégration Maketou")
  5. Sélectionnez l'agent WhatsApp à associer
  6. Copiez immédiatement la clé (elle ne sera plus affichée)

⚠️ Important : Conservez cette clé en lieu sûr, elle ne sera affichée qu'une seule fois !

Authentification

Toutes les requêtes nécessitent un header Authorization avec le format Bearer :

Authorization: Bearer wz_votre_cle_api_complète

Format de la clé : wz_xxxxxxxxxxxxxxxxxxxxxx (32 caractères après le préfixe)

Envoi de messages

Endpoint

POST https://api21.wazzap.ai/api/wazzap/send-message

Headers requis

Authorization: Bearer wz_votre_cle_api
Content-Type: application/json

Body de la requête

{
  "phoneNumber": "+3300000000",
  "message": "Votre message ici",
  "disableAiResponse": false
}

Paramètres

Paramètre Type Requis Description Exemple
phoneNumber string Oui Numéro du destinataire (format international) "+3300000000"
message string Oui Message texte à envoyer "Bonjour !"
disableAiResponse boolean Non Désactive la réponse automatique de l'IA (défaut: false) true

Réponse en cas de succès (200)

{
  "success": true,
  "code": 200,
  "message": "Message envoyé avec succès",
  "data": {
    "messageId": "3EB0XXX",
    "phoneNumber": "+3300000000",
    "formattedPhoneNumber": "3300000000",
    "executionTime": 234,
    "provider": "v1",
    "agentId": "agent_123",
    "organizationId": "org_456",
    "aiResponseDisabled": false
  }
}

Réponse en cas d'erreur (4xx/5xx)

{
  "success": false,
  "code": 400,
  "errorCode": "MISSING_PHONE_NUMBER",
  "message": "Le paramètre 'phoneNumber' est requis"
}

Désactivation de la réponse automatique de l'IA

Qu'est-ce que disableAiResponse ?

Le paramètre disableAiResponse permet de désactiver la prise en charge de la conversation automatiquement par l'agent IA qui est connecter a votre compte whatsapp pour un contact spécifique. Lorsqu'il est activé (true), le contact passe en mode humain, ce qui signifie que :

  • Votre message sera envoyé normalement
  • Le contact sera créé et lié à votre agent
  • L'IA ne répondra PAS automatiquement aux messages de ce contact
  • Vous pourrez répondre manuellement depuis votre dashboard Wazzap AI ou depuis votre WhatsApp depuis votre smartphone.

Cas d'usage typiques

1. Support VIP ou escalade

// Client important qui nécessite une attention humaine
await envoyerMessage(
  '+3300000000',
  'Bonjour M. Dupont, un conseiller va vous répondre sous peu.',
  { disableAiResponse: true }
);

2. Notifications one-way sans attendre de réponse

// Notification de livraison sans nécessiter de réponse IA
await envoyerMessage(
  '+33698765432',
  'Votre colis est arrivé au point relais.',
  { disableAiResponse: true }
);

3. Campagnes marketing personnalisées

// Envoyer une offre spéciale sans activer l'IA
const clients = ['+33601...', '+33602...'];
for (const client of clients) {
  await envoyerMessage(
    client,
    'Offre exclusive : -20% ce weekend !',
    { disableAiResponse: true }
  );
}

Exemple complet

const response = await fetch('https://api21.wazzap.ai/api/wazzap/send-message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wz_votre_cle_api',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phoneNumber: '+3300000000',
    message: 'Bonjour, un humain va vous répondre rapidement.',
    disableAiResponse: true  // L'IA ne répondra pas automatiquement
  })
});

const data = await response.json();
console.log('AI Response Disabled:', data.data.aiResponseDisabled); // true

Comment réactiver l'IA pour un contact ?

Pour réactiver la réponse automatique de l'IA pour un contact :

  1. Connectez-vous à votre dashboard Wazzap AI
  2. Accédez à la conversation du contact
  3. Cliquez sur le bouton "Réactiver l'IA" ou similaire

Ou envoyez simplement un nouveau message sans le paramètre disableAiResponse (ou avec false) :

await envoyerMessage(
  '+3300000000',
  'L\'IA est maintenant réactivée',
  { disableAiResponse: false }  // L'IA va répondre normalement
);

Important à savoir

  • Le paramètre s'applique par contact et persiste jusqu'à réactivation
  • Un contact avec disableAiResponse: true sera marqué comme "Mode humain" dans votre dashboard
  • Vous pouvez toujours répondre manuellement via le dashboard
  • L'IA reste active pour tous les autres contacts

Tracking et Statistiques

Endpoint de statistiques

Consultez en temps réel les performances de votre clé API :

GET https://api21.wazzap.ai/api/wazzap/stats
Authorization: Bearer wz_votre_cle_api

Réponse

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "cm9xxx...",
      "name": "Production API",
      "agentId": "cm9yyy..."
    },
    "stats": {
      "totalRequests": 1250,
      "successRequests": 1200,
      "failedRequests": 50,
      "successRate": 96.0
    },
    "queue": {
      "processing": 2,
      "pending": 5,
      "maxConcurrent": 4
    },
    "rateLimit": {
      "limit": 100,
      "current": 45,
      "remaining": 55,
      "resetAt": "2025-10-15T15:30:00.000Z"
    },
    "recentRequests": [
      {
        "id": "req_xxx",
        "status": "COMPLETED",
        "statusCode": 200,
        "duration": 234,
        "provider": "v1",
        "startedAt": "2025-10-15T15:25:00.000Z",
        "completedAt": "2025-10-15T15:25:00.234Z"
      }
      // ... 9 autres requêtes récentes
    ]
  }
}

Métriques disponibles

Métrique Description
totalRequests Nombre total de requêtes effectuées
successRequests Nombre de requêtes réussies
failedRequests Nombre de requêtes échouées
successRate Taux de succès en pourcentage
queue.processing Nombre de requêtes en cours de traitement
queue.pending Nombre de requêtes en attente
rateLimit.current Nombre de requêtes dans la fenêtre actuelle
rateLimit.remaining Nombre de requêtes restantes avant limite

Exemple de monitoring

async function surveillerAPI() {
  const response = await fetch('https://api21.wazzap.ai/api/wazzap/stats', {
    headers: {
      'Authorization': 'Bearer wz_votre_cle_api'
    }
  });

  const { data } = await response.json();
  
  console.log(`Taux de succès: ${data.stats.successRate}%`);
  console.log(`Queue: ${data.queue.processing}/${data.queue.maxConcurrent} en cours, ${data.queue.pending} en attente`);
  console.log(`Rate limit: ${data.rateLimit.remaining}/${data.rateLimit.limit} restantes`);
  
  // Alerte si problème détecté
  if (data.stats.successRate < 90) {
    console.warn('Taux de succès faible - vérifier la connexion WhatsApp');
  }
}

// Surveiller toutes les 30 secondes
setInterval(surveillerAPI, 30000);

Rate Limiting et Queue

Système de Queue Automatique

Pour garantir la stabilité, chaque clé API dispose d'une queue intelligente qui traite maximum 4 requêtes en parallèle.

Comment ça fonctionne ?

Vos requêtes → [Queue] → [4 slots de traitement] → Envoi WhatsApp
                            ↑
                    Maximum 4 simultanées
                    Les autres attendent

Rate Limiting

Chaque clé API a des limites configurables :

Paramètre Défaut Description
rateLimit 100 Requêtes par fenêtre
rateLimitWindow 60s Durée de la fenêtre

Par défaut : 100 requêtes par minute

Gestion du dépassement

Si vous dépassez la limite :

{
  "success": false,
  "code": 429,
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "message": "Trop de requêtes. Veuillez patienter.",
  "rateLimit": {
    "limit": 100,
    "remaining": 0,
    "reset": "2025-10-15T15:30:00.000Z"
  }
}

Bonnes pratiques pour éviter le rate limiting

// 1. Vérifier avant d'envoyer en masse
async function envoyerSiPossible(phoneNumber, message) {
  const stats = await obtenirStats();
  
  if (stats.data.rateLimit.remaining < 5) {
    const resetTime = new Date(stats.data.rateLimit.resetAt);
    const waitTime = resetTime.getTime() - Date.now();
    console.log(`Attente de ${Math.ceil(waitTime/1000)}s...`);
    await new Promise(r => setTimeout(r, waitTime));
  }
  
  return await envoyerMessage(phoneNumber, message);
}

// 2. Espacer les envois automatiquement
async function envoyerAvecEspacement(contacts, intervalMs = 700) {
  for (const contact of contacts) {
    await envoyerMessage(contact.phone, contact.message);
    await new Promise(r => setTimeout(r, intervalMs));
  }
}

Augmenter votre rate limit

Pour augmenter votre rate limit, contactez votre administrateur ou passez à un plan supérieur.

Exemples de code

Envoi de message simple

Gestion des erreurs

Codes d'erreur

Code HTTP Code erreur Description Solution
200 - Succès -
400 MISSING_PHONE_NUMBER Numéro manquant Ajouter phoneNumber
400 MISSING_MESSAGE Message manquant Ajouter message
400 NO_WHATSAPP_PROVIDER Aucun WhatsApp connecté Connecter WhatsApp
401 API_KEY_MISSING Clé manquante Ajouter le header Authorization
401 API_KEY_INVALID_OR_EXPIRED Clé invalide Vérifier la clé
403 NO_WHATSAPP_ACCOUNT_CONNECTED WhatsApp non connecté Reconnecter WhatsApp
404 AGENT_NOT_FOUND Agent non trouvé Vérifier l'agent
429 - Trop de requêtes Attendre 1 minute
500 MESSAGE_SEND_ERROR Erreur serveur Réessayer

Exemples d'erreurs

Clé API manquante

{
  "success": false,
  "code": 401,
  "errorCode": "API_KEY_MISSING",
  "message": "Clé API manquante. Utilisez le header 'Authorization: Bearer YOUR_API_KEY'"
}

Numéro de téléphone manquant

{
  "success": false,
  "code": 400,
  "errorCode": "MISSING_PHONE_NUMBER",
  "message": "Le paramètre 'phoneNumber' est requis"
}

Compte WhatsApp non connecté

{
  "success": false,
  "code": 403,
  "errorCode": "NO_WHATSAPP_ACCOUNT_CONNECTED",
  "message": "Aucun compte WhatsApp connecté pour cet agent"
}

Bonnes pratiques

1. Sécurité

À faire :

  • Stocker la clé dans des variables d'environnement
  • Ne jamais exposer la clé côté client
  • Utiliser HTTPS uniquement
  • Régénérer la clé si compromise

À ne pas faire :

  • Hardcoder la clé dans le code
  • Committer la clé dans Git
  • Partager la clé publiquement

Exemple sécurisé :

// .env
Wazzap AI_API_KEY=wz_votre_cle_api
Wazzap AI_API_URL=https://votre-domaine.Wazzap AI.com

// config.js
require('dotenv').config();

module.exports = {
  apiKey: process.env.Wazzap AI_API_KEY,
  apiUrl: process.env.Wazzap AI_API_URL
};

2. Rate limiting

  • Maximum : 1230 requêtes par minute
  • Implémenter une queue pour les envois en masse

3. Validation des données

// Valider le numéro
function validerNumero(phoneNumber) {
  const cleaned = phoneNumber.replace(/[^\d+]/g, '');
  if (!/^\+?\d{10,15}$/.test(cleaned)) {
    throw new Error('Numéro invalide');
  }
  return cleaned.startsWith('+') ? cleaned : '+' + cleaned;
}

// Valider le message
function validerMessage(message) {
  if (!message || typeof message !== 'string') {
    throw new Error('Message invalide');
  }
  if (message.length > 4096) {
    throw new Error('Message trop long (max 4096 caractères)');
  }
  return message.trim();
}

📚 Cas d'usage

Envoi de notifications personnalisées

const clients = [
  { nom: 'Jean Dupont', phone: '+3300000000', commande: '#12345' },
  { nom: 'Marie Martin', phone: '+33698765432', commande: '#12346' }
];

async function envoyerNotifications(clients) {
  for (const client of clients) {
    const message = `
Bonjour ${client.nom},

Votre commande ${client.commande} a été confirmée.

Merci !
    `.trim();
    
    await envoyerMessage(client.phone, message);
    await new Promise(r => setTimeout(r, 3000)); // Attendre 3s
  }
}

Support

Problèmes courants

Le message n'arrive pas :

  1. Vérifier que le numéro est correct
  2. Vérifier que le numero WhatsApp est connecté dans Wazzap AI
  3. Tester avec un autre numéro

"Rate limit exceeded" :

  1. Réduire la fréquence d'envoi
  2. Attendre 1 minute
  3. Implémenter une queue

Clé API invalide :

  1. Vérifier que vous avez bien copié la clé complète
  2. Vérifier que la clé n'a pas expiré
  3. Régénérer une nouvelle clé si nécessaire

Contact

Pour toute question :

  • Consultez d'abord cette documentation
  • Contactez nous à l'adresse contact@Wazzap.ai
APIWhatsAppIntégrationDéveloppement

Crée votre assistant IA gratuitement

Transformez vos conversations WhatsApp en opportunités commerciales, qualifiez vos leads et prenez des rendez-vous automatiquement

Amadou Fall
Kaaramoo
Bestilia
Joel Toulan
4.8 / 5
+300 Utilisateurs WazzapAI
Commencer gratuitement

Aucune carte de crédit requise ·