Webhooks WhatsApp : quels événements TextMeFlow envoie-t-il ?
Vous avez configuré une URL de webhook et TextMeFlow envoie des données à votre serveur, mais quels événements exactement, et que contient chaque payload ? Cet aperçu vous aide à décider quels événements capter et lesquels ignorer.
Pourquoi des événements (et pas seulement « message reçu »)
La plupart des intégrations ne pensent qu'aux messages entrants, mais une connexion WhatsApp génère plus de signaux que cela : statut de livraison, état de session de l'appareil relié et messages d'erreur. Si vous ne réagissez qu'aux messages entrants, vous ne verrez pas, par exemple, que votre numéro a perdu la connexion et que les messages sortants n'arrivent plus depuis un moment.
Chaque appel de webhook est un POST avec un corps JSON et un champ event qui indique le type. Pour vérifier correctement la signature HMAC de chaque appel, consultez notre guide dédié sur la vérification des signatures de webhook ; cet article se concentre sur les événements eux-mêmes.
message.received
L'événement le plus utilisé : quelqu'un envoie un message WhatsApp à votre numéro relié. Le payload contient le numéro de l'expéditeur, le type de message (texte, image, document, localisation, …), le contenu ou l'URL du média, et un horodatage. C'est l'événement sur lequel vous construisez vos chatbots, réponses automatiques et routage de tickets.
Attention : les médias (photos, PDF, messages vocaux) ne sont pas intégrés au payload, mais fournis sous forme d'URL de téléchargement temporaire. Récupérez le fichier immédiatement : l'URL n'est pas valable indéfiniment.
message.delivered et message.read
Pour les messages sortants que vous avez envoyés vous-même via l'API, vous recevez des mises à jour de statut :
message.delivered: le message est arrivé sur l'appareil du destinataire.message.read: le destinataire a ouvert le message (coche bleue), pour autant qu'il n'ait pas désactivé cette fonction de son côté.
Ces événements sont idéaux pour construire des tableaux de bord de livraison ou pour détecter qu'un numéro donné n'est systématiquement pas joint, souvent signe d'un numéro erroné ou désactivé, et non d'un problème de votre côté.
message.failed
Un message sortant n'a pas pu être livré. Le payload contient un code d'erreur et sa description. Il s'agit le plus souvent d'un numéro invalide ou qui n'est pas sur WhatsApp, d'un destinataire qui vous a bloqué, ou d'une erreur de livraison temporaire chez WhatsApp lui-même. Construisez une logique de nouvelle tentative avec modération : renvoyer aveuglément après un failed augmente votre score de risque dans le pipeline anti-spam.
session.connected et session.disconnected
Ces deux événements ne concernent pas les messages, mais l'état de l'appareil WhatsApp relié lui-même :
session.connected: l'appareil est (re)lié et actif. Cet événement se déclenche aussi lors d'une reconnexion, pas seulement lors de la première liaison.session.disconnected: la liaison est rompue (appareil hors ligne, WhatsApp déconnecté, problème réseau). À partir de ce moment, plus aucun message n'est envoyé ni reçu tant que l'appareil n'est pas relié à nouveau.
Pour tout environnement de production, il est conseillé d'envoyer une alerte sur session.disconnected (Slack, e-mail, outil de supervision) : c'est l'événement que vous voulez connaître le plus vite, car sans session active, tout votre canal WhatsApp est à l'arrêt.
En pratique : un endpoint, un switch
La plupart des équipes traitent tous les événements sur un seul endpoint de webhook et routent en interne selon le champ event :
app.post('/webhooks/textmeflow', (req, res) => {
const { event, data } = req.body;
switch (event) {
case 'message.received':
handleIncoming(data);
break;
case 'message.delivered':
case 'message.read':
updateDeliveryStatus(data);
break;
case 'message.failed':
logFailure(data);
break;
case 'session.disconnected':
alertTeam(data);
break;
}
res.sendStatus(200);
});
Répondez toujours rapidement avec un statut 2xx, même si votre traitement est asynchrone : sinon TextMeFlow interprète l'appel comme un échec et une nouvelle tentative suit, ce qui peut entraîner un double traitement si vous n'êtes pas idempotent.
Pour démarrer
Configurez votre URL de webhook dans le tableau de bord et testez avec un message à vous-même : vous verrez immédiatement arriver message.received, suivi de message.delivered dès que WhatsApp le confirme. Pas encore de compte ? Démarrez gratuitement avec 50 messages par mois, pour toujours : inscrivez-vous ici.
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