Envoyer un OTP WhatsApp : tutoriel intégration en 15 minutes

Envoyer un OTP WhatsApp pour securiser une connexion, valider un paiement ou verifier un numero est aujourd'hui l'un des cas d'usage les plus rentables de WhatsApp Business API au Maroc. Bien maitrise, ce flux tient dans une quinzaine de minutes d'integration cote back-end. Voici la marche a suivre concrete, pensee pour un environnement Node.js ou PHP classique.

Prerequis techniques

Avant de coder, il faut disposer de trois elements : un compte Meta Business verifie, un numero WhatsApp dedie approuve par un BSP officiel, et un template de type Authentication valide par Meta. Le template ressemble a ceci :

Template type Authentication

• Nom : otp_login_fr.
• Langue : francais (fr).
• Categorie : Authentication.
• Corps : "Votre code de verification est {{1}}. Ne le partagez avec personne."
• Bouton : Copier le code, avec parametre dynamique {{1}}.

Etape 1 : appeler l'API Meta Cloud

L'envoi se fait via un simple POST HTTPS vers https://graph.facebook.com/v20.0/{PHONE_NUMBER_ID}/messages, avec un token d'acces systeme. La charge utile precise le destinataire au format international marocain (par exemple 212661234567), le nom du template, la langue et le code a injecter dans la variable {{1}}.

Bonnes pratiques cote code

• Generer le code cote serveur avec une source aleatoire cryptographique (jamais cote client).
• Stocker le hash du code (bcrypt, argon2) plutot que le code en clair.
• Prevoir une duree de validite courte, typiquement 5 minutes.
• Limiter le nombre de tentatives pour eviter les attaques par force brute.

Etape 2 : ecouter le webhook de statut

Chaque envoi genere une serie d'evenements que Meta pousse vers votre endpoint webhook : sent, delivered, read et eventuellement failed. Vous devez signer et verifier les requetes entrantes, puis persister ces statuts en base pour votre tableau de bord et vos audits.

Etape 3 : gerer le fallback SMS

Au Maroc, environ 5 a 10 % des numeros ne sont pas actifs sur WhatsApp. Un OTP non delivre est une conversion perdue. La solution consiste a declencher un timer cote serveur : si l'evenement delivered n'arrive pas dans les 30 a 60 secondes, votre code bascule automatiquement sur un SMS envoye via un agregateur multi-operateurs couvrant IAM, Orange Maroc et Inwi.

Regles de bascule recommandees

1. Statut failed immediat : bascule instantanee sur SMS.
2. Statut sent mais pas de delivered apres 45 secondes : bascule SMS.
3. Statut delivered mais pas de read apres 90 secondes : rappel SMS optionnel selon le cas d'usage.

Etape 4 : valider le code

Cote application, l'utilisateur saisit ou colle le code recu grace au bouton natif. Votre back-end compare le code au hash stocke, verifie que la duree de validite n'est pas depassee et que le nombre de tentatives n'a pas explose. Si tout est vert, la session est ouverte et le code est invalide immediatement pour eviter la reutilisation.

Erreurs frequentes a eviter

• Utiliser un template non Authentication : Meta bloque et facture la mauvaise categorie.
• Oublier la normalisation du numero au format international (+212).
• Ne pas journaliser les webhooks, ce qui rend le debogage impossible.
• Ne pas prevoir de retry sur les erreurs 5xx temporaires de l'API.

Conclusion

Un flux OTP WhatsApp propre repose sur trois piliers : un template Authentication conforme, une gestion serieuse des webhooks et un fallback SMS automatique. En 15 minutes d'integration soignee, une entreprise marocaine peut diviser par deux le cout de ses OTP tout en offrant une experience nettement plus fluide que le SMS traditionnel.