Développer avec l'API WhatsApp Cloud en Node.js : tutoriel

Intégrer l'API WhatsApp Cloud dans une application Node.js est aujourd'hui accessible à toute équipe technique. Meta expose une API REST propre, largement documentée, qui permet d'envoyer des messages, gérer des templates et recevoir des événements via webhooks. Tutoriel pratique pour un développeur qui démarre.

Prérequis

• Un compte Meta Business Manager vérifié.
• Un numéro WhatsApp dédié provisionné via un BSP ou directement sur la Cloud API.
• Un Permanent Access Token système généré depuis le Business Manager.
• Un serveur Node.js exposé en HTTPS (Vercel, Fly.io, un VPS chez OVH ou n8ncloud, tunnel ngrok pour le développement).
• Node.js 18+ et un projet Express ou Fastify.

Envoyer un message texte simple

L'endpoint standard est https://graph.facebook.com/v20.0/{PHONE_NUMBER_ID}/messages. Le corps JSON contient le destinataire au format international (par exemple 212612345678), le type de message et le contenu.

Structure de la requête

• Méthode : POST.
• Headers : Authorization: Bearer <ACCESS_TOKEN> et Content-Type: application/json.
• Body : objet contenant messaging_product: "whatsapp", to, type: "text" et un objet text.

Attention : hors fenêtre de conversation active (24h après un message entrant client), un message texte libre sera rejeté. Il faut utiliser un template validé.

Envoyer un template validé

Les templates sont créés depuis le Business Manager ou via l'API de gestion des templates. Une fois approuvés par Meta, on les invoque en spécifiant le nom, la langue et les variables.

Exemple type OTP

Le corps de la requête utilise type: "template" avec un objet template contenant le name, la language (par exemple fr ou ar) et les components. Un template OTP typique de la catégorie Authentication contient un corps avec la variable de code et un bouton "Copier le code".

Recevoir les messages entrants via webhook

Meta envoie des événements POST à une URL HTTPS que vous configurez dans le Business Manager. Le webhook doit :

1. Répondre à un défi GET de vérification (avec un verify token personnalisé).
2. Accepter les POST contenant les messages entrants et les statuts.
3. Répondre 200 OK rapidement (moins de 20 secondes) pour éviter les retries en cascade.

Traitement asynchrone

Le traitement lourd (persistance en base, appel à un chatbot, envoi de réponse) doit être placé dans une queue asynchrone (BullMQ, RabbitMQ, ou une simple file interne). Le handler webhook renvoie 200 immédiatement.

Gérer les statuts de livraison

Les webhooks livrent également les changements de statut des messages sortants : sent, delivered, read, failed. Ces événements sont indispensables pour :

• Déclencher un fallback SMS après un timeout sur un OTP.
• Mesurer les taux de livraison par template.
• Détecter les numéros invalides et nettoyer les listes.
• Calculer les coûts réels (Meta facture au message pour les catégories transactionnelles).

Sécuriser l'intégration

• Vérifier la signature X-Hub-Signature-256 sur chaque webhook entrant pour s'assurer que la requête vient bien de Meta.
• Stocker le token dans un secret manager (jamais en clair dans le code), et le rotate régulièrement.
• Chiffrer au repos les messages contenant des données personnelles.
• Journaliser les échecs et exposer des métriques Prometheus/Grafana pour les alertes.

Gérer les templates programmatiquement

Pour un projet à multiples templates, il est utile d'exposer l'API Message Templates : création, mise à jour, suppression. Cela permet un versioning propre et une CI/CD qui déploie les templates comme du code.

Erreurs fréquentes en développement

• Template rejeté pour non-conformité de catégorie (marketing envoyé en utility).
• Rate limits Meta déclenchés lors de tests massifs — utiliser un compte de test.
• Numéro flaggé pour envoi non sollicité en phase de dev — toujours utiliser des numéros consentants.
• Fenêtre 24h expirée : message libre rejeté, revenir au template.
• Webhook timeout : traitement synchrone trop long, migrer vers de l'asynchrone.

Conformité conformité réglementaire côté développeur

Pour un projet marocain, les données traitées via WhatsApp (numéros, contenus de messages) tombent sous la loi 09-08 et la supervision de la conformité réglementaire. Le développeur doit prévoir : opt-in traçable en base, endpoints de suppression (droit à l'oubli), durée de conservation limitée, et documentation des flux de données.

Conclusion

L'API WhatsApp Cloud en Node.js offre une prise en main rapide pour toute équipe technique marocaine. La complexité ne réside pas dans le code — elle réside dans la conformité (conformité réglementaire, catégorisation des templates, opt-in) et dans l'architecture de fiabilité (webhooks asynchrones, fallback SMS, monitoring). Un investissement structurant qui débloque tous les cas d'usage transactionnels et conversationnels de l'entreprise.