Intégrer WhatsApp API avec Node.js : tutoriel complet avec exemples de code

L'API WhatsApp Business Cloud est aujourd'hui l'un des canaux de communication les plus puissants pour atteindre les clients en Afrique francophone. Avec des taux d'ouverture dépassant 90 % et une pénétration massive dans des pays comme la Côte d'Ivoire, le Sénégal, le Cameroun ou le Maroc, WhatsApp n'est plus un simple outil de messagerie : c'est un levier commercial incontournable. Et pour les développeurs, Node.js reste l'un des environnements les plus adaptés pour construire des intégrations rapides, scalables et maintenables. Ce tutoriel vous guide pas à pas dans l'intégration de l'API WhatsApp Cloud avec Node.js, avec de vrais exemples de code prêts à l'emploi.

Prérequis et configuration initiale

Avant d'écrire la moindre ligne de code, il vous faut trois éléments : un compte Meta Developer, un numéro de téléphone WhatsApp Business enregistré sur la plateforme Meta, et un token d'accès permanent. Consultez le guide complet WhatsApp Business API pour configurer ces prérequis si ce n'est pas encore fait.

Côté Node.js, initialisez votre projet et installez les dépendances nécessaires :

mkdir whatsapp-node-integration
cd whatsapp-node-integration
npm init -y
npm install axios express dotenv

Créez un fichier .env à la racine :

WHATSAPP_TOKEN=votre_token_acces_permanent
PHONE_NUMBER_ID=votre_phone_number_id
VERIFY_TOKEN=un_token_secret_pour_webhook

Chargez ces variables dans votre code avec dotenv :

require('dotenv').config();
const axios = require('axios');

const BASE_URL = `https://graph.facebook.com/v18.0/${process.env.PHONE_NUMBER_ID}/messages`;
const HEADERS = {
  'Authorization': `Bearer ${process.env.WHATSAPP_TOKEN}`,
  'Content-Type': 'application/json'
};

Envoyer votre premier message texte

L'envoi d'un message texte simple est la brique de base de toute intégration. Voici une fonction réutilisable :

async function sendTextMessage(to, text) {
  const payload = {
    messaging_product: 'whatsapp',
    recipient_type: 'individual',
    to: to,  // format international : 221XXXXXXXXX
    type: 'text',
    text: {
      preview_url: false,
      body: text
    }
  };

  try {
    const response = await axios.post(BASE_URL, payload, { headers: HEADERS });
    console.log('Message envoyé :', response.data);
    return response.data;
  } catch (error) {
    console.error('Erreur envoi :', error.response?.data || error.message);
    throw error;
  }
}

// Exemple : envoyer un message à un client au Sénégal
sendTextMessage('221771234567', 'Bonjour ! Votre commande a bien été confirmée.');

Pour aller plus loin, vous pouvez envoyer des messages avec des templates approuvés (HSM), ce qui est obligatoire pour initier une conversation hors d'une fenêtre de 24 heures :

async function sendTemplateMessage(to, templateName, languageCode, components) {
  const payload = {
    messaging_product: 'whatsapp',
    to: to,
    type: 'template',
    template: {
      name: templateName,
      language: { code: languageCode },
      components: components
    }
  };

  const response = await axios.post(BASE_URL, payload, { headers: HEADERS });
  return response.data;
}

// Envoyer un rappel de livraison avec paramètres
sendTemplateMessage(
  '22507123456',
  'confirmation_livraison',
  'fr',
  [
    {
      type: 'body',
      parameters: [
        { type: 'text', text: 'Kofi Asante' },
        { type: 'text', text: '15 mars à 14h' }
      ]
    }
  ]
);

Gérer les webhooks entrants avec Express

Les webhooks permettent de recevoir les réponses de vos clients en temps réel. C'est le cœur d'un chatbot ou d'un système de support. Voici comment configurer un serveur Express pour recevoir et vérifier les webhooks Meta :

const express = require('express');
const app = express();
app.use(express.json());

// Vérification initiale du webhook (étape Meta Developer)
app.get('/webhook', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === process.env.VERIFY_TOKEN) {
    console.log('Webhook vérifié avec succès');
    res.status(200).send(challenge);
  } else {
    res.sendStatus(403);
  }
});

// Réception des messages entrants
app.post('/webhook', (req, res) => {
  const body = req.body;

  if (body.object === 'whatsapp_business_account') {
    body.entry?.forEach(entry => {
      entry.changes?.forEach(change => {
        const messages = change.value?.messages;
        if (messages) {
          messages.forEach(message => {
            console.log(`Message reçu de ${message.from} : ${message.text?.body}`);
            // Votre logique de traitement ici
            handleIncomingMessage(message);
          });
        }
      });
    });
  }

  res.sendStatus(200);
});

async function handleIncomingMessage(message) {
  const from = message.from;
  const text = message.text?.body?.toLowerCase();

  if (text === 'commande') {
    await sendTextMessage(from, 'Pour passer une commande, envoyez votre liste de produits.');
  } else if (text === 'solde') {
    await sendTextMessage(from, 'Votre solde actuel est de 15 000 FCFA.');
  }
}

app.listen(3000, () => console.log('Serveur webhook actif sur le port 3000'));

Pour exposer ce serveur en développement local, utilisez ngrok : ngrok http 3000. Enregistrez l'URL HTTPS générée dans votre tableau de bord Meta Developer.

Structurer son projet pour la production

En production, une architecture robuste s'impose. Voici les bonnes pratiques pour un contexte africain où la connectivité peut être instable :

Gestion des retentatives : implémentez un mécanisme de retry avec backoff exponentiel pour les erreurs temporaires (codes 429, 500, 503). L'article sur la gestion des erreurs WhatsApp API détaille cette approche.

File d'attente de messages : utilisez une queue (Bull, BullMQ avec Redis) pour éviter les dépassements de rate limit lors d'envois en masse. Cela est particulièrement utile lors de campagnes promotionnelles ciblant des milliers de clients.

Logging : journalisez chaque requête et réponse pour le débogage et la conformité. Stockez au minimum le numéro destinataire, l'horodatage, le statut de livraison et l'identifiant de message retourné par l'API.

Sécurité : ne stockez jamais votre token d'accès dans le code source. Utilisez des variables d'environnement ou un gestionnaire de secrets (AWS Secrets Manager, HashiCorp Vault). Vérifiez également la signature des webhooks entrants avec le X-Hub-Signature-256 fourni par Meta.

const crypto = require('crypto');

function verifyWebhookSignature(req, res, next) {
  const signature = req.headers['x-hub-signature-256'];
  const body = JSON.stringify(req.body);
  const expectedSig = 'sha256=' + crypto
    .createHmac('sha256', process.env.APP_SECRET)
    .update(body)
    .digest('hex');

  if (signature !== expectedSig) {
    return res.sendStatus(403);
  }
  next();
}

Combinez cette intégration Node.js avec Whakup pour bénéficier d'une interface no-code au-dessus de votre infrastructure, gérer les templates, les segments et l'analyse des performances. Découvrez comment automatiser vos flux WhatsApp sans sacrifier la personnalisation technique.

FAQ

Q: Ai-je besoin d'un compte Meta Business vérifié pour utiliser l'API WhatsApp Cloud ?

R: Oui, un compte Meta Business vérifié est nécessaire pour accéder à l'API WhatsApp Cloud en production. En phase de développement, vous pouvez tester avec un numéro de test fourni par Meta sans vérification complète, mais les envois seront limités à 5 numéros autorisés manuellement.

Q: Quelle est la différence entre l'API Cloud de Meta et l'API On-Premise ?

R: L'API Cloud est hébergée par Meta, ne nécessite aucune infrastructure serveur de votre côté et inclut les mises à jour automatiques. L'API On-Premise (dépréciée depuis 2023) était hébergée sur vos propres serveurs. Pour les nouveaux projets, l'API Cloud est la seule option recommandée.

Q: Comment tester l'envoi de messages sans numéro de production ?

R: Meta fournit un numéro de test dans le tableau de bord Developer. Vous pouvez envoyer jusqu'à 1000 messages de test par mois vers des numéros que vous avez préalablement autorisés. C'est suffisant pour valider votre intégration Node.js avant la mise en production.

Q: Peut-on envoyer des messages à des numéros sans indicatif pays dans Node.js ?

R: Non, l'API WhatsApp exige le format international complet sans le signe +. Pour un numéro sénégalais 077 123 45 67, vous devez passer 221771234567. Pensez à normaliser les numéros côté serveur avant l'envoi pour éviter les erreurs.

Q: Comment gérer les accusés de réception et les statuts de livraison en Node.js ?

R: Les statuts de livraison (sent, delivered, read) arrivent via les webhooks dans l'objet statuses du payload. Écoutez ces événements dans votre handler /webhook et mettez à jour votre base de données en conséquence pour un suivi précis de chaque message.

---

Prêt à construire votre intégration WhatsApp en Node.js ? Créez votre compte Whakup gratuitement et connectez votre application à une plateforme marketing complète, sans repartir de zéro.