Créer un bot de menu WhatsApp en Node.js avec Express
Un bot à mots-clés répond à un message à la fois. Un bot de menu, lui, se souvient de l'endroit où en est le client dans la conversation — « 1 pour le support, 2 pour la facturation », puis une question complémentaire dans cette branche. Ce petit bout d'état fait toute la différence entre un bot qui sonne comme un script et un bot qui ressemble à un vrai accueil. Ce tutoriel en construit un en Node.js avec Express, en s'appuyant sur l'API TextMeFlow pour l'envoi et la réception.
Ce qu'il vous faut
- Un compte TextMeFlow avec un numéro WhatsApp couplé par QR (guide de démarrage)
- Votre clé API et votre secret webhook, disponibles dans le portail
- Node.js 18+ avec
expressinstallé
Étape 1 — le endpoint webhook
TextMeFlow envoie chaque message entrant en POST à l'URL de votre webhook, au format JSON, signé en HMAC-SHA256 dans l'en-tête X-TextMeFlow-Signature (sha256=<hex>). Le seul piège propre à Express : vous devez lire le corps brut de la requête avant que tout middleware d'analyse JSON n'y touche, sinon la vérification de la signature échouera sur des octets resérialisés. Montez donc express.raw() sur la route du webhook, et non de façon globale :
import express from "express";
import crypto from "crypto";
const app = express();
const WEBHOOK_SECRET = process.env.TMF_WEBHOOK_SECRET;
const API_KEY = process.env.TMF_API_KEY;
const API_URL = "https://api.textmeflow.eu/v1/messages";
app.post(
"/webhook",
express.raw({ type: "application/json" }),
async (req, res) => {
const expected =
"sha256=" +
crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.body).digest("hex");
const received = req.header("X-TextMeFlow-Signature") || "";
const a = Buffer.from(expected);
const b = Buffer.from(received);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body);
await handleMessage(event);
res.sendStatus(200);
}
);
crypto.timingSafeEqual lève une erreur si les deux buffers n'ont pas la même longueur : vérifiez donc d'abord ce point — une longueur différente signifie simplement « mauvaise signature », pas un plantage. La référence complète sur les en-têtes et les nouvelles tentatives se trouve dans le guide des signatures webhook.
Étape 2 — suivre l'état de la conversation
Une Map indexée par le numéro de l'expéditeur suffit pour un bot à processus unique :
const sessions = new Map(); // phone -> { step: string }
async function handleMessage(event) {
const from = event.from;
const text = (event.message || "").trim().toLowerCase();
const session = sessions.get(from) || { step: "root" };
let reply;
if (session.step === "root") {
if (text === "1") {
reply = "Support — décrivez votre problème en un seul message et nous reviendrons vers vous.";
session.step = "support";
} else if (text === "2") {
reply = "Facturation — répondez avec votre numéro de commande.";
session.step = "billing";
} else {
reply = "Bonjour ! Répondez 1 pour le support, 2 pour la facturation.";
}
} else if (session.step === "support" || session.step === "billing") {
reply = "Merci, un membre de l'équipe vous répondra très prochainement.";
session.step = "root"; // retour au début une fois la branche traitée
}
sessions.set(from, session);
if (reply) await sendMessage(from, reply);
}
Deux points comptent pour que tout fonctionne : remettez step sur root dès qu'une branche est traitée (sinon le client reste bloqué), et traitez toute saisie non reconnue dans root comme une demande d'affichage du menu plutôt que par le silence — contrairement à un simple bot à mots-clés, un bot de menu doit toujours indiquer au client quelles sont ses options.
Étape 3 — envoyer la réponse
async function sendMessage(to, text) {
const res = await fetch(API_URL, {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ to, text }),
});
if (!res.ok) throw new Error(`send failed: ${res.status}`);
}
Les réponses comptent dans le quota mensuel de votre forfait et dans les limites de débit par compte. Un bot de menu qui répond à de vrais clients reste donc largement dans les 50 messages par mois du forfait gratuit pour les tests, ou dans les 500 par mois de Starter en production.
Étape 4 — respecter le pipeline anti-spam
Deux choses se produisent automatiquement et n'ont pas à être codées dans votre bot : STOP (et ses variantes) est géré au niveau de l'API, de sorte qu'un destinataire désinscrit est bloqué avant même que votre webhook ne soit rappelé, et les messages envoyés entre 22h00 et 08h00, heure locale du destinataire, sont différés à 08h00 sauf si vous passez "urgent": true — ce qui vaut la peine pour une confirmation de facturation, mais pas pour une réponse de menu qui peut attendre le matin.
Étape 5 — lancer et tester
export TMF_API_KEY=... TMF_WEBHOOK_SECRET=...
node server.js
Pendant le développement, exposez le port avec un tunnel (ngrok ou équivalent), définissez cette URL comme endpoint webhook dans le portail TextMeFlow, puis écrivez à votre propre numéro pour parcourir le menu.
Passer à l'échelle au-delà d'un seul processus
Une Map en mémoire disparaît au redémarrage et ne partage pas son état entre plusieurs instances de serveur. Dès que vous exécutez plus d'un processus — ou que vous utilisez le multi-appareils du plan Business — remplacez-la par Redis avec un TTL court (une session de menu inactive depuis 30 minutes devrait de toute façon être réinitialisée).
Prêt à brancher tout cela sur un vrai numéro ? Le forfait gratuit comprend 50 messages par mois, pour toujours — de quoi construire et tester tout le flux. Créez votre compte gratuit.
Envie d'envoyer des messages WhatsApp via API ?
Gratuit pour toujours jusqu'à 50 messages/mois. Scannez un QR et envoyez votre premier message en 5 minutes.
Gratuit pour toujours