AccediInizia la prova gratuita
Meta Tech Provider

Stati webhook WhatsApp: inviato, consegnato, letto e fallito

I webhook di stato riportano cosa è successo a un messaggio inviato da un'azienda tramite la Cloud API di WhatsApp. Arrivano sul campo messages con un array statuses invece di un array messages: inviato (un segno di spunta), consegnato (due segni di spunta), letto (due segni di spunta blu), riprodotto per i messaggi vocali e fallito con un array errors. Abbina statuses[].id al wamid restituito dalla tua richiesta di invio.

easyCoexistence collega il numero dell'app WhatsApp Business che già usi alla Cloud API di Meta tramite Coexistence.

5

Valori di stato inviati da Meta: sent, delivered, read, played (prima riproduzione dei messaggi vocali) e failed.

3

Webhook di stato separati che un singolo messaggio in uscita può generare: sent, delivered e read.

v24.0

A partire da questa versione della Graph API, l'oggetto conversation viene omesso, tranne che per i messaggi in una finestra gratuita del punto di ingresso.

0

Non esistono le API per recuperare i dati storici dei webhook; Meta chiede di acquisire e archiviare i payload non appena arrivano.

messages

L'intestazione X-EC-Event su uno stato inoltrato: gli stati viaggiano dentro gli eventi messages, sotto value.statuses.

Dove arrivano i webhook di stato di WhatsApp?

Sullo stesso campo messages che trasporta ciò che i clienti inviano, nello stesso oggetto, con la stessa struttura entry e changes. La differenza sta dentro value: un messaggio in arrivo ha un array messages, uno stato ha un array statuses. Un handler che legge solo value.messages scarta ogni stato senza alcun errore. metadata.phone_number_id indica quale dei tuoi numeri ha inviato il messaggio, e arriva anche un array contacts con il nome del profilo del cliente, wa_id e BSUID, tranne che sugli stati falliti e sullo stato sent dei messaggi di gruppo. Questo è l'esempio di Meta di un template di marketing che ha lasciato i server di Meta:

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

Cosa significa ogni valore di stato?

Ogni valore corrisponde a un segno che il cliente vedrebbe in WhatsApp. Uno stato conta come letto solo dopo essere stato consegnato; quando un cliente riceve un messaggio mentre la chat è già aperta, Meta invia read senza prima un webhook delivered, come ottimizzazione interna. Quindi un sistema di tracciamento deve accettare read anche quando delivered non è arrivato, e deve ordinare gli stati invece di aspettarseli uno alla volta in una sequenza fissa.

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.

Quali campi contiene un oggetto stato?

Meno di un messaggio, e diversi sono condizionali. Il riferimento di Meta indica quando ciascuno è presente:

  • id: il wamid del messaggio inviato, la chiave per l'abbinamento.
  • status e timestamp: il valore e l'ora Unix in cui il webhook è stato attivato, come stringa.
  • recipient_id: il numero di telefono o l'id del gruppo, omesso quando hai inviato a un BSUID e il numero non è disponibile.
  • recipient_user_id: il BSUID del cliente, omesso su uno stato fallito quando hai inviato a un numero di telefono.
  • recipient_type e recipient_participant_id: solo per i messaggi inviati a un gruppo.
  • biz_opaque_callback_data: solo se lo hai impostato nella richiesta di invio.
  • pricing: solo su sent e su uno tra delivered o read. errors: solo sugli stati falliti.

Come si abbina uno stato al messaggio inviato?

Tramite il wamid. La richiesta di invio risponde con messages[0].id, e ogni stato di quel messaggio riporta lo stesso valore in statuses[].id. Salvalo accanto al tuo record quando invii, poi aggiorna il record quando arrivano gli stati, tenendo lo stato più alto raggiunto, così un delivered in ritardo non sovrascrive read. Uno stato il cui wamid non conosci è stato inviato da qualcos'altro sul numero, come un'automazione, e può essere ignorato o registrato.

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

Cosa cambia su un numero in Coexistence?

Gli stati descrivono ciò che è stato inviato tramite l'API: risposte delle tue automazioni, messaggi inviati dalla tua AI tramite un connettore MCP e tutto ciò che invia il tuo codice. Ciò che il titolare scrive nell'app WhatsApp Business arriva al software in modo diverso, come smb_message_echoes, che Meta documenta come lo specchio dei messaggi inviati dall'app. I messaggi importati nell'importazione una tantum della cronologia portano il proprio stato all'interno del webhook della cronologia, con valori come delivered, read, played, pending e error.

Gli stati seguono la destinazione del campo messages del numero. Con una destinazione diretta, Meta li invia direttamente al tuo endpoint, perché messages è un campo che Meta permette di sovrascrivere per una destinazione. Con le automazioni attive e un Forward URL impostato, arrivano a quell'URL come eventi messages.

Come fa la tua AI o l'automazione a sapere se un messaggio è stato consegnato?

Tramite la tua destinazione, non tramite l'invio. Quando un assistente chiama send_template o send_message, il risultato dello strumento riporta il wamid e indica che Meta ha accettato il messaggio; la consegna viene confermata in seguito, sul dispositivo del cliente, e segnalata come stato. easyCoexistence non conserva una cronologia degli stati da interrogare, e nessuno strumento MCP legge gli stati, quindi un agente che ha bisogno della conferma di consegna deve inviare tramite il tuo sistema oppure leggere gli stati che riceve il tuo Forward URL.

Lo stesso vale per le automazioni: un'esecuzione nella scheda Runs mostra il passaggio di risposta completato non appena Meta ha accettato il messaggio, e un fallimento segnalato in seguito compare solo come stato fallito sulla tua destinazione.

Errori comuni

  • Cercare un campo statuses separato. Gli stati arrivano su messages, quindi un handler che legge solo value.messages li perde senza alcun errore.
  • Pretendere delivered prima di read. Meta salta il webhook delivered quando il messaggio viene letto nel momento stesso in cui arriva.
  • Trattare la risposta all'invio come consegna. Un wamid significa che Meta ha accettato la richiesta; un fallimento può arrivare minuti dopo come stato fallito.
  • Identificare i clienti solo tramite recipient_id. Viene omesso quando hai inviato a un BSUID e il numero di telefono non è disponibile; recipient_user_id contiene il BSUID.
Farlo con EasyCoexistence

Gli stati di ciò che inviano le tue automazioni, la tua AI o il tuo codice arrivano al tuo server: direttamente da Meta in modalità diretta, oppure inoltrati al tuo Forward URL e firmati con X-EC-Signature quando le automazioni sono attive, e non vengono conservati per impostazione predefinita. Da US$ 9 fino a US$ 0,75 per numero al mese, in calo man mano che aggiungi numeri, con i primi 3 giorni di prova gratuita.

Domande frequenti

I webhook di stato includono il testo del messaggio?

No. Uno stato contiene il wamid, lo stato, il destinatario, i timestamp e, dove applicabile, i prezzi e gli errori. Conserva una copia di ciò che hai inviato, con chiave il wamid, se ti serve mostrarla accanto al suo stato.

Posso recuperare in seguito gli stati passati da Meta?

No. La guida ai webhook di Meta dice che non esistono API per recuperare i dati storici dei webhook, quindi uno stato che il tuo endpoint non ha acquisito è perso una volta che Meta smette di riprovare, dopo un massimo di 7 giorni.

A cosa serve biz_opaque_callback_data?

È una stringa che imposti in fase di invio, come il tuo id dell'ordine o del ticket. Meta la restituisce negli stati di quel messaggio, così puoi abbinare uno stato al tuo record senza prima cercare il wamid.

Devo rispondere ai webhook di stato con 200?

Sì, come per qualsiasi POST di webhook. Meta considera qualsiasi altra risposta come una consegna non riuscita e la ritenta, ed è uno dei modi in cui lo stesso stato ti arriva due volte.

Continua a leggere

Pronto per iniziare?

Configura WhatsApp Coexistence in pochi minuti, non in mesi. L'app continua a funzionare sul telefono.

Inizia la prova gratuita

Verificato il