AnmeldenKostenlose Testphase starten
Meta Tech Provider

WhatsApp-Webhook-Status: gesendet, zugestellt, gelesen, fehlgeschlagen

Status-Webhooks melden, was mit einer Nachricht passiert ist, die ein Unternehmen über die WhatsApp Cloud API gesendet hat. Sie kommen im messages-Feld mit einem statuses-Array statt eines messages-Arrays: gesendet (ein Häkchen), zugestellt (zwei Häkchen), gelesen (zwei blaue Häkchen), abgespielt bei Sprachnachrichten und fehlgeschlagen mit einem errors-Array. Ordnen Sie statuses[].id der wamid zu, die Ihre Sendeanfrage zurückgegeben hat.

easyCoexistence verbindet die WhatsApp-Business-App-Nummer, die Sie bereits nutzen, über Coexistence mit der Cloud API von Meta.

5

Statuswerte, die Meta sendet: sent, delivered, read, played (erstmaliges Abspielen von Sprachnachrichten) und failed.

3

Eigene Statuswebhooks, die eine ausgehende Nachricht erzeugen kann: sent, delivered und read.

v24.0

Ab dieser Graph-API-Version wird das conversation-Objekt weggelassen, außer bei Nachrichten innerhalb eines Fensters des kostenlosen Einstiegspunkts.

0

Keine APIs zum Abrufen vergangener Webhook-Daten; Meta bittet darum, Payloads beim Eingang zu erfassen und zu speichern.

messages

Der X-EC-Event-Header bei einem weitergeleiteten Status: Statusmeldungen reisen innerhalb von messages-Events, unter value.statuses.

Wo kommen WhatsApp-Statuswebhooks an?

Im selben messages-Feld, das auch Kundennachrichten trägt, im selben Objekt mit derselben entry- und changes-Struktur. Der Unterschied liegt innerhalb von value: Eine eingehende Nachricht hat ein messages-Array, ein Status hat ein statuses-Array. Ein Handler, der nur value.messages liest, verwirft jeden Status ohne Fehlermeldung. metadata.phone_number_id gibt an, welche Ihrer Nummern die Nachricht gesendet hat. Dazu kommt ein contacts-Array mit dem Profilnamen des Kunden, der wa_id und der BSUID, außer bei fehlgeschlagenen Status und beim sent-Status von Gruppennachrichten. Dies ist Metas Beispiel für eine Marketing-Vorlage, die Metas Server verlassen hat:

Meta's example: a marketing message with status sent
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo M."
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918"
              }
            ],
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "sent",
                "timestamp": "1750030073",
                "recipient_id": "16505551234",
                "recipient_user_id": "US.13491208655302741918",
                "conversation": {
                  "id": "72b14d6bd5407799e66f64d1b338e567",
                  "expiration_timestamp": "1750116480",
                  "origin": {
                    "type": "marketing"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "type": "regular",
                  "category": "marketing"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Was bedeutet jeder Statuswert?

Jeder Wert entspricht einer Markierung, die der Kunde in WhatsApp sieht. Ein Status gilt als gelesen erst, nachdem die Nachricht zugestellt wurde. Empfängt ein Kunde eine Nachricht, während der Chat bereits geöffnet ist, sendet Meta read ohne vorherigen delivered-Webhook, als interne Optimierung. Ein Tracker sollte deshalb read auch dann akzeptieren, wenn delivered nie eintraf, und Statusmeldungen nach Rangfolge einordnen, statt eine feste Reihenfolge zu erwarten.

sentLeft Meta's servers. One gray check in WhatsApp.
deliveredReached the customer's device. Two gray checks.
readDisplayed in an open chat on the device. Two blue checks.
playedFirst play of voice messages. Blue microphone.
failedCould not be sent or delivered. Red error triangle, plus an errors array.

Welche Felder enthält ein Statusobjekt?

Weniger als eine Nachricht, und mehrere sind bedingt. Metas Referenz listet auf, wann jedes Feld vorhanden ist:

  • id: die wamid der von Ihnen gesendeten Nachricht, der Schlüssel für den Abgleich.
  • status und timestamp: der Wert und die Unix-Zeit, zu der der Webhook ausgelöst wurde, als String.
  • recipient_id: die Telefonnummer oder Gruppen-ID; entfällt, wenn Sie an eine BSUID gesendet haben und die Nummer nicht verfügbar ist.
  • recipient_user_id: die BSUID des Kunden; entfällt bei einem fehlgeschlagenen Status, wenn Sie an eine Telefonnummer gesendet haben.
  • recipient_type und recipient_participant_id: nur bei Nachrichten an eine Gruppe.
  • biz_opaque_callback_data: nur, wenn Sie es in der Sendeanfrage gesetzt haben.
  • pricing: nur bei sent und bei einem von delivered oder read. errors: nur bei failed.

Wie ordnen Sie einen Status der gesendeten Nachricht zu?

Über die wamid. Die Sendeanfrage antwortet mit messages[0].id, und jede Statusmeldung für diese Nachricht trägt denselben Wert in statuses[].id. Speichern Sie ihn beim Senden neben Ihrem eigenen Datensatz und aktualisieren Sie diesen, wenn Statusmeldungen eintreffen. Behalten Sie dabei den höchsten erreichten Status, damit ein verspätetes delivered ein read nicht überschreibt. Eine Statusmeldung mit einer unbekannten wamid stammt von etwas anderem auf der Nummer, etwa einer Automatisierung, und kann ignoriert oder protokolliert werden.

statuses.mjs: apply status webhooks to your sends (Node.js)
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };

// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
  for (const s of value.statuses ?? []) {
    const rec = sends.get(s.id); // the wamid your send request returned
    if (!rec) continue; // sent by something else, such as an automation
    if (s.status === "failed") {
      rec.status = "failed";
      rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
    } else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
      rec.status = s.status; // read arriving before delivered is fine; never step back
    }
    rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
  }
}

Was ändert sich bei einer Coexistence-Nummer?

Statusmeldungen beschreiben, was über die API gesendet wurde: Antworten Ihrer Automatisierungen, Nachrichten, die Ihre KI über einen MCP-Connector gesendet hat, und alles, was Ihr eigener Code gesendet hat. Was der Inhaber in der WhatsApp-Business-App tippt, erreicht die Software auf anderem Weg, als smb_message_echoes, die Meta als Spiegel der app-gesendeten Nachrichten dokumentiert. Nachrichten, die beim einmaligen Verlaufsimport übernommen wurden, tragen ihren Status innerhalb des history-Webhooks, mit Werten wie delivered, read, played, pending und error.

Statusmeldungen gehen dorthin, wohin das messages-Feld der Nummer geht. Bei direktem Ziel sendet Meta sie direkt an Ihren Endpoint, weil messages ein Feld ist, das Meta für ein Ziel überschreiben lässt. Mit eingeschalteten Automatisierungen und gesetzter Forward-URL erreichen sie diese URL als messages-Events.

Wie erfährt Ihre KI oder Automatisierung, ob eine Nachricht zugestellt wurde?

Über Ihr Ziel, nicht über den Sendevorgang. Wenn ein Assistent send_template oder send_message aufruft, enthält das Tool-Ergebnis die wamid und besagt, dass Meta die Nachricht angenommen hat. Die Zustellung wird später auf dem Gerät des Kunden bestätigt und als Status gemeldet. easyCoexistence speichert keinen Statusverlauf, den man abfragen könnte, und kein MCP-Tool liest Statusmeldungen. Ein Agent, der eine Zustellbestätigung braucht, sollte deshalb über Ihr System senden oder die Statusmeldungen lesen, die Ihre Forward-URL empfängt.

Dasselbe gilt für Automatisierungen: Ein Lauf im Tab Runs zeigt den Antwortschritt als erledigt, sobald Meta die Nachricht angenommen hat. Ein danach gemeldeter Fehler erscheint nur als fehlgeschlagener Status an Ihrem Ziel.

Häufige Fehler

  • Ein eigenes statuses-Feld suchen. Statusmeldungen kommen über messages; ein Handler, der nur value.messages liest, verliert sie ohne jede Fehlermeldung.
  • delivered vor read verlangen. Meta überspringt den delivered-Webhook, wenn die Nachricht bei Eingang sofort gelesen wird.
  • Die Sendeantwort als Zustellung verstehen. Eine wamid bedeutet, dass Meta die Anfrage angenommen hat; ein Fehler kann Minuten später als failed-Status folgen.
  • Kunden allein über recipient_id zuordnen. Das Feld entfällt, wenn Sie an eine BSUID gesendet haben und die Telefonnummer nicht verfügbar ist; recipient_user_id trägt die BSUID.
Mit EasyCoexistence

Statusmeldungen zu dem, was Ihre Automatisierungen, Ihre KI oder Ihr Code senden, gehen an Ihren Server: direkt von Meta im Direktmodus oder weitergeleitet an Ihre Forward-URL und mit X-EC-Signature signiert, wenn Automatisierungen aktiv sind. Standardmäßig werden sie nicht gespeichert. US$ 9 bis US$ 0.75 pro Nummer und Monat, sinkend mit jeder weiteren Nummer. Die ersten 3 Tage sind eine kostenlose Testphase.

Häufig gestellte Fragen

Enthalten Statuswebhooks den Text der Nachricht?

Nein. Ein Status enthält die wamid, den Status, den Empfänger, Zeitstempel und, wo zutreffend, Preisangaben und Fehler. Bewahren Sie eine eigene Kopie des Gesendeten auf, geschlüsselt nach wamid, wenn Sie es neben seinem Status anzeigen möchten.

Kann ich vergangene Statusmeldungen später bei Meta abrufen?

Nein. Metas Webhook-Anleitung sagt, dass es keine APIs zum Abrufen historischer Webhook-Daten gibt. Ein Status, den Ihr Endpoint nicht erfasst hat, ist verloren, sobald Meta die Wiederholungsversuche einstellt, nach bis zu 7 Tagen.

Wofür ist biz_opaque_callback_data?

Es ist eine Zeichenkette, die Sie beim Senden setzen, etwa Ihre eigene Bestell- oder Ticket-ID. Meta gibt sie in den statuses dieser Nachricht zurück, sodass Sie einen Status Ihrem Datensatz zuordnen können, ohne zuerst die wamid nachzuschlagen.

Muss ich Statuswebhooks mit 200 beantworten?

Ja, wie jeden Webhook-POST. Meta wertet jede andere Antwort als fehlgeschlagene Zustellung und wiederholt sie. So erreicht Sie derselbe Status manchmal zweimal.

Weiterlesen

Bereit für den Start?

Richten Sie WhatsApp Coexistence in wenigen Minuten statt Monaten ein. Die App funktioniert weiterhin auf dem Telefon.

Kostenlose Testphase starten

Verifiziert am