· 5 min · TextMeFlow Team

WhatsApp-Webhook: Fotos, Dokumente und Sprachnachrichten

Die meisten Webhook-Anleitungen behandeln nur den einfachen Fall: Ein Kunde tippt eine Antwort, du bekommst einen String, du speicherst ihn. Aber ein echtes Gespräch enthält auch ein Foto eines beschädigten Teils, ein signiertes PDF, eine Sprachnachricht statt einer getippten Antwort. Erwartet dein Webhook-Handler, dass message immer Text ist, bringt dieser Verkehr ihn entweder zum Absturz oder geht stillschweigend verloren. So kommen eingehende Medien tatsächlich an und so gehst du damit um.

Was an deinem Endpunkt ankommt

Jede eingehende Nachricht – Text oder Medien – erreicht deine Webhook-URL als derselbe POST mit derselben JSON-Struktur. Das Feld, das sich ändert, ist type:

{
  "type": "image",
  "from": "32472932208",
  "from_name": "Jan Janssens",
  "to": "32499123456",
  "file": "https://cdn.textmeflow.eu/media/a1b2c3d4.jpg",
  "message": "hier ist der Schaden an der Stoßstange",
  "from_me": false,
  "wa_message_id": "3EB0A1B2C3D4E5F6",
  "message_id": null
}

type ist einer von text, image, audio, video, document oder location. Bei einer reinen Textnachricht ist file der literale String "null" (so belassen für die Drop-in-Kompatibilität mit Integrationen im TextMeBot-Stil). Bei image, video, audio und document ist file eine URL zur Mediendatei, gehostet von TextMeFlow – hole sie ab, bevor du sie brauchst, denn du solltest nicht davon ausgehen, dass sie unbegrenzt verfügbar bleibt. Ein Foto ohne Bildunterschrift kommt mit leerem message an; ein document trägt den ursprünglichen Dateinamen in message statt eines Beschriftungstexts. Die vollständige Feldreferenz findest du in der Dokumentation zu eingehenden Webhooks.

Nach Typ verzweigen, bevor du message anfasst

Der Fehler, den wir am häufigsten sehen: Code, der db.save(body.message) ausführt und type nie prüft. Für text ist das in Ordnung, aber bei einem document speicherst du einen Dateinamen statt Inhalt, und bei image/audio/video speicherst du einen leeren String und verlierst die Datei stillschweigend. Verzweige also zuerst:

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 ist der Sonderfall: Es gibt keine Datei zum Abholen, message ist einfach der String "lat,lng" – nützlich für eine Einsatzbestätigung „ich bin an der Adresse" oder eine Abholanfrage für einen Kurier.

Die Datei herunterladen

Behandle die file-URL wie jeden anderen Remote-Abruf – lade sie serverseitig herunter und gib keine per Hotlink eingebundene TextMeFlow-URL an dein Frontend oder an Dritte weiter. Ein minimaler Schritt zum Herunterladen und Speichern:

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 });
}

Eine Werkstatt, die ein Foto einer Delle im Blech erhält, ein Umzugsunternehmen, das ein signiertes Inventar-PDF zurückbekommt, oder eine Praxis, die eine Sprachnachricht von einem Patienten erhält, der lieber spricht als tippt – alle drei laufen über genau denselben Weg. Braucht dein Unternehmen den tatsächlichen MIME-Typ oder die Dateiendung statt einer Vermutung, lies sie aus den heruntergeladenen Bytes oder aus dem Content-Type-Header der Antwort aus, statt dem Suffix der URL zu vertrauen.

Eigene ausgehende Nachrichten nicht doppelt speichern

from_me: true bedeutet, dass die Nachricht in der Payload von deiner Nummer gesendet wurde – über die API oder von Hand in WhatsApp selbst getippt. So rekonstruierst du einen vollständigen Gesprächsverlauf. Ist from_me wahr und die Nachricht wurde über die API gesendet, enthält message_id die ID, die du beim Senden zurückbekommen hast, sodass du sie mit deiner eigenen Outbox abgleichen und doppeltes Speichern vermeiden kannst. message_id ist null für alles, was von Hand getippt wurde, und für alles, was vom Kunden hereinkommt – nutze stattdessen wa_message_id als allgemeinen Deduplizierungsschlüssel, da Wiederholungen denselben Wert wiederverwenden.

Die Signatur prüfen, bevor irgendetwas davon läuft

Nichts davon sollte laufen, bevor du X-TextMeFlow-Signature gegen den rohen Request-Body geprüft hast – siehe WhatsApp-Webhook-Signaturen verifizieren für die HMAC-Prüfung in PHP, Node und Python. Überspringst du das, kann jeder, der deine Endpunkt-URL findet, gefälschte „eingehendes Foto"-Ereignisse in dein System posten.

Bei eingehenden Medien steckt viel wirklich nützliche Automatisierung – Zustellnachweis-Fotos, signierte Verträge, Support-Tickets per Sprachnachricht – und es braucht nur ein paar zusätzliche Zeilen Verzweigung, um sie korrekt zu verarbeiten, statt sie unter den Tisch fallen zu lassen. Starte kostenlos und verbinde einen Webhook-Endpunkt mit deiner eigenen Nummer, um die Payloads selbst zu sehen.

Selbst WhatsApp-Nachrichten per API senden?

Für immer gratis bis 50 Nachrichten/Monat. QR scannen und in 5 Minuten die erste Nachricht senden.

Für immer gratis