ΣύνδεσηΞεκινήστε δωρεάν δοκιμή
Meta Tech Provider

Καταστάσεις webhook του WhatsApp: εστάλη, παραδόθηκε, διαβάστηκε και απέτυχε

Τα webhooks κατάστασης αναφέρουν τι συνέβη σε μήνυμα που έστειλε μια επιχείρηση μέσω του WhatsApp Cloud API. Φτάνουν στο πεδίο messages με πίνακα statuses αντί για πίνακα messages: εστάλη (ένα τικ), παραδόθηκε (δύο τικ), διαβάστηκε (δύο μπλε τικ), αναπαράχθηκε (για φωνητικά μηνύματα) και απέτυχε με πίνακα errors. Αντιστοιχίστε το statuses[].id με το wamid που επέστρεψε το αίτημα αποστολής σας.

Το easyCoexistence συνδέει τον αριθμό της εφαρμογής WhatsApp Business που ήδη χρησιμοποιείτε με το Cloud API της Meta μέσω του Coexistence.

5

Τιμές κατάστασης που στέλνει η Meta: `sent`, `delivered`, `read`, `played` (πρώτη αναπαραγωγή φωνητικών μηνυμάτων) και `failed`.

3

Ξεχωριστά webhooks κατάστασης που μπορεί να παράγει ένα εξερχόμενο μήνυμα: `sent`, `delivered` και `read`.

v24.0

Από αυτή την έκδοση του Graph API, το αντικείμενο `conversation` παραλείπεται, εκτός από τα μηνύματα σε παράθυρο δωρεάν σημείου εισόδου.

0

Δεν υπάρχουν API για την ανάκτηση παλαιότερων δεδομένων των webhooks. Η Meta ζητά να καταγράφετε και να αποθηκεύετε τα payloads καθώς φτάνουν.

messages

Η κεφαλίδα X-EC-Event σε προωθημένη κατάσταση: οι καταστάσεις ταξιδεύουν μέσα στα συμβάντα messages, κάτω από το value.statuses.

Πού φτάνουν τα webhooks κατάστασης του WhatsApp;

Στο ίδιο πεδίο messages που μεταφέρει όσα στέλνουν οι πελάτες, στο ίδιο αντικείμενο, entry και changes envelope. Η διαφορά βρίσκεται μέσα στο value: ένα εισερχόμενο μήνυμα έχει πίνακα messages, ενώ μια κατάσταση έχει πίνακα statuses. Ένας χειριστής που διαβάζει μόνο το value.messages χάνει κάθε κατάσταση χωρίς σφάλμα. Το metadata.phone_number_id δείχνει ποιος από τους αριθμούς σας έστειλε το μήνυμα, και έρχεται μαζί ένας πίνακας contacts με το όνομα προφίλ του πελάτη, το wa_id και το BSUID, εκτός από τις αποτυχημένες καταστάσεις και την κατάσταση sent των μηνυμάτων ομάδας. Ακολουθεί το παράδειγμα της Meta για ένα template μάρκετινγκ που έφυγε από τους διακομιστές της:

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"
        }
      ]
    }
  ]
}

Τι σημαίνει κάθε τιμή κατάστασης;

Κάθε τιμή αντιστοιχεί σε μια ένδειξη που θα έβλεπε ο πελάτης στο WhatsApp. Μια κατάσταση θεωρείται `read` μόνο αφού έχει προηγηθεί `delivered`. Όταν όμως ο πελάτης λαμβάνει μήνυμα ενώ η συνομιλία είναι ήδη ανοιχτή, η Meta στέλνει το `read` χωρίς προηγούμενο webhook `delivered`, ως εσωτερική βελτιστοποίηση. Γι' αυτό ένα εργαλείο παρακολούθησης πρέπει να δέχεται το `read` ακόμη κι όταν το `delivered` δεν έφτασε ποτέ, και να κατατάσσει τις καταστάσεις αντί να τις περιμένει μία μία σε σταθερή σειρά.

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.

Ποια πεδία έχει ένα αντικείμενο κατάστασης;

Λιγότερα από ένα μήνυμα, και αρκετά είναι υπό προϋποθέσεις. Η αναφορά της Meta λέει πότε υπάρχει το καθένα:

  • `id`: το wamid του μηνύματος που στείλατε, το κλειδί για την αντιστοίχιση.
  • `status` και `timestamp`: η τιμή και η ώρα Unix που ενεργοποιήθηκε το webhook, ως string.
  • `recipient_id`: ο αριθμός τηλεφώνου ή το group id, παραλείπεται όταν στείλατε σε BSUID και ο αριθμός δεν είναι διαθέσιμος.
  • `recipient_user_id`: το BSUID του πελάτη, παραλείπεται σε αποτυχημένη κατάσταση όταν στείλατε σε αριθμό τηλεφώνου.
  • `recipient_type` και `recipient_participant_id`: μόνο για μηνύματα που στάλθηκαν σε ομάδα.
  • `biz_opaque_callback_data`: μόνο όταν το ορίσατε στο αίτημα αποστολής.
  • `pricing`: μόνο στην κατάσταση `sent` και σε μία από τις `delivered` ή `read`. `errors`: μόνο στην κατάσταση `failed`.

Πώς αντιστοιχίζετε μια κατάσταση με το μήνυμα που στείλατε;

Με το wamid. Το αίτημα αποστολής επιστρέφει το `messages[0].id`, και κάθε κατάσταση για εκείνο το μήνυμα φέρει την ίδια τιμή στο `statuses[].id`. Αποθηκεύστε το δίπλα στη δική σας εγγραφή όταν στέλνετε, και ενημερώστε την όταν φτάνουν καταστάσεις, κρατώντας την υψηλότερη κατάσταση που έχει επιτευχθεί, ώστε ένα καθυστερημένο `delivered` να μην αντικαταστήσει το `read`. Μια κατάσταση με wamid που δεν γνωρίζετε στάλθηκε από κάτι άλλο στον αριθμό, όπως ένας αυτοματισμός, και μπορείτε να την αγνοήσετε ή να την καταγράψετε.

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

Τι αλλάζει σε αριθμό Coexistence;

Οι καταστάσεις περιγράφουν όσα στάλθηκαν μέσω του API: απαντήσεις από τους αυτοματισμούς σας, μηνύματα που έστειλε η AI σας μέσω ενός συνδέσμου MCP, και ό,τι έστειλε ο δικός σας κώδικας. Ό,τι πληκτρολογεί ο ιδιοκτήτης στην εφαρμογή WhatsApp Business φτάνει στο λογισμικό διαφορετικά, ως `smb_message_echoes`, το οποίο η Meta τεκμηριώνει ως καθρέφτη των μηνυμάτων που στέλνονται από την εφαρμογή. Τα μηνύματα που μεταφέρθηκαν με την εφάπαξ εισαγωγή ιστορικού έχουν τη δική τους κατάσταση μέσα στο webhook ιστορικού, με τιμές όπως `delivered`, `read`, `played`, `pending` και `error`.

Οι καταστάσεις πηγαίνουν όπου πηγαίνει το πεδίο messages του αριθμού. Με άμεσο προορισμό, η Meta τις στέλνει κατευθείαν στο endpoint σας, επειδή το messages είναι πεδίο που ο προορισμός μπορεί να αντικαταστήσει. Με ενεργούς αυτοματισμούς και ορισμένο Forward URL, φτάνουν σε αυτό το URL ως συμβάντα messages.

Πώς μαθαίνει ο AI ή ο αυτοματισμός σας αν ένα μήνυμα παραδόθηκε;

Μέσω του προορισμού σας, όχι μέσω της αποστολής. Όταν ένας βοηθός καλεί `send_template` ή `send_message`, το αποτέλεσμα του εργαλείου φέρει το wamid και δηλώνει ότι η Meta δέχτηκε το μήνυμα. Η παράδοση επιβεβαιώνεται αργότερα, στη συσκευή του πελάτη, και αναφέρεται ως κατάσταση. Το easyCoexistence δεν κρατά ιστορικό καταστάσεων προς αναζήτηση, και κανένα εργαλείο MCP δεν διαβάζει καταστάσεις. Ένας πράκτορας που χρειάζεται επιβεβαίωση παράδοσης πρέπει λοιπόν να στέλνει μέσω του δικού σας συστήματος, ή να διαβάζει τις καταστάσεις που λαμβάνει το Forward URL σας.

Το ίδιο ισχύει για τους αυτοματισμούς: μια εκτέλεση στην καρτέλα Runs δείχνει το βήμα της απάντησης ως ολοκληρωμένο μόλις η Meta δεχτεί το μήνυμα, και μια αποτυχία που αναφέρεται αργότερα εμφανίζεται μόνο ως κατάσταση `failed` στον προορισμό σας.

Συνηθισμένα λάθη

  • Αναζήτηση ξεχωριστού πεδίου statuses. Οι καταστάσεις έρχονται στο messages, οπότε ένας χειριστής που διαβάζει μόνο το value.messages τις χάνει χωρίς κανένα σφάλμα.
  • Απαίτηση να προηγηθεί το `delivered` πριν από το `read`. Η Meta παραλείπει το webhook `delivered` όταν το μήνυμα διαβάζεται τη στιγμή που φτάνει.
  • Αντιμετώπιση της απόκρισης αποστολής ως παράδοσης. Ένα wamid σημαίνει ότι η Meta δέχτηκε το αίτημα· μια αποτυχία μπορεί να έρθει λεπτά αργότερα ως κατάσταση `failed`.
  • Χρήση μόνο του `recipient_id` ως κλειδιού για πελάτες. Παραλείπεται όταν στείλατε σε BSUID και ο αριθμός τηλεφώνου δεν είναι διαθέσιμος· το `recipient_user_id` φέρει το BSUID.
Κάντε το με EasyCoexistence

Οι καταστάσεις για όσα στέλνουν οι αυτοματισμοί σας, η AI σας ή ο κώδικάς σας πηγαίνουν στον διακομιστή σας: κατευθείαν από τη Meta σε άμεση λειτουργία, ή προωθούνται στο Forward URL σας και υπογράφονται με X-EC-Signature όταν οι αυτοματισμοί είναι ενεργοί, και δεν αποθηκεύονται από προεπιλογή. Από US$ 9 ανά συνδεδεμένο αριθμό τον μήνα, με πτώση έως US$ 0,75 καθώς προσθέτετε αριθμούς, και οι πρώτες 3 ημέρες είναι δωρεάν.

Συχνές ερωτήσεις

Τα webhooks κατάστασης περιλαμβάνουν το κείμενο του μηνύματος;

Όχι. Μια κατάσταση φέρει το wamid, την κατάσταση, τον παραλήπτη, τις ώρες και, όπου ισχύουν, την τιμολόγηση και τα σφάλματα. Κρατήστε το δικό σας αντίγραφο όσων στείλατε, με κλειδί το wamid, αν θέλετε να το εμφανίζετε δίπλα στην κατάστασή του.

Μπορώ να ανακτήσω αργότερα παλαιότερες καταστάσεις από τη Meta;

Όχι. Ο οδηγός webhooks της Meta αναφέρει ότι δεν υπάρχουν API για την ανάκτηση ιστορικών δεδομένων του webhook, οπότε μια κατάσταση που δεν κατέγραψε το endpoint σας χάνεται μόλις η Meta σταματήσει τις επαναλήψεις, μετά από έως 7 ημέρες.

Σε τι χρησιμεύει το biz_opaque_callback_data;

Είναι μια συμβολοσειρά που ορίζετε κατά την αποστολή, για παράδειγμα τον δικό σας αριθμό παραγγελίας ή εισιτηρίου υποστήριξης. Η Meta την επιστρέφει στις καταστάσεις εκείνου του μηνύματος, ώστε να αντιστοιχίζετε μια κατάσταση με την εγγραφή σας χωρίς να αναζητήσετε πρώτα το wamid.

Πρέπει να απαντάτε στα webhooks κατάστασης με 200;

Ναι, όπως κάθε POST webhook. Η Meta θεωρεί κάθε άλλη απόκριση αποτυχημένη παράδοση και την επαναλαμβάνει, και αυτός είναι ένας από τους τρόπους με τους οποίους η ίδια κατάσταση φτάνει δύο φορές.

Συνεχίστε την ανάγνωση

Γιατί ένα μήνυμα WhatsApp απέτυχε: ανάγνωση της κατάστασης failed και των σφαλμάτωνΗ κατάσταση failed σημαίνει ότι η Meta δεν μπόρεσε να στείλει ή να παραδώσει το μήνυμα. Δείτε τους κωδικούς 131047, 131049, 131050 και τι να κάνετε.Αντικείμενο τιμολόγησης webhook WhatsApp: type, category και billable (2026)Τι σημαίνουν τα πεδία του αντικειμένου τιμολόγησης στα webhooks κατάστασης WhatsApp από τον Οκτώβριο 2026 και πώς μετράτε τις χρεώσεις.Επαναλήψεις, διπλότυπα και σειρά των webhooks του WhatsApp: πώς να τα χειριστείτεΗ Meta επαναλαμβάνει τα webhooks του WhatsApp έως 7 ημέρες, άρα τα διπλότυπα είναι φυσιολογικά. Κλειδιά αποκλεισμού και ασφαλής χειριστής.Τα webhooks κλήσεων του WhatsApp: γεγονότα του Calling API και κλήσεις σε αριθμό CoexistenceΤο πεδίο calls αναφέρει τα γεγονότα του WhatsApp Calling API: σύνδεση, τερματισμό, καταστάσεις κλήσεων, εγγραφές. Τι ισχύει σε αριθμούς Coexistence.Πώς φτάνουν τα μηνύματα WhatsApp στον διακομιστή σας: άμεσα ή διαχειριζόμενα, και επαλήθευση της υπογραφήςΆμεσα: η Meta στέλνει στον διακομιστή σας. Διαχειριζόμενα: αυτοματισμοί και υπογεγραμμένη προώθηση στο Forward URL. Payload, X-EC-Signature και επαναδοκιμές.Ονόματα χρήστη του WhatsApp και BSUID: τι αλλάζει στα webhooks του Cloud APIΠώς τα ονόματα χρήστη αλλάζουν τα webhooks του Cloud API: το BSUID στο user_id, πότε λείπει ο αριθμός, η απάντηση με recipient και το Coexistence.

Έτοιμοι να ξεκινήσετε;

Ρυθμίστε το WhatsApp Coexistence σε λίγα λεπτά, όχι σε μήνες. Η εφαρμογή συνεχίζει να λειτουργεί στο τηλέφωνο.

Ξεκινήστε δωρεάν δοκιμή

Επαληθεύτηκε στις