WhatsApp pour l'authentification OTP via l'API : tutoriel pour les éditeurs

Ce tutoriel vous guide pas à pas pour envoyer votre premier OTP (code à usage unique) via l'API WhatsApp Business. À la fin de ce tutoriel, vous aurez un template d'authentification validé, un appel API fonctionnel et un mécanisme de fallback en place. Durée estimée : 45 à 90 minutes selon votre stack technique.

Prérequis avant de commencer

Avant d'écrire la première ligne de code, vérifiez que vous avez :

• Un compte Whakup actif avec accès à l'espace éditeur et vos clés API.
• Un numéro WhatsApp Business connecté via l'embedded signup Whakup (ou un numéro sandbox pour les tests).
• Un environnement backend capable de faire des requêtes HTTP (Node.js, Python, PHP, Ruby — peu importe).
• Un numéro de téléphone personnel avec WhatsApp pour tester la réception.

Si vous n'avez pas encore de compte Whakup, consultez notre guide de démarrage de l'API WhatsApp Business avant de continuer.

Étape 1 : Créer le template d'authentification

1.1 Accéder au gestionnaire de templates

Connectez-vous à l'espace éditeur Whakup. Dans la section "Templates", cliquez sur "Créer un template".

1.2 Paramétrer le template

Renseignez les champs suivants :

Champ	Valeur
Nom	auth_otp_fr (minuscules, sans espaces)
Catégorie	Authentication
Langue	Français (fr)

1.3 Composer le message

Header : Aucun (les templates Authentication n'acceptent pas d'image).

Corps du message (copiez-collez exactement) :

{{1}} est votre code de vérification MonApplication. Il expire dans 10 minutes. Ne le partagez avec personne.

Remplacez "MonApplication" par le nom réel de votre service. La variable {{1}} sera remplacée par le code OTP lors de l'envoi.

Footer : Cochez "Add Security Recommendation" — Meta affiche automatiquement "Pour votre sécurité, ne partagez pas ce code."

Bouton : Choisissez le type OTP / Copy Code. Ce bouton copie automatiquement le code dans le presse-papier de l'utilisateur.

1.4 Soumettre pour validation

Cliquez sur "Soumettre". Meta valide les templates Authentication en général en moins de 24 heures. Vous recevrez une notification Whakup quand le statut passe à APPROVED.

En attendant, passez à l'étape 2 avec le mode sandbox.

Étape 2 : Tester en sandbox

Whakup met à disposition un environnement sandbox qui ne consomme pas de crédits et ne dépend pas de l'approbation Meta. Utilisez l'URL sandbox pour vos tests initiaux.

2.1 Générer un code OTP côté backend

Voici un exemple en Node.js :

const crypto = require('crypto');

function generateOTP(length = 6) {
  // CSPRNG : cryptographiquement sécurisé
  const buffer = crypto.randomBytes(4);
  const num = buffer.readUInt32BE(0);
  const otp = String(num % Math.pow(10, length)).padStart(length, '0');
  return otp;
}

// Stocker dans Redis avec TTL 10 minutes
async function storeOTP(phoneNumber, otp, redisClient) {
  const key = `otp:${phoneNumber}`;
  const hash = crypto.createHash('sha256').update(otp).digest('hex');
  await redisClient.set(key, hash, { EX: 600 }); // 600 secondes
  return hash;
}

2.2 Appeler l'API Whakup

async function sendOTPWhatsApp(phoneNumber, otpCode) {
  const response = await fetch('https://api.whakup.com/v1/messages', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.WHAKUP_API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: phoneNumber,  // Format E.164 : +33612345678
      template: {
        name: 'auth_otp_fr',
        language: 'fr',
        components: [
          {
            type: 'body',
            parameters: [
              { type: 'text', text: otpCode }
            ]
          },
          {
            type: 'button',
            sub_type: 'url',
            index: 0,
            parameters: [
              { type: 'text', text: otpCode }
            ]
          }
        ]
      }
    })
  });

  const data = await response.json();

  if (!response.ok) {
    throw new Error(`Whakup API error: ${data.error}`);
  }

  return data.message_id;
}

2.3 Vérifier le code saisi par l'utilisateur

async function verifyOTP(phoneNumber, userInput, redisClient) {
  const key = `otp:${phoneNumber}`;
  const storedHash = await redisClient.get(key);

  if (!storedHash) {
    return { valid: false, reason: 'expired' };
  }

  const inputHash = crypto.createHash('sha256').update(userInput).digest('hex');

  // Comparaison en temps constant pour éviter les timing attacks
  const valid = crypto.timingSafeEqual(
    Buffer.from(storedHash, 'hex'),
    Buffer.from(inputHash, 'hex')
  );

  if (valid) {
    await redisClient.del(key); // Invalider le code après utilisation
  }

  return { valid, reason: valid ? 'ok' : 'invalid' };
}

Étape 3 : Configurer le webhook de statut

Whakup notifie votre backend de l'état de livraison via webhook. Configurez votre endpoint dans l'espace éditeur Whakup (section "Webhooks").

3.1 Créer l'endpoint webhook

app.post('/webhooks/whakup', express.json(), (req, res) => {
  const { message_id, status, timestamp } = req.body;

  switch (status) {
    case 'delivered':
      // Message livré : démarrer le timer d'expiration côté UI
      console.log(`OTP delivered: ${message_id} at ${timestamp}`);
      break;

    case 'failed':
      // Livraison échouée : déclencher le fallback SMS
      triggerSMSFallback(message_id);
      break;

    case 'read':
      // Utilisateur a ouvert le message
      break;
  }

  res.status(200).send('OK'); // Répondez toujours 200, même en cas d'erreur interne
});

3.2 Implémenter le fallback SMS

async function triggerSMSFallback(messageId) {
  // Récupérez le numéro associé au message_id depuis votre store
  const { phoneNumber, otpCode } = await getMessageContext(messageId);

  // Envoyez via votre provider SMS habituel
  await smsProvider.send({
    to: phoneNumber,
    message: `Votre code de vérification : ${otpCode}. Expire dans 10 min.`
  });

  console.log(`SMS fallback triggered for ${phoneNumber}`);
}

Étape 4 : Passer en production

Quand votre template est approuvé par Meta et vos tests sandbox concluants :

1. Remplacez l'URL sandbox par l'URL de production dans votre configuration.
2. Activez le rate limiting : 3 tentatives d'envoi maximum par numéro par heure.
3. Configurez les alertes : taux d'échec > 5 % sur 1 heure = notification immédiate.
4. Testez avec un vrai numéro avant d'ouvrir aux utilisateurs finaux.

Pour passer de 1 000 à 100 000 messages par jour, votre numéro doit monter en tier de messagerie progressivement. Consultez notre article sur les limites de messagerie WhatsApp API pour anticiper cette montée en charge.

FAQ

Mon template a été rejeté par Meta, que faire ?

Relisez le motif de rejet dans l'espace Whakup. Les raisons les plus fréquentes pour les templates OTP : absence de la durée de validité dans le corps, nom d'application absent, ou URL dans le bouton ne correspondant pas au domaine déclaré. Corrigez et resoumettez immédiatement — il n'y a pas de délai d'attente entre soumissions.

Peut-on envoyer l'OTP sans template pré-approuvé ?

Non. Tous les messages initiés par l'entreprise (outside the 24h service window) nécessitent un template approuvé. L'OTP est toujours initié par votre système, donc un template est obligatoire. Il n'y a pas de contournement possible via l'API WhatsApp Business.

Comment gérer plusieurs langues pour l'OTP ?

Créez un template par langue (auth_otp_fr, auth_otp_en, auth_otp_es, etc.). Lors de l'appel API, sélectionnez le template correspondant à la locale de l'utilisateur stockée dans votre base. La structure de l'appel API est identique, seul le champ name et language changent.

Quel est le TTL recommandé pour un code OTP WhatsApp ?

10 minutes est le standard pour une bonne expérience utilisateur. Réduisez à 5 minutes pour les transactions financières ou les accès à des données sensibles. N'allez pas en dessous de 3 minutes : les utilisateurs dans des zones à connectivité variable pourraient ne pas recevoir le message à temps.

---

Ce tutoriel couvre l'essentiel pour un premier déploiement en production. Pour les cas avancés — multi-tenant, intégration dans un workflow d'authentification OAuth, gestion des numéros portés — l'équipe technique Whakup accompagne les éditeurs pendant leur phase d'intégration. Accédez à la documentation complète et démarrez votre intégration OTP via l'API Whakup.