📍 Article principal de la serie : WhatsApp Cloud API en 2026 : architecture, webhooks, templates et intégrations
Un utilisateur qui doit écrire « 1 », « menu », « info », « tarif » pour naviguer dans votre chatbot WhatsApp abandonne la conversation deux fois plus vite qu’un utilisateur qui touche un bouton. Le clavier mobile est une friction, l’orthographe libre génère des erreurs de routage, et les FAQ en texte libre demandent un parsing fragile (regex, NLP, fallback LLM) que l’on cherche a éviter quand le parcours est connu d’avance. Les messages interactifs natifs WhatsApp Reply Buttons et List Messages resolvent ce problème : le client touche, votre webhook reçoit un identifiant deterministe, le routage est trivial. Conversion plus haute, code plus simple, support utilisateur réduit. Ce tutoriel montre comment construire un bot menu de bout en bout en Node.js, avec persistance d’état et timeout de fenêtre 24h.
Prerequis
Avant de coder le routage des boutons, l’environnement doit être opérationnel. Vous devez disposer d’un compte WhatsApp Business Cloud API configuré (numéro vérifie dans Meta Business Manager, application Meta avec produit WhatsApp ajoute, jeton d’acces permanent ou rotatif), d’un webhook HTTPS déjà recevant les événements messages (le tutoriel Webhooks WhatsApp avec Node.js et Express couvre cette partie), et de Node.js 20 ou supérieur. Si vous n’avez pas encore configuré tout cela, commencez par le guide principal liste plus haut. Le code de cet article suppose que vous avez déjà un endpoint POST /webhook qui reçoit les payloads Meta et un endpoint GET /webhook qui répond au challenge de vérification.
Côté dépendances, nous utiliserons express pour le serveur HTTP, axios pour appeler l’API Graph, ioredis pour la persistance d’état (alternative better-sqlite3 mentionnée a l’étape 6), et dotenv pour les variables d’environnement (WA_TOKEN, WA_PHONE_ID, WA_VERIFY_TOKEN).
Comprendre les 3 types de messages interactifs
WhatsApp Cloud API propose trois sous-types de messages interactive, chacun adapte à un nombre de choix différent. Bien choisir le sous-type est la première decision UX du bot.
Reply Buttons (sub-type button) affiche jusqu’à trois boutons sous le message. Chaque bouton à un titre visible (20 caractères maximum) et un identifiant cache (256 caractères maximum) renvoye dans le webhook. Adapte aux choix binaires ou ternaires : oui/non, français/anglais, livraison/retrait/annuler. Le rendu est immédiat, le tap est rapide, le taux de sélection dépasse souvent 70 pour cent.
List Messages (sub-type list) affiche un bouton unique qui, une fois tape, ouvre une feuille modale avec une liste organisée. Vous pouvez créer jusqu’à dix sections, et chaque section peut contenir jusqu’à dix items (rows). Chaque item à un titre (24 caractères), une description optionnelle (72 caractères) et un identifiant. Adapte aux menus de catalogue : « voir nos catégories », « sélectionner un creneau », « choisir un service ».
Flow Messages (sub-type flow) lance un mini-formulaire multi-écrans rendu nativement dans WhatsApp. Lance par Meta en 2024 et progressivement deploye sur les clients mobiles puis Web et Desktop fin 2025, c’est l’option la plus puissante quand vous avez besoin de collecter plusieurs champs (nom, adresse, date, montant) en un seul échange. Flows dépasse le cadre de cet article, qui se concentre sur boutons et listes, plus simples a mettre en place et suffisants pour 80 pour cent des cas d’usage.
Étape 1 — Modéliser le parcours conversationnel (state machine simple)
Avant d’ecrire la moindre ligne d’envoi, dessinez sur papier le graphe d’états. Un menu interactif est une machine a états finis : chaque écran est un état, chaque tap de bouton est une transition. Sans ce schema, vous ecrirez du code spaghetti avec des if imbriques que personne ne pourra maintenir dans trois mois.
Pour notre bot d’exemple, une boutique d’epicerie en ligne, le parcours minimal contient cinq états : WELCOME (menu principal avec boutons), BROWSING (liste des catégories), PRODUCT (fiche produit avec boutons ajouter/retour), CART (recapitulatif et boutons valider/annuler), CHECKOUT (saisie texte libre pour adresse). Chaque état décrit ce que le bot vient d’envoyer ; quand un message entrant arrive, le routeur consulte l’état courant pour decider quoi faire.
Voici la structure de base que nous allons remplir au fil des étapes. Definissez les états comme constantes pour éviter les fautes de frappe :
// states.js
const STATES = {
WELCOME: 'WELCOME',
BROWSING: 'BROWSING',
PRODUCT: 'PRODUCT',
CART: 'CART',
CHECKOUT: 'CHECKOUT'
};
module.exports = { STATES };Ce module sera importe partout dans le bot. Chaque fonction d’envoi positionne un état, chaque fonction de réception lit cet état puis le met à jour. Le contrat est strict : aucune chaine en dur, toujours STATES.WELCOME, jamais 'WELCOME'.
Étape 2 — Envoyer un message Reply Buttons
Le payload d’un message interactive de type button suit une structure imbriquee. Le champ action.buttons est un tableau dont chaque élément à un type: "reply" et un objet reply contenant id et title. L’identifiant est ce que vous recevrez en webhook ; le titre est ce que l’utilisateur voit. Choisissez des identifiants stables, courts, semantiques (menu_orders, menu_help) plutôt que numériques : votre code de routage sera plus lisible et le debug en production plus rapide.
// senders.js
const axios = require('axios');
const WA_API = `https://graph.facebook.com/v23.0/${process.env.WA_PHONE_ID}/messages`;
const HEADERS = {
Authorization: `Bearer ${process.env.WA_TOKEN}`,
'Content-Type': 'application/json'
};
async function sendWelcomeButtons(to) {
const payload = {
messaging_product: 'whatsapp',
to,
type: 'interactive',
interactive: {
type: 'button',
body: { text: 'Bienvenue chez Epicerie Baobab. Que voulez-vous faire ?' },
action: {
buttons: [
{ type: 'reply', reply: { id: 'menu_browse', title: 'Voir produits' } },
{ type: 'reply', reply: { id: 'menu_orders', title: 'Mes commandes' } },
{ type: 'reply', reply: { id: 'menu_help', title: 'Parler a un agent' } }
]
}
}
};
return axios.post(WA_API, payload, { headers: HEADERS });
}
module.exports = { sendWelcomeButtons };A l’exécution, l’API Graph répond avec un objet contenant messages[0].id (le wamid du message envoyé) et un statut HTTP 200. Si vous recevez 400 avec (#100) Param interactive[action][buttons][0][reply][title] is too long, c’est que vous avez dépasse les 20 caractères : tronquez et reessayez. Si vous recevez 401, votre token est expire ou invalide.
Étape 3 — Recevoir et router la réponse d’un bouton
Quand l’utilisateur tape un bouton, Meta envoie un webhook au format suivant : entry[0].changes[0].value.messages[0] à un type: "interactive", et l’objet interactive contient type: "button_reply" avec les champs button_reply.id et button_reply.title. Le champ id est exactement celui que vous avez envoyé a l’étape 2 ; c’est le pivot du routage.
// router.js
const { sendWelcomeButtons } = require('./senders');
const { sendCategoryList, sendCart } = require('./senders-list');
async function handleIncoming(msg, from) {
if (msg.type === 'interactive' && msg.interactive.type === 'button_reply') {
const buttonId = msg.interactive.button_reply.id;
switch (buttonId) {
case 'menu_browse':
return sendCategoryList(from);
case 'menu_orders':
return sendCart(from);
case 'menu_help':
return sendHumanHandoff(from);
default:
return sendWelcomeButtons(from);
}
}
// Fallback texte libre
return sendWelcomeButtons(from);
}
module.exports = { handleIncoming };Le switch sur buttonId est exhaustif : chaque identifiant émis a l’étape 2 a son cas. Le default renvoie au menu d’accueil — important pour éviter qu’un utilisateur reste bloque si vous deployez une nouvelle version du bot pendant qu’une session est active avec d’anciens identifiants. Un utilisateur qui tape « menu_browse » et reçoit une liste de catégories en moins d’une seconde percoit le bot comme réactif ; un utilisateur qui reçoit un message d’erreur ferme la conversation.
Étape 4 — Envoyer une List Message
La List Message est plus dense que les Reply Buttons : elle convient quand vous avez quatre choix ou plus, ou quand vous voulez grouper les choix par catégorie. Le payload est plus verbeux, avec un objet action qui contient un button (le label du bouton qui ouvre la modale, 20 caractères maximum) et un tableau sections. Chaque section à un title (24 caractères) et un tableau rows. Chaque row à un id, un title (24 caractères) et une description optionnelle (72 caractères).
Limite clé a mémoriser : vous pouvez avoir jusqu’à 10 sections, mais la somme totale de rows toutes sections confondues ne peut pas dépasser 10. Vous ne pouvez donc pas faire 5 sections de 5 rows chacune. Cette contrainte est vérifiée côté API ; dépasser renvoie une erreur 400.
// senders-list.js
async function sendCategoryList(to) {
const payload = {
messaging_product: 'whatsapp',
to,
type: 'interactive',
interactive: {
type: 'list',
header: { type: 'text', text: 'Nos categories' },
body: { text: 'Selectionnez une categorie pour voir les produits.' },
footer: { text: 'Livraison Dakar 24h' },
action: {
button: 'Parcourir',
sections: [
{
title: 'Frais',
rows: [
{ id: 'cat_fruits', title: 'Fruits', description: 'Mangue, papaye, banane' },
{ id: 'cat_legumes', title: 'Legumes', description: 'Tomate, oignon, gombo' }
]
},
{
title: 'Epicerie seche',
rows: [
{ id: 'cat_riz', title: 'Riz et cereales' },
{ id: 'cat_huile', title: 'Huiles et condiments' }
]
}
]
}
}
};
return axios.post(WA_API, payload, { headers: HEADERS });
}Quatre rows au total, deux sections, sous la limite. Le footer est optionnel mais utile pour rappeler une promesse commerciale (délai de livraison, garantie). Le header peut être de type text, image, video ou document ; commencez en texte, c’est plus rapide a iterer.
Étape 5 — Recevoir et router la sélection d’une liste
Quand l’utilisateur selectionne une row, Meta envoie un webhook avec interactive.type: "list_reply", et l’objet list_reply contient id, title et description (les mêmes que vous avez envoyés). Le routage suit le même pattern qu’a l’étape 3, mais sur un identifiant différent.
// router.js (suite)
async function handleIncoming(msg, from) {
if (msg.type === 'interactive' && msg.interactive.type === 'list_reply') {
const listId = msg.interactive.list_reply.id;
if (listId.startsWith('cat_')) {
return sendProductsForCategory(from, listId);
}
if (listId.startsWith('prod_')) {
return sendProductCard(from, listId);
}
}
// ... reste du routage
}Le prefixe sur l’identifiant (cat_, prod_, order_) permet de regrouper les routes sans switch exhaustif. C’est un pattern qui scale bien quand le catalogue grossit : vous chargez la liste de produits depuis votre base de données au moment d’envoyer la liste, et le routage reste générique.
Étape 6 — Persister l’état de session avec Redis ou SQLite
Sans persistance, le bot est amnesique : à chaque message entrant, vous ignorez ou en etait l’utilisateur. Pour un bot menu pur (chaque écran contient toutes les infos pour decider), l’état n’est pas strictement necessaire. Mais des qu’un utilisateur peut être au milieu d’un panier ou d’un formulaire multi-étapes, il faut stocker au moins son état courant et son contexte (dernier produit consulte, contenu du panier).
Redis est le choix par défaut : faible latence, TTL natif (parfait pour expirer les sessions après 24h, voir étape 7), bibliotheque ioredis stable. Pour un MVP qui tient sur un seul serveur, better-sqlite3 suffit et évite un service supplémentaire.
// session.js
const Redis = require('ioredis');
const redis = new Redis(process.env.REDIS_URL);
const SESSION_TTL = 24 * 60 * 60; // 24h en secondes
async function getSession(phone) {
const raw = await redis.get(`wa:session:${phone}`);
return raw ? JSON.parse(raw) : { state: 'WELCOME', cart: [] };
}
async function setSession(phone, session) {
await redis.set(
`wa:session:${phone}`,
JSON.stringify(session),
'EX',
SESSION_TTL
);
}
module.exports = { getSession, setSession };La clé est prefixee par wa:session: pour éviter les collisions avec d’autres usages Redis. Le TTL de 86400 secondes correspond à la fenêtre de service client WhatsApp ; toute session inactive plus de 24h est automatiquement purgee, ce qui évite que votre Redis grossisse indefiniment. À chaque mise à jour de session, vous reinitialisez le TTL : c’est le comportement par défaut de la commande SET ... EX.
Étape 7 — Gérer le timeout de session (24h fenêtre Meta)
Meta impose une règle stricte : vous ne pouvez envoyer un message libre (texte, interactif, média) à un utilisateur que dans les 24 heures suivant son dernier message entrant. Cette fenêtre est appelee « customer service window » ou « fenêtre de conversation ». Passe ce délai, vous devez envoyer un message basé sur un template préalablement approuvé par Meta (voir Templates WhatsApp et processus d’approbation Meta).
Côté bot menu, cela a deux conséquences. Premierement, votre logique d’envoi doit vérifier le timestamp du dernier message entrant avant d’envoyer un message interactif spontané. Deuxiemement, si l’utilisateur ne répond plus pendant 24h, sa session devient invalide côté Meta même si vous l’avez encore en Redis ; reinitialisez-la à la prochaine interaction.
// session.js (suite)
async function isWindowOpen(phone) {
const lastInbound = await redis.get(`wa:last:${phone}`);
if (!lastInbound) return false;
const ageSec = (Date.now() - parseInt(lastInbound, 10)) / 1000;
return ageSec < 24 * 60 * 60;
}
async function markInbound(phone) {
await redis.set(`wa:last:${phone}`, Date.now().toString(), 'EX', SESSION_TTL);
}Appelez markInbound(from) au tout debut de chaque traitement de message entrant, et isWindowOpen(to) avant tout envoi non sollicite. Si la fenêtre est fermee, basculez sur un template au lieu d’un message libre. Le bon signal de réussite est l’absence d’erreurs 131047 (« Re-engagement message ») dans vos logs : si vous voyez ce code, vous avez tente un envoi libre hors fenêtre.
Étape 8 — Exemple complet : bot de prise de commande pour une epicerie
Assemblons les pièces. Le parcours complet est : utilisateur écrit « bonjour » → bot envoie 3 boutons d’accueil → utilisateur tape « Voir produits » → bot envoie une liste de catégories → utilisateur tape « Fruits » → bot envoie une liste de produits de la catégorie → utilisateur tape « Mangue Kent » → bot envoie une fiche avec 2 boutons « Ajouter au panier » / « Retour » → utilisateur tape « Ajouter » → bot confirme et propose 2 boutons « Continuer » / « Valider commande ». Voici le squelette du fichier principal qui orchestre tout :
// app.js
const express = require('express');
const { getSession, setSession, markInbound } = require('./session');
const {
sendWelcomeButtons,
sendCategoryList,
sendProductsForCategory,
sendProductCard,
sendCartConfirm
} = require('./senders');
const app = express();
app.use(express.json());
app.post('/webhook', async (req, res) => {
res.sendStatus(200); // Accuser reception immediatement
try {
const change = req.body.entry?.[0]?.changes?.[0]?.value;
const msg = change?.messages?.[0];
if (!msg) return;
const from = msg.from;
await markInbound(from);
const session = await getSession(from);
if (msg.type === 'interactive') {
const sub = msg.interactive.type;
if (sub === 'button_reply') {
await routeButton(from, msg.interactive.button_reply.id, session);
} else if (sub === 'list_reply') {
await routeList(from, msg.interactive.list_reply.id, session);
}
} else if (msg.type === 'text') {
await sendWelcomeButtons(from);
session.state = 'WELCOME';
await setSession(from, session);
}
} catch (err) {
console.error('webhook error', err);
}
});
app.listen(3000, () => console.log('Bot up on :3000'));Trois points clés a remarquer. D’abord, res.sendStatus(200) est envoyé avant tout traitement métier : Meta retransmet le webhook si vous ne répondez pas en moins de 20 secondes, ce qui declencherait des doublons. Ensuite, markInbound est appele en premier pour fixer le timestamp avant tout envoi sortant. Enfin, le try/catch englobe tout le traitement asynchrone pour éviter qu’une erreur non gérée fasse crasher le process Node — un crash signifierait que vous avez accuse réception 200 a Meta sans traiter, et le message serait perdu.
Les fonctions routeButton et routeList contiennent les switch présentes aux étapes 3 et 5, enrichis pour mettre à jour session.state à chaque transition. Par exemple, après l’envoi de la liste de catégories, vous positionnez session.state = 'BROWSING' ; après l’ajout au panier, vous faites session.cart.push(productId) et passez en 'CART'.
Étape 9 — Vérification : tester chaque branche du menu
Le bot menu est un graphe ; le test consiste a parcourir chaque arete au moins une fois. Sur WhatsApp, deux niveaux de test sont utiles. Le premier est manuel : prenez votre téléphone, ouvrez la conversation avec le numéro du bot, et jouez chaque parcours nominal (achat réussi) puis chaque parcours degrade (clic sur « Retour », abandon de panier, message texte hors menu). Notez chaque écran qui s’affiche dans un tableau.
Le second niveau est automatise : envoyez des payloads webhook simules à votre serveur local avec curl ou httpie, en imitant le format Meta. Cela permet de tester le routage sans dependre de WhatsApp et sans consommer votre quota de messages. Voici un exemple de simulation d’un tap sur le bouton « Voir produits » :
curl -X POST http://localhost:3000/webhook \
-H "Content-Type: application/json" \
-d '{
"entry": [{
"changes": [{
"value": {
"messages": [{
"from": "221770000000",
"type": "interactive",
"interactive": {
"type": "button_reply",
"button_reply": { "id": "menu_browse", "title": "Voir produits" }
}
}]
}
}]
}]
}'Si le routage est correct, vous devez voir dans les logs du serveur un appel sortant vers graph.facebook.com avec un payload type: list. Repetez cet exercice pour chaque bouton et chaque row. Une checklist en tableur avec une colonne par état et une ligne par identifiant est suffisante ; la passer entièrement avant chaque déploiement évite les regressions.
Erreurs fréquentes
| Symptome | Cause probable | Solution |
|---|---|---|
| HTTP 400 « title is too long » | Titre de bouton ou row dépasse 20 ou 24 caractères | Tronquer côté serveur avant envoi |
| HTTP 400 sur sections | Plus de 10 rows au total dans la liste | Diviser en deux listes ou paginer |
| HTTP 131047 | Envoi libre hors fenêtre 24h | Basculer sur un template approuvé |
| Webhook duplique | Réponse 200 trop lente (timeout 20s) | Répondre 200 avant le traitement async |
| Boutons invisibles côté utilisateur | Application WhatsApp obsolete | Demander mise à jour, fallback texte |
| Routage perdu après redeploiement | Identifiants de boutons modifies | Versionner les ids, garder anciens en compat |
Bonnes pratiques UX pour menus WhatsApp
Limitez chaque écran à une seule decision. Un message qui pose deux questions à la fois oblige l’utilisateur a faire deux taps, et le second tap est souvent perdu si l’application bascule en arriere-plan. Si vous avez besoin de deux infos, faites deux écrans successifs.
Prevoyez toujours un bouton « Retour » ou « Menu principal » sur chaque écran sauf l’accueil. L’utilisateur qui se sent piège ferme la conversation et marque parfois le numéro comme spam, ce qui degrade votre quality rating Meta. Sur les Reply Buttons, gardez deux boutons pour l’action et un pour le retour ; sur les List Messages, ajoutez une row « Retour au menu » en dernière section.
Écrivez les titres en impératif court : « Voir produits » plutôt que « Cliquez ici pour voir les produits ». L’impératif sonne naturel sur mobile et tient dans les 20 caractères. Évitez les emoji dans les titres : ils consomment plusieurs caractères et rendent le rendu inconsistant entre versions de WhatsApp.
Affichez toujours le prix dans la description de la row plutôt que dans le titre. Le titre doit être le nom du produit ; la description (72 caractères) accueille le prix, le poids et un argument court. C’est le pattern utilise par les bots qui convertissent.
Tutoriels frères
- Webhooks WhatsApp avec Node.js et Express : réception fiable des messages entrants
- Templates WhatsApp et processus d’approbation Meta : réactivation hors fenêtre 24h
Pour aller plus loin
Quand votre menu interactif dépasse trois ou quatre niveaux, ou quand vous devez collecter un formulaire complet (adresse de livraison, date de rendez-vous, montant), il devient temps de migrer vers WhatsApp Flows. Les Flows permettent de construire des mini-formulaires multi-écrans rendus nativement, avec validation côté client, sans appels webhook intermediaires. C’est plus rapide pour l’utilisateur et plus simple a maintenir côté serveur.
Pour le paiement intègre dans une commande, regardez le couplage avec un agrégateur mobile money (Wave, Orange Money, Mixx by Yas) déclenche depuis le bouton « Valider commande » : le bot envoie un lien de paiement, le client paie dans une autre appli, votre webhook de paiement met à jour la session Redis et le bot envoie un message de confirmation.
FAQ
Puis-je mettre plus de 3 boutons sur un message Reply Buttons ?
Non, la limite est stricte a 3 boutons par message interactive.type: button. Si vous avez besoin de plus de choix, basculez sur une List Message (jusqu’à 10 rows total) ou sequencez plusieurs messages successifs.
Quelle est la différence entre id et title dans un bouton ?
Le title est ce que l’utilisateur voit (20 caractères maximum), le id est ce que vous recevez dans le webhook (256 caractères maximum). Utilisez des id stables et semantiques, et changez les title librement sans impact sur le routage côté serveur.
Combien de rows puis-je mettre dans une List Message ?
Jusqu’à 10 sections, mais le total cumule de rows toutes sections confondues ne peut pas dépasser 10. Vous pouvez par exemple faire 2 sections de 5 rows, 3 sections de 3+3+4 rows, ou 1 section de 10 rows.
Faut-il payer pour envoyer un message interactif ?
Oui, les messages interactifs sont factures au tarif « service » pendant la fenêtre de 24h ouverte par un message entrant utilisateur, et au tarif « marketing » ou « utility » hors fenêtre via template. Le tarif dépend du pays du destinataire ; consultez la grille Meta à jour.
Mon bot ne reçoit pas les button_reply, que vérifier ?
Vérifiez d’abord que vous etes abonne au champ messages dans la configuration du webhook (Meta App > WhatsApp > Webhooks). Vérifiez ensuite que vous lisez bien msg.interactive.button_reply.id et non msg.button_reply.id (le champ est imbrique sous interactive). Loguez le payload brut entrant pour confirmer la structure.