Conectați-văÎncepeți perioada de probă gratuită
Meta Tech Provider

Statusurile webhook WhatsApp: trimis, livrat, citit și eșuat

Webhook-urile de status raportează ce s-a întâmplat cu un mesaj pe care o firmă l-a trimis prin WhatsApp Cloud API. Ele sosesc pe câmpul messages, cu un array statuses în loc de un array messages: sent (o bifă), delivered (două bife), read (două bife albastre), played pentru mesajele vocale și failed, cu un array errors. Potriviți statuses[].id cu wamid-ul returnat de cererea dumneavoastră de trimitere.

easyCoexistence conectează numărul din aplicația WhatsApp Business pe care îl folosiți deja la Cloud API de la Meta, prin Coexistence.

5

Valorile de status trimise de Meta: sent, delivered, read, played (prima redare a mesajelor vocale) și failed.

3

Webhook-urile de status separate pe care le poate produce un singur mesaj trimis: sent, delivered și read.

v24.0

De la această versiune a Graph API, obiectul conversation este omis, cu excepția mesajelor din fereastra gratuită a unui punct de intrare.

0

Nu există API-uri pentru preluarea datelor webhook din trecut; Meta vă cere să capturați și să stocați payload-urile pe măsură ce sosesc.

messages

Antetul X-EC-Event pe un status redirecționat: statusurile circulă în interiorul evenimentelor messages, sub value.statuses.

Unde sosesc webhook-urile de status WhatsApp?

Pe același câmp messages care transportă mesajele primite de la clienți, în același obiect, în aceeași structură entry și changes. Diferența este în interiorul lui value: un mesaj primit are un array messages, iar un status are un array statuses. Un handler care citește doar value.messages pierde fiecare status fără nicio eroare. metadata.phone_number_id indică numărul dumneavoastră care a trimis mesajul, iar un array contacts cu numele de profil al clientului, wa_id și BSUID vine împreună cu el, cu excepția statusurilor failed și a statusului sent al mesajelor de grup. Iată exemplul Meta al unui șablon de marketing care a părăsit serverele 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"
        }
      ]
    }
  ]
}

Ce înseamnă fiecare valoare de status?

Fiecare valoare corespunde unei bife pe care clientul o vede în WhatsApp. Un status este considerat read doar după ce mesajul a fost livrat. Când un client primește un mesaj în timp ce conversația este deja deschisă, Meta trimite read fără un webhook delivered anterior, ca optimizare internă. Așadar, un sistem de urmărire trebuie să accepte read chiar dacă delivered nu a sosit niciodată și trebuie să ierarhizeze statusurile, în loc să le aștepte pe rând într-o secvență fixă.

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.

Ce câmpuri conține un obiect de status?

Mai puține decât un mesaj, iar câteva sunt condiționale. Referința Meta indică momentul în care apare fiecare dintre ele:

  • id: wamid-ul mesajului trimis, cheia după care se face potrivirea.
  • status și timestamp: valoarea și momentul Unix în care a fost declanșat webhook-ul, ca șir de caractere.
  • recipient_id: numărul de telefon sau id-ul grupului, omis când ați trimis către un BSUID și numărul nu este disponibil.
  • recipient_user_id: BSUID-ul clientului, omis la un status failed când ați trimis către un număr de telefon.
  • recipient_type și recipient_participant_id: doar pentru mesajele trimise unui grup.
  • biz_opaque_callback_data: doar dacă l-ați setat în cererea de trimitere.
  • pricing: doar la sent și la unul dintre delivered sau read. errors: doar la failed.

Cum asociați un status cu mesajul trimis?

Prin wamid. Cererea de trimitere răspunde cu messages[0].id, iar fiecare status al acelui mesaj poartă aceeași valoare în statuses[].id. Salvați-o lângă propria evidență la trimitere, apoi actualizați evidența atunci când sosesc statusurile, păstrând cel mai înalt status atins, astfel încât un delivered întârziat să nu îl suprascrie pe read. Un status al cărui wamid nu îl cunoașteți a fost trimis de altceva de pe număr, cum ar fi o automatizare, și poate fi ignorat sau înregistrat în jurnal.

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

Ce se schimbă pe un număr Coexistence?

Statusurile descriu ce s-a trimis prin API: răspunsurile din automatizările dumneavoastră, mesajele trimise de AI prin conectorul MCP și orice trimite propriul dumneavoastră cod. Ceea ce tastează proprietarul în aplicația WhatsApp Business ajunge la software altfel, sub forma smb_message_echoes, pe care Meta o documentează ca oglinda mesajelor trimise din aplicație. Mesajele importate o singură dată din istoric poartă propriul status în webhook-ul de istoric, cu valori precum delivered, read, played, pending și error.

Statusurile urmează câmpul messages al numărului, oriunde ar merge acesta. Cu o destinație directă, Meta le trimite direct către endpoint-ul dumneavoastră, deoarece messages este un câmp pe care Meta îl permite unei destinații să îl suprascrie. Cu automatizările active și un Forward URL setat, ele ajung la acel URL ca evenimente messages.

Cum află AI-ul sau automatizarea dumneavoastră dacă un mesaj a fost livrat?

Prin destinația dumneavoastră, nu prin trimitere. Când un asistent apelează send_template sau send_message, rezultatul instrumentului conține wamid-ul și spune că Meta a acceptat mesajul; livrarea se confirmă mai târziu, pe dispozitivul clientului, și este raportată ca status. easyCoexistence nu păstrează un istoric de statusuri de interogat, iar niciun instrument MCP nu citește statusurile, așadar un agent care are nevoie de confirmarea livrării trebuie să trimită prin sistemul dumneavoastră sau să citească statusurile primite de Forward URL.

La fel stau lucrurile și pentru automatizări: o rulare din fila Runs arată pasul de răspuns ca finalizat din momentul în care Meta a acceptat mesajul, iar un eșec raportat ulterior apare doar ca status failed la destinația dumneavoastră.

Greșeli frecvente

  • Căutarea unui câmp statuses separat. Statusurile vin pe messages, așa că un handler care citește doar value.messages le pierde fără nicio eroare.
  • Cerința ca delivered să vină înaintea lui read. Meta omite webhook-ul delivered când mesajul este citit chiar în momentul sosirii.
  • Tratarea răspunsului de trimitere drept livrare. Un wamid înseamnă că Meta a acceptat cererea; un eșec poate urma câteva minute mai târziu, ca status failed.
  • Recunoașterea clienților doar după recipient_id. Acesta este omis când ați trimis către un BSUID și numărul de telefon nu este disponibil; recipient_user_id conține BSUID-ul.
Faceți acest lucru cu EasyCoexistence

Statusurile pentru ce trimit automatizările, AI-ul sau codul dumneavoastră ajung la serverul dumneavoastră: direct de la Meta în modul direct sau redirecționate către Forward URL și semnate cu X-EC-Signature când automatizările sunt active, și nu sunt stocate implicit. De la US$ 9 la US$ 0,75 pe număr pe lună, scăzând pe măsură ce adăugați numere, cu primele 3 zile gratuite.

Întrebări frecvente

Webhook-urile de status includ textul mesajului?

Nu. Un status conține wamid-ul, statusul, destinatarul, marcajele de timp și, unde se aplică, tarifarea și erorile. Păstrați o copie proprie a ceea ce ați trimis, asociată cu wamid-ul, dacă doriți să o afișați lângă statusul său.

Pot prelua statusurile trecute de la Meta mai târziu?

Nu. Ghidul Meta pentru webhook-uri spune că nu există API-uri pentru preluarea datelor istorice de webhook, așa că un status pe care endpoint-ul dumneavoastră nu l-a capturat este pierdut după ce Meta încetează reîncercările, adică după cel mult 7 zile.

La ce servește biz_opaque_callback_data?

Este un șir de caractere pe care îl setați la trimitere, de exemplu id-ul propriu al comenzii sau al tichetului. Meta îl returnează în statuses al acelui mesaj, astfel încât puteți asocia un status cu evidența dumneavoastră fără a căuta mai întâi wamid-ul.

Trebuie să răspund cu 200 la webhook-urile de status?

Da, ca la orice POST de webhook. Meta tratează orice alt răspuns ca pe o livrare eșuată și o reîncearcă, ceea ce este unul dintre motivele pentru care același status ajunge la dumneavoastră de două ori.

Continuați să citiți

Gata să începeți?

Configurați WhatsApp Coexistence în câteva minute, nu luni. Aplicația continuă să funcționeze pe telefon.

Începeți perioada de probă gratuită

Verificat la