Documentation

Choisissez votre langage : tous les exemples de la page changent en même temps (Python par défaut).

AuthentificationNiveau 1 · Envoyer un codeVérifier un codeNiveau 2 · Connecter un numéroEnvoyer un messageRecevoir (webhook)ErreursTarifs

Base et authentification

URL de base : https://whatsapp-api.lebinaire.com. Requêtes et réponses en JSON (Content-Type: application/json).

Créez une clé dans votre tableau de bord (onglet « Clés API »), puis envoyez-la dans chaque requête :

Authorization: Bearer wak_xxxxxxxxxxxxxxxx

La clé n’est affichée qu’une fois. Limite : 120 requêtes/minute/clé. Gardez-la côté serveur (variable d’environnement), jamais dans une application mobile ou une page web publique.

Niveau 1 — Envoyer un code OTP

POST /v1/otp/send

ChampDescription
phone *Numéro de l’utilisateur, format international (ex. 22654641531). 8 chiffres = Burkina Faso.
lengthLongueur du code, 4 à 8 (défaut 6).
ttlValidité en secondes, 60 à 900 (défaut 300).
app_nameNom affiché dans le message (2-30 caractères).
langfr (défaut) ou en.
// Réponse 200
{ "id":"otp_9f2c...", "phone":"22654641531", "code":"482913", "length":6,
  "expires_at":"2026-11-17T22:10:00.000Z", "expires_in":300, "sent":true }

Le code est dans la réponse. Gardez-le côté serveur ; quand l’utilisateur saisit le sien dans votre application, c’est à vous de comparer. Ne renvoyez jamais le code au navigateur ou à l’application.

Prévoyez un délai d’attente de 70 s : l’envoi passe par une file « humaine » qui protège le numéro du bot.

Exemple complet : un petit serveur « code par WhatsApp »

Règles de protection

Vérifier un code optionnel

Si vous préférez que ce soit nous qui comparions : POST /v1/otp/verify avec {"id":"otp_...","code":"482913"} → {"valid":true}. 5 essais maximum par code, usage unique, expire selon ttl.

Niveau 2 — Connecter votre propre numéro

Deux façons : depuis le tableau de bord (onglet « Niveau 2 », avec un guide pas à pas), ou par l’API :

Sur le téléphone du numéro : WhatsApp → Appareils connectés (Android : menu ⋮ · iPhone : Réglages) → Connecter un appareil → Connecter avec un numéro de téléphone → saisissez le code. À faire dans les 3 minutes.

Statuts : pairing, connecting, connected, reconnecting, pairing_expired, logged_out, blocked, paused_billing, stopped. La réponse de GET /v1/session contient aussi pairing_code et pairing_expires_at (ms).

⚠ Votre numéro est le vôtre : WhatsApp peut le restreindre si vous envoyez du spam. N’écrivez qu’à des personnes qui attendent vos messages, utilisez de préférence un numéro dédié, restez à un usage humain.

Envoyer un message texte

POST /v1/messages/send répond 202 avec {"id":"msg_...","status":"queued"}. Suivez-le avec GET /v1/messages/<id> (queued → sent ou failed) ou via le webhook. Messages envoyés avec délais aléatoires et indicateur « écrit… ». Maximum 20/minute et 500/jour par session ; le destinataire doit être sur WhatsApp.

Déconnecter : DELETE /v1/session.

Recevoir les messages : le webhook

Enregistrez votre URL (ou faites-le dans le tableau de bord) :

PUT /v1/webhook   {"url":"https://monsite.com/wa-webhook"}
// -> { "ok":true, "url":"...", "secret":"whsec_..." }

Pour chaque message reçu, nous envoyons un POST JSON :

{ "event":"message.received", "created_at":"2026-11-17T21:30:00.000Z",
  "data":{ "message_id":"3EB0...", "from":"22654641531", "push_name":"Awa",
           "type":"text", "text":"Bonjour", "timestamp":1794432600, "session_phone":"22670000000" } }

Évènements : message.received, message.sent, message.failed, session.connected, session.disconnected, session.logged_out, session.blocked, webhook.test. Types de message : text, image, video, document, audio, sticker, location, contact, other (texte/légende dans text ; les fichiers eux-mêmes ne sont pas transmis). Les groupes sont ignorés.

Vérifier la signature (obligatoire)

Chaque requête porte X-WhatsAppAPI-Signature: sha256=<hex> = HMAC-SHA256 du corps brut avec votre secret. Répondez 2xx en moins de 10 s ; sinon 3 nouvelles tentatives (10 s, 1 min, 5 min). Exemple de récepteur :

Codes d’erreur

HTTPSignification
400Paramètre invalide (le champ error l’explique)
401Clé API absente, invalide ou révoquée
402Essai terminé et aucun abonnement actif pour ce niveau
403Compte non vérifié ou suspendu
404Ressource introuvable
409Session non connectée / déjà active
429Cadence ou plafond dépassé (voir error, parfois retry_after)
502 / 503Code non remis / bot momentanément hors ligne : patientez, ne bouclez pas

Tarifs et paiement

Essai gratuit de 3 jours dès la vérification de votre numéro (niveaux 1 et 2). Ensuite : niveau 1 = 1 000 F/mois, niveau 2 = 500 F/mois. Contactez l’administrateur pour payer : il crédite votre portefeuille, puis vous activez l’abonnement d’un clic dans votre tableau de bord.