Statusy webhooków WhatsApp: sent, delivered, read i failed
Webhooki statusów opisują, co się stało z wiadomością wysłaną przez firmę przez WhatsApp Cloud API. Przychodzą w polu messages, ale zamiast tablicy messages zawierają tablicę statuses: sent (jeden znacznik), delivered (dwa znaczniki), read (dwa niebieskie znaczniki), played dla wiadomości głosowych oraz failed z tablicą errors. Dopasuj statuses[].id do identyfikatora wamid, który zwróciło Twoje żądanie wysłania.
easyCoexistence łączy numer z aplikacją WhatsApp Business, którego już używasz, z Cloud API Meta przez Coexistence.
Wartości statusów wysyłane przez Meta: sent, delivered, read, played (pierwsze odtworzenie wiadomości głosowych) i failed.
Osobne webhooki statusów, jakie może wygenerować jedna wychodząca wiadomość: sent, delivered i read.
Od tej wersji Graph API obiekt conversation jest pomijany, z wyjątkiem wiadomości w bezpłatnym oknie punktu wejścia.
Nie ma API do pobierania przeszłych danych webhooków; Meta prosi o zapisywanie payloadów w chwili ich nadejścia.
Nagłówek X-EC-Event przy przekazanym statusie: statusy przychodzą w zdarzeniach messages, pod value.statuses.
Dokąd trafiają webhooki statusów WhatsApp?
Na to samo pole messages, które przenosi wiadomości od klientów, w tym samym obiekcie, w tej samej strukturze entry i changes. Różnica jest wewnątrz value: wiadomość przychodząca ma tablicę messages, a status ma tablicę statuses. Handler, który czyta tylko value.messages, bez błędu odrzuca każdy status. metadata.phone_number_id wskazuje, którym z Twoich numerów wysłano wiadomość, a przychodzi też tablica contacts z nazwą profilu klienta, wa_id i BSUID, z wyjątkiem statusów failed oraz statusu sent wiadomości grupowych. Oto przykład Meta dla szablonu marketingowego, który opuścił serwery Meta:
{
"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"
}
]
}
]
}Co oznacza każda wartość statusu?
Każda wartość odpowiada znacznikowi, jaki klient widzi w WhatsApp. Status read liczy się dopiero po doręczeniu wiadomości, a gdy klient otrzyma wiadomość, mając już otwarty czat, Meta wysyła read bez wcześniejszego webhooka delivered, jako wewnętrzną optymalizację. Dlatego tracker powinien przyjmować read nawet wtedy, gdy delivered nie nadeszło, i powinien porządkować statusy według rangi, a nie oczekiwać ich w stałej kolejności.
Jakie pola ma obiekt statusu?
Mniej niż wiadomość, a kilka z nich jest warunkowych. Referencja Meta wymienia, kiedy każde pole jest obecne:
- id: wamid wysłanej przez Ciebie wiadomości, klucz do dopasowania.
- status i timestamp: wartość i czas Unix, w którym wywołano webhook, jako ciąg znaków.
recipient_id: numer telefonu lub identyfikator grupy, pomijany, gdy wysłano do BSUID, a numer jest niedostępny.recipient_user_id: BSUID klienta, pomijany przy statusie failed, gdy wysłano na numer telefonu.recipient_typeirecipient_participant_id: tylko przy wiadomościach wysłanych do grupy.biz_opaque_callback_data: tylko wtedy, gdy ustawiono je w żądaniu wysłania.- pricing: tylko przy sent i przy jednym z delivered lub read. errors: tylko przy failed.
Jak dopasować status do wysłanej wiadomości?
Po identyfikatorze wamid. Żądanie wysłania zwraca messages[0].id, a każdy status tej wiadomości niesie tę samą wartość w statuses[].id. Zapisz ją obok własnego rekordu w chwili wysyłki, a potem aktualizuj rekord, gdy przychodzą statusy, zachowując najwyższy osiągnięty status, tak aby spóźnione delivered nie nadpisało read. Status z nieznanym wamid został wysłany przez coś innego na tym numerze, na przykład przez automatyzację, i można go zignorować lub zapisać w logu.
// 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));
}
}Co zmienia się na numerze Coexistence?
Statusy opisują to, co wysłano przez API: odpowiedzi z automatyzacji, wiadomości wysłane przez AI przez konektor MCP i wszystko, co wysłał Twój własny kod. To, co właściciel wpisze w aplikacji WhatsApp Business, dociera do oprogramowania inaczej, jako smb_message_echoes, które Meta opisuje jako lustrzane odbicie wiadomości wysłanych z aplikacji. Wiadomości przeniesione w jednorazowym imporcie historii niosą własny status w webhooku historii, z wartościami takimi jak delivered, read, played, pending i error.
Statusy trafiają tam, gdzie trafia pole messages numeru. Przy bezpośrednim miejscu docelowym Meta wysyła je prosto na Twój endpoint, ponieważ messages to pole, które Meta pozwala nadpisać w miejscu docelowym. Przy włączonych automatyzacjach i ustawionym Forward URL docierają pod ten adres jako zdarzenia messages.
Skąd AI lub automatyzacja wie, że wiadomość została doręczona?
Z Twojego miejsca docelowego, nie z wysyłki. Gdy asystent wywołuje send_template lub send_message, wynik narzędzia zawiera wamid i informuje, że Meta przyjęła wiadomość; doręczenie potwierdza się później, na urządzeniu klienta, i jest zgłaszane jako status. easyCoexistence nie przechowuje historii statusów do odpytywania i żadne narzędzie MCP nie czyta statusów, więc agent, który potrzebuje potwierdzenia doręczenia, powinien wysyłać przez Twój system albo czytać statusy, które odbiera Twój Forward URL.
To samo dotyczy automatyzacji: przebieg w zakładce Runs pokazuje krok odpowiedzi jako wykonany, gdy Meta przyjęła wiadomość, a błąd zgłoszony później pojawia się tylko jako status failed w Twoim miejscu docelowym.
Typowe błędy
- Szukanie osobnego pola statuses. Statusy przychodzą w messages, więc handler czytający tylko value.messages gubi je bez żadnego błędu.
- Wymaganie delivered przed read. Meta pomija webhook delivered, gdy wiadomość zostaje przeczytana w chwili nadejścia.
- Traktowanie odpowiedzi na wysyłkę jako doręczenia. Wamid oznacza, że Meta przyjęła żądanie; błąd może pojawić się minuty później jako status failed.
- Identyfikowanie klientów wyłącznie po recipient_id. Pole jest pomijane, gdy wysłano do BSUID, a numer telefonu jest niedostępny; BSUID niesie recipient_user_id.
Statusy tego, co wysyłają Twoje automatyzacje, AI lub kod, trafiają na Twój serwer: wprost z Meta w trybie bezpośrednim albo przekazane na Twój Forward URL i podpisane nagłówkiem X-EC-Signature, gdy automatyzacje są włączone; domyślnie nie są przechowywane. Od US$ 9 do US$ 0,75 za numer miesięcznie, spadając wraz z dodawaniem numerów, z pierwszymi 3 dniami bezpłatnymi.
Najczęściej zadawane pytania
Czy webhooki statusów zawierają treść wiadomości?
Nie. Status zawiera wamid, wartość statusu, odbiorcę, znaczniki czasu oraz, tam gdzie mają zastosowanie, cenę i błędy. Jeśli potrzebujesz pokazać treść obok statusu, zachowaj własną kopię tego, co wysłano, z kluczem wamid.
Czy później mogę pobrać statusy z Meta?
Nie. Przewodnik po webhookach Meta mówi, że nie ma API do pobierania historycznych danych webhooków, więc status, którego endpoint nie zapisał, przepada, gdy Meta przestaje ponawiać próby, czyli po maksymalnie 7 dniach.
Do czego służy biz_opaque_callback_data?
To ciąg, który ustawiasz przy wysyłaniu, na przykład własny identyfikator zamówienia lub zgłoszenia. Meta zwraca go w statuses tej wiadomości, więc możesz dopasować status do swojego rekordu bez wcześniejszego szukania wamid.
Czy na webhooki statusów muszę odpowiadać kodem 200?
Tak, jak na każdy POST webhooka. Meta traktuje każdą inną odpowiedź jako nieudane doręczenie i ponawia je, co jest jednym ze sposobów, w jakie ten sam status dociera dwukrotnie.
Czytaj dalej
Gotowy, aby zacząć?
Skonfiguruj WhatsApp Coexistence w kilka minut, nie miesięcy. Aplikacja nadal działa na telefonie.
Rozpocznij bezpłatny okres próbnyZweryfikowano w