Documentation API WhatsApp

Introduction

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

Authentification

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

Authorization: Bearer wz_votre_cle_api_complete

Format de la clé : wz_xxxxxxxx... (32 caractères après le préfixe). Vous pouvez aussi utiliser une clé au format wzy_xxxxxxxx_... (format natif WazzyAI).

Envoi de messages

Body de la requête

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

Paramètres

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
  }
}

Exemple complet (JavaScript)

const response = await fetch('https://votre-domaine/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
  })
});
const data = await response.json();
console.log('Message envoyé, id =', data.data.messageId);

Exemple cURL

curl -X POST https://votre-domaine/api/wazzap/send-message \
  -H "Authorization: Bearer wz_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+3300000000",
    "message": "Bonjour depuis l'\''API !"
  }'

Désactivation de l'IA (mode humain)

Le paramètre disableAiResponse permet de désactiver la prise en charge automatique par l'agent IA pour un contact spécifique. Lorsqu'il est activé (true), le contact passe en mode humain :

• Votre message est envoyé normalement
• Le contact est créé et lié à votre agent
• L'IA ne répondra pas automatiquement aux prochains messages de ce contact
• Vous pouvez répondre manuellement depuis le dashboard ou WhatsApp

Réactiver l'IA

Envoyez un nouveau message avec disableAiResponse: false (ou omettez le paramètre), OU cliquez sur "Réactiver l'IA" dans le dashboard.

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

Statistiques

curl https://votre-domaine/api/wazzap/stats \
  -H "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": "2026-08-24T15:30:00.000Z"
    },
    "recentRequests": [ ... 10 dernières ... ]
  }
}

Rate limiting et queue

Chaque clé API dispose d'une queue intelligente qui traite au maximum 4 requêtes en parallèle. Les requêtes suivantes attendent dans une file d'attente FIFO.

La limite par défaut est de 100 requêtes/minute. Configurable par clé au moment de la création.

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

Codes d'erreur

Bonnes pratiques

• ✅ Stockez la clé dans une variable d'environnement (jamais dans le code source)
• ✅ Ne l'exposez jamais côté client (navigateur, app mobile)
• ✅ Utilisez HTTPS uniquement
• ✅ Espacez les envois automatiquement (au moins 700ms entre 2 messages)
• ✅ Régénérez la clé si vous suspectez qu'elle a fuité
• ❌ Ne pas hardcoder la clé, ne pas la committer dans Git