· 5 min · TextMeFlow Team

Webhook WhatsApp : photos, documents et messages vocaux

La plupart des guides sur les webhooks ne traitent que le cas facile : un client tape une réponse, vous recevez une chaîne de caractères, vous la stockez. Or une vraie conversation comprend aussi la photo d'une pièce endommagée, un PDF signé, un message vocal à la place d'une réponse écrite. Si votre gestionnaire de webhook s'attend à ce que message soit toujours du texte, ce trafic le fait planter ou disparaît en silence. Voici comment les médias entrants arrivent réellement et comment les traiter.

Ce qui arrive sur votre point de terminaison

Chaque message entrant, texte ou média, atteint l'URL de votre webhook sous la forme du même POST avec la même structure JSON. Le champ qui change est type :

{
  "type": "image",
  "from": "32472932208",
  "from_name": "Jan Janssens",
  "to": "32499123456",
  "file": "https://cdn.textmeflow.eu/media/a1b2c3d4.jpg",
  "message": "voici les dégâts sur le pare-chocs",
  "from_me": false,
  "wa_message_id": "3EB0A1B2C3D4E5F6",
  "message_id": null
}

type vaut text, image, audio, video, document ou location. Pour un simple message texte, file est la chaîne littérale "null" (conservée ainsi pour une compatibilité directe avec les intégrations de type TextMeBot). Pour image, video, audio et document, file est l'URL du fichier média, hébergé par TextMeFlow : récupérez-le avant d'en avoir besoin, car il ne faut pas supposer qu'il reste disponible indéfiniment. Une photo envoyée sans légende arrive avec un message vide ; un document transporte le nom de fichier d'origine dans message plutôt qu'un texte de légende. La référence complète des champs se trouve dans la documentation des webhooks entrants.

Aiguillez selon le type avant de toucher à message

Le bug que nous voyons le plus souvent : un code qui exécute db.save(body.message) sans jamais vérifier type. C'est correct pour text, mais pour un document vous stockerez un nom de fichier au lieu du contenu, et pour image/audio/video vous stockerez une chaîne vide et perdrez le fichier en silence. Aiguillez donc d'abord :

app.post('/textmeflow-inbound', async (req, res) => {
  // ...signature check first, see /docs/webhooks...
  const body = JSON.parse(raw.toString('utf8'));

  switch (body.type) {
    case 'text':
      await saveReply(body.from, body.message);
      break;
    case 'image':
    case 'video':
    case 'audio':
    case 'document':
      await downloadAndStore(body.from, body.file, body.message, body.type);
      break;
    case 'location':
      const [lat, lng] = body.message.split(',');
      await saveLocation(body.from, lat, lng);
      break;
  }

  res.sendStatus(200);
});

location fait figure d'exception : il n'y a aucun fichier à récupérer, message est simplement la chaîne "lat,lng", utile pour une confirmation d'intervention « je suis à l'adresse » ou une demande d'enlèvement par un coursier.

Télécharger le fichier

Traitez l'URL file comme n'importe quelle autre récupération distante : téléchargez-la côté serveur, ne transmettez pas une URL TextMeFlow en hotlink à votre frontend ni à un tiers. Une étape minimale de téléchargement et de stockage :

async function downloadAndStore(from, url, caption, type) {
  const res = await fetch(url);
  const buffer = Buffer.from(await res.arrayBuffer());
  const ext = { image: 'jpg', video: 'mp4', audio: 'ogg', document: 'pdf' }[type];
  const key = `inbound/${from}/${Date.now()}.${ext}`;
  await storage.put(key, buffer);
  await db.saveAttachment({ from, key, caption, type });
}

Un garage qui reçoit la photo d'une tôle bosselée, une entreprise de déménagement qui récupère un PDF d'inventaire signé, ou un cabinet qui reçoit un message vocal d'un patient qui préfère parler que taper : les trois passent exactement par le même chemin. Si votre activité a besoin du véritable type MIME ou de l'extension plutôt que d'une supposition, lisez-les à partir des octets téléchargés ou de l'en-tête Content-Type de la réponse au lieu de vous fier au suffixe de l'URL.

Ne sauvegardez pas deux fois vos propres messages sortants

from_me: true signifie que le message de la charge utile a été envoyé par votre numéro, via l'API ou saisi à la main dans WhatsApp lui-même. C'est ainsi que vous reconstituez un fil de conversation complet. Lorsque from_me est vrai et que le message a été envoyé via l'API, message_id contient l'identifiant reçu lors de l'envoi, ce qui vous permet de le rapprocher de votre propre boîte d'envoi et d'éviter un double stockage. message_id vaut null pour tout ce qui a été saisi à la main et pour tout ce qui provient du client ; utilisez plutôt wa_message_id comme clé générale de dédoublonnage, puisque les nouvelles tentatives réutilisent la même valeur.

Vérifiez la signature avant tout cela

Rien de ce qui précède ne doit s'exécuter avant d'avoir vérifié X-TextMeFlow-Signature par rapport au corps brut de la requête ; voyez vérifier les signatures des webhooks WhatsApp pour la vérification HMAC en PHP, Node et Python. Si vous l'omettez, quiconque découvre l'URL de votre point de terminaison peut injecter de faux événements « photo entrante » dans votre système.

Les médias entrants sont l'endroit où se trouve une grande part d'automatisation vraiment utile (photos de preuve de livraison, contrats signés, tickets de support par message vocal), et il suffit de quelques lignes d'aiguillage supplémentaires pour les traiter correctement au lieu de les laisser tomber. Commencez gratuitement et reliez un point de terminaison webhook à votre propre numéro pour voir les charges utiles par vous-même.

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