API WhatsApp

Introduction

Cette API gère la connexion d'un compte WhatsApp. Chaque clé secrète possède sa propre session, indépendante des autres. Une fois connecté, tu peux :

• lier ton numéro avec un code d'appairage (sans scanner de QR code) ;
• mettre ta session en pause, la relancer ou la supprimer ;
• recevoir chaque message entrant sur ton site grâce à un webhook ;
• répondre et envoyer des messages (texte, image, vidéo, audio, document) avec /send.

Tes commandes (!menu, !ping...) vivent dans ton propre code. Tu ne modifies jamais l'API.

Démarrage rapide

1. Récupère ta clé auprès de l'administrateur. Elle ressemble à a1b2c3... (48 caractères). Garde-la secrète.

2. Demande un code d'appairage avec ton numéro (format international, sans +) :

curl -X POST {{BASE}}/pair \
  -H "x-api-key: SA_CLE" -H "Content-Type: application/json" \
  -d '{"number":"50937000000"}'

Réponse :

{"code":"ABCD1234"}

3. Entre le code dans WhatsApp : Appareils connectés, Connecter un appareil, Lier avec le numéro de téléphone. Fais-le vite, le code expire au bout de quelques minutes.

4. Vérifie la connexion :

curl {{BASE}}/status -H "x-api-key: SA_CLE"

Tu dois voir "status":"open".

5. Envoie un premier message :

curl -X POST {{BASE}}/send \
  -H "x-api-key: SA_CLE" -H "Content-Type: application/json" \
  -d '{"to":"50937000000","text":"Bonjour !"}'

Authentification

Toutes les routes (sauf /panel et /docs) demandent ta clé dans le header x-api-key.

x-api-key: SA_CLE

Une clé ne donne accès qu'à sa propre session. Une clé invalide renvoie 401.

Endpoints

Toutes les réponses sont en JSON. Les erreurs ont la forme {"error":"message"}.

GET/status

Renvoie l'état de ta connexion.

curl {{BASE}}/status -H "x-api-key: SA_CLE"

{
  "label": "cle1",
  "status": "open",
  "phone": "50937000000",
  "since": 1790000000000,
  "registered": true,
  "webhook": "https://monsite.com/wa-hook"
}

POST/pair

Génère un code d'appairage pour lier un numéro WhatsApp.

curl -X POST {{BASE}}/pair \
  -H "x-api-key: SA_CLE" -H "Content-Type: application/json" \
  -d '{"number":"50937000000"}'

{"code":"ABCD1234"}

Limite : 5 demandes par 10 minutes. Si un compte est déjà lié, l'API répond Déjà connecté : utilise /logout d'abord.

POST/stop

Met la session en pause. Le compte reste lié, mais l'API se déconnecte de WhatsApp. Aucun message n'est reçu ni envoyé pendant la pause, et elle est conservée après un redémarrage du serveur.

curl -X POST {{BASE}}/stop -H "x-api-key: SA_CLE"

{"ok":true,"status":"stopped"}

POST/start

Relance une session en pause (ou reconnecte une session liée). Pas besoin d'un nouveau code.

curl -X POST {{BASE}}/start -H "x-api-key: SA_CLE"

{"ok":true,"status":"connecting"}

Si aucun compte n'est lié, l'API répond Aucune session, utilise /pair.

POST/logout

Supprime définitivement la session et délie l'appareil dans WhatsApp. Pour te reconnecter, il faut un nouveau code avec /pair. Le webhook n'est pas supprimé.

curl -X POST {{BASE}}/logout -H "x-api-key: SA_CLE"

{"ok":true}

POST/webhook

Enregistre l'URL qui recevra tes messages entrants.

curl -X POST {{BASE}}/webhook \
  -H "x-api-key: SA_CLE" -H "Content-Type: application/json" \
  -d '{"url":"https://monsite.com/wa-hook"}'

{"ok":true,"url":"https://monsite.com/wa-hook"}

GET/webhook

Renvoie le webhook actuel.

curl {{BASE}}/webhook -H "x-api-key: SA_CLE"

{"url":"https://monsite.com/wa-hook"}

DELETE/webhook

Supprime le webhook. Tu ne reçois plus de messages.

curl -X DELETE {{BASE}}/webhook -H "x-api-key: SA_CLE"

POST/send

Envoie un message. La session doit être open. Limite : 30 messages par minute.

Texte :

curl -X POST {{BASE}}/send \
  -H "x-api-key: SA_CLE" -H "Content-Type: application/json" \
  -d '{"to":"50937000000","text":"Bonjour !"}'

Image :

curl -X POST {{BASE}}/send \
  -H "x-api-key: SA_CLE" -H "Content-Type: application/json" \
  -d '{"to":"50937000000","type":"image","url":"https://monsite.com/photo.jpg","caption":"Ma photo"}'

Document :

curl -X POST {{BASE}}/send \
  -H "x-api-key: SA_CLE" -H "Content-Type: application/json" \
  -d '{"to":"50937000000","type":"document","url":"https://monsite.com/facture.pdf","filename":"facture.pdf"}'

{"ok":true}

Les liens de fichiers doivent être publics (http ou https) et ne pas pointer vers un réseau privé ou localhost.

Webhook : recevoir les messages

Quand quelqu'un écrit à ton numéro, l'API envoie une requête POST à ton URL avec ce JSON :

{
  "label": "cle1",
  "id": "3EB0A1B2C3D4E5F6",
  "from": "50937000000@s.whatsapp.net",
  "sender": "50937000000@s.whatsapp.net",
  "name": "Jean",
  "isGroup": false,
  "type": "conversation",
  "text": "!menu",
  "timestamp": 1790000000
}

Ne sont pas transmis : tes propres messages, les statuts des contacts et les chaînes (newsletters).

Vérifier la signature

Chaque requête contient le header x-signature : un HMAC SHA-256 (en hexadécimal) du corps brut, calculé avec ta clé. La clé n'est jamais envoyée. Vérifie toujours la signature avant de traiter le message.

Si ton site ne répond pas 200 dans les 8 secondes, l'API réessaie une fois, puis abandonne le message. Réponds vite, et fais tes traitements longs après la réponse.

Statuts de connexion

Si WhatsApp délie l'appareil depuis ton téléphone, la session est supprimée automatiquement : redemande un code avec /pair.

Erreurs et limites

Exemples de code

Un bot minimal qui répond à !ping et !menu, avec vérification de la signature.

Node.js (Express)

import express from 'express'
import crypto from 'crypto'

const app = express()
const KEY = process.env.WA_API_KEY
const API = '{{BASE}}'

async function send(to, text) {
  await fetch(API + '/send', {
    method: 'POST',
    headers: { 'x-api-key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ to, text })
  })
}

app.post('/wa-hook', express.json({ verify: function (req, res, buf) { req.raw = buf } }), async function (req, res) {
  const sig = crypto.createHmac('sha256', KEY).update(req.raw).digest('hex')
  if (sig !== req.headers['x-signature']) return res.sendStatus(401)
  res.sendStatus(200)

  const { from, text, isGroup } = req.body
  if (isGroup) return
  if (text === '!ping') await send(from, 'pong')
  if (text === '!menu') await send(from, 'Boutique | Compte | Support')
})

app.listen(5001)

Python (Flask)

import hmac, hashlib, os, requests
from flask import Flask, request, abort

app = Flask(__name__)
KEY = os.environ['WA_API_KEY']
API = '{{BASE}}'

@app.post('/wa-hook')
def hook():
    sig = hmac.new(KEY.encode(), request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, request.headers.get('x-signature', '')):
        abort(401)
    data = request.get_json()
    if data['text'] == '!ping':
        requests.post(API + '/send', headers={'x-api-key': KEY},
                      json={'to': data['from'], 'text': 'pong'})
    return '', 200

PHP

<?php
$KEY = getenv('WA_API_KEY');
$raw = file_get_contents('php://input');
$sig = hash_hmac('sha256', $raw, $KEY);
if (!hash_equals($sig, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

$data = json_decode($raw, true);
if ($data['text'] === '!ping') {
  $ch = curl_init('{{BASE}}/send');
  curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['x-api-key: ' . $KEY, 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['to' => $data['from'], 'text' => 'pong']),
    CURLOPT_RETURNTRANSFER => true
  ]);
  curl_exec($ch);
}
http_response_code(200);

Questions fréquentes

Combien de comptes puis-je lier ?

Un compte WhatsApp par clé. Chaque clé a sa session, isolée des autres.

Le code d'appairage est refusé, que faire ?

Vérifie le numéro (format international, sans +), demande un nouveau code et entre-le rapidement. Attention à la limite de 5 demandes par 10 minutes.

La session est passée à disconnected toute seule

Essaie POST /start. Si l'erreur indique qu'aucune session n'existe, WhatsApp a délié l'appareil : refais un /pair.

Je ne reçois rien sur mon webhook

• Vérifie que /status montre open et que le webhook est bien enregistré.
• Vérifie que ta route accepte le POST JSON et répond 200 rapidement.
• Attention : les messages que tu envoies toi-même depuis le numéro lié ne sont pas transmis. Teste avec un autre téléphone.

Comment éviter un bannissement du numéro ?

• Ne fais pas d'envois massifs ni de messages non sollicités.
• Ne réponds qu'aux personnes qui t'ont écrit et ignore les groupes si tu n'en as pas besoin.
• Évite les boucles où ton bot répond à un autre bot.
• Garde un rythme humain entre les messages.

Panneau de gestion : /panel