WhatsApp pour les alertes de sécurité via l'API : tutoriel pour les éditeurs

Envoyer une alerte de sécurité WhatsApp via l'API demande moins de deux heures de travail pour un développeur qui a déjà accès à l'API. Ce tutoriel couvre chaque étape, de la configuration du numéro à la réception des statuts de livraison, avec des exemples de requêtes HTTP concrets.

Étape 1 — Configurer votre accès API et votre numéro

Avant d'envoyer quoi que ce soit, il vous faut :

• Un WABA actif (WhatsApp Business Account) associé à votre compte Whakup
• Un numéro de téléphone enregistré sur ce WABA (numéro dédié, pas votre numéro personnel)
• Un token d'accès généré depuis votre espace Whakup

Si vous n'avez pas encore de compte, l'embedded signup Whakup permet de créer et connecter un WABA en quelques minutes sans passer par Business Manager manuellement. C'est un avantage concret du statut de Meta Tech Provider certifié de Whakup.

Une fois le token récupéré, testez l'accès avec un appel simple :

curl -X GET \
  "https://graph.facebook.com/v19.0/{phone-number-id}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

La réponse doit retourner le id, le display_phone_number et le verified_name de votre numéro.

Étape 2 — Créer et soumettre un template AUTHENTICATION

Les alertes de sécurité utilisent la catégorie AUTHENTICATION. Meta propose un template standardisé avec bouton "Copier le code" intégré. C'est le plus rapide à déployer.

Soumettez le template via l'API :

curl -X POST \
  "https://graph.facebook.com/v19.0/{waba-id}/message_templates" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "auth_otp_login",
    "language": "fr",
    "category": "AUTHENTICATION",
    "components": [
      {
        "type": "body",
        "add_security_recommendation": true
      },
      {
        "type": "footer",
        "code_expiration_minutes": 5
      },
      {
        "type": "buttons",
        "buttons": [
          {
            "type": "otp",
            "otp_type": "copy_code",
            "text": "Copier le code"
          }
        ]
      }
    ]
  }'

Le délai d'approbation est généralement inférieur à 24 heures. Pour un template AUTHENTICATION standard, il peut être validé en moins d'une heure. Consultez l'article sur les catégories de templates WhatsApp si vous hésitez entre AUTHENTICATION et UTILITY.

Étape 3 — Envoyer l'alerte sécurité

Une fois le template approuvé, voici la requête d'envoi :

curl -X POST \
  "https://graph.facebook.com/v19.0/{phone-number-id}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "+33612345678",
    "type": "template",
    "template": {
      "name": "auth_otp_login",
      "language": { "code": "fr" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "482931" }
          ]
        },
        {
          "type": "button",
          "sub_type": "url",
          "index": "0",
          "parameters": [
            { "type": "text", "text": "482931" }
          ]
        }
      ]
    }
  }'

La valeur "482931" est votre OTP généré côté serveur. Remplacez-la par votre logique de génération (TOTP, UUID tronqué, etc.).

La réponse contient un messages[0].id (identifiant du message). Conservez-le pour tracker le statut via webhook.

Étape 4 — Configurer les webhooks pour les statuts

Les webhooks sont indispensables pour savoir si l'alerte a bien été reçue et détecter les cas de fallback. Configurez votre endpoint dans votre espace Whakup, puis implémentez la réception :

// Express.js - exemple de handler webhook
app.post('/webhook/whatsapp', (req, res) => {
  const body = req.body;

  if (body.entry?.[0]?.changes?.[0]?.value?.statuses) {
    const statuses = body.entry[0].changes[0].value.statuses;

    statuses.forEach(status => {
      const { id, status: statusValue, timestamp, recipient_id } = status;

      switch (statusValue) {
        case 'sent':
          // Message transmis à WhatsApp
          break;
        case 'delivered':
          // Livré sur l'appareil — OTP accessible
          clearFallbackTimer(id);
          break;
        case 'read':
          // Utilisateur a vu le message
          break;
        case 'failed':
          // Échec — déclencher le fallback SMS
          triggerSmsFallback(recipient_id, status.errors);
          break;
      }
    });
  }

  res.sendStatus(200);
});

La fonction clearFallbackTimer annule le timer de fallback SMS démarré à l'envoi. Si delivered n'arrive pas sous 10-15 secondes, triggerSmsFallback prend le relais.

Pour le détail de la configuration des webhooks, lisez l'article webhooks WhatsApp API : configuration et réception.

Étape 5 — Tester en sandbox avant la mise en production

Whakup met à disposition un environnement sandbox pour tester vos flux sans frais. En sandbox :

• Les messages sont envoyés vers des numéros de test whitelisted
• Les webhooks fonctionnent normalement (vous pouvez tester les statuts delivered, failed)
• Les templates peuvent être soumis et testés sans approbation formelle

Scénarios à tester impérativement avant la prod :

Scénario	Résultat attendu
Numéro WhatsApp actif	Statut delivered < 5 sec
Numéro non-WhatsApp	Erreur 131014, fallback SMS
OTP expiré (> 5 min)	Bouton grisé côté utilisateur
Template non approuvé	Erreur 132001
Token invalide	HTTP 401

FAQ

Comment générer un OTP sécurisé côté serveur ?

Utilisez un générateur TOTP conforme RFC 6238 (bibliothèques speakeasy en Node.js, pyotp en Python) ou un code numérique à 6 chiffres généré de manière cryptographiquement sûre (crypto.randomInt en Node.js). Ne réutilisez jamais un OTP et stockez-le hashé (bcrypt ou argon2) avec son timestamp de génération.

Peut-on envoyer plusieurs templates AUTHENTICATION depuis le même numéro ?

Oui. Un numéro peut avoir plusieurs templates approuvés. Vous pouvez avoir un template pour la connexion, un pour la réinitialisation de mot de passe, un pour la confirmation de transaction — chacun avec ses propres paramètres et durées d'expiration.

Que se passe-t-il si l'utilisateur n'a pas WhatsApp sur son numéro ?

L'API retourne une erreur 131014 (numéro non-WhatsApp) ou 131009 (numéro invalide). Détectez ces codes dans votre handler webhook ou dans la réponse HTTP synchrone, et basculez sur SMS. Marquez le numéro comme "non-WhatsApp" dans votre base pour éviter les tentatives futures inutiles.

L'API Whakup est-elle compatible avec l'API Graph Meta standard ?

Oui. Whakup expose l'API Cloud officielle de Meta. Les requêtes sont identiques à celles décrites dans la documentation Meta. Vous n'avez pas à apprendre un format propriétaire — si vous avez déjà intégré l'API Graph, vous êtes opérationnel immédiatement.

---

Votre intégration est prête à passer en production ? Accédez à l'API WhatsApp Business Whakup pour créer votre compte, générer votre token et configurer votre premier WABA. Le sandbox est disponible immédiatement après inscription.