WhatsApp durum webhook'ları: sent, delivered, read ve failed
Durum webhook'ları, WhatsApp Cloud API üzerinden işletmenizin gönderdiği bir mesajın ne olduğunu bildirir. messages alanına, messages dizisi yerine statuses dizisiyle gelirler: sent (tek onay), delivered (çift onay), read (çift mavi onay), sesli mesajlar için played ve errors dizisi içeren failed. statuses[].id değerini, gönderme isteğinizin döndürdüğü wamid ile eşleştirin.
easyCoexistence, zaten kullandığınız WhatsApp Business uygulama numarasını Coexistence üzerinden Meta'nın Cloud API'sine bağlar.
Meta'nın gönderdiği durum değerleri: sent, delivered, read, played (sesli mesajların ilk oynatılması) ve failed.
Tek bir giden mesajın üretebileceği ayrı durum webhook'ları: sent, delivered ve read.
Bu Graph API sürümünden itibaren, ücretsiz giriş penceresindeki mesajlar hariç, conversation nesnesi dahil edilmez.
Geçmiş webhook verilerini getiren API yoktur; Meta, payload'ları geldikleri anda yakalayıp saklamanızı ister.
İletilen bir durumdaki X-EC-Event başlığı: durumlar messages olayları içinde, value.statuses altında taşınır.
WhatsApp durum webhook'ları nereye gelir?
Müşterilerin gönderdiği mesajları taşıyan aynı messages alanına, aynı nesne, entry ve changes zarfının içinde gelirler. Fark value'nun içindedir: gelen bir mesajın messages dizisi vardır, bir durumun ise statuses dizisi. Yalnızca value.messages okuyan bir işleyici, her durumu hata vermeden düşürür. metadata.phone_number_id, mesajı hangi numaranızın gönderdiğini söyler. Müşterinin profil adı, wa_id ve BSUID'sini içeren bir contacts dizisi de gelir; ancak başarısız durumlarda ve grup mesajlarının sent durumunda bu dizi gelmez. Aşağıda, Meta sunucularından çıkmış bir pazarlama şablonuna dair Meta'nın örneği yer alıyor:
{
"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"
}
]
}
]
}Her durum değeri ne anlama gelir?
Her değer, müşterinin WhatsApp'ta göreceği bir işarete karşılık gelir. Bir durum ancak iletildikten sonra read sayılır. Müşteri sohbet zaten açıkken bir mesaj aldığında, Meta dahili bir optimizasyon olarak önce delivered webhook'unu göndermeden read gönderir. Bu nedenle bir takipçi, delivered hiç gelmemiş olsa bile read'i kabul etmeli ve durumları sabit bir sırayla tek tek beklemek yerine sıralamalıdır.
Bir durum nesnesi hangi alanları taşır?
Bir mesajdan daha az alan taşır ve birkaçı koşulludur. Meta'nın referansı, her birinin ne zaman bulunduğunu listeler:
- id: göndermiş olduğunuz mesajın wamid'i; eşleştirme anahtarı.
- status ve timestamp: değer ile webhook'un tetiklendiği Unix zamanı, string olarak.
recipient_id: telefon numarası veya grup kimliği; BSUID ile gönderdiğinizde ve numara yoksa atlanır.recipient_user_id: müşterinin BSUID'i; telefon numarasına gönderdiğinizde başarısız bir durumda atlanır.recipient_typeverecipient_participant_id: yalnızca gruba gönderilen mesajlar için.biz_opaque_callback_data: yalnızca gönderme isteğinde siz ayarladıysanız.- pricing: yalnızca sent durumunda ve delivered veya read durumlarından birinde. errors: yalnızca failed durumunda.
Bir durumu gönderdiğiniz mesajla nasıl eşleştirirsiniz?
wamid ile. Gönderme isteği messages[0].id değerini döndürür ve o mesaja ait her durum, statuses[].id içinde aynı değeri taşır. Göndermede bunu kendi kaydınızın yanında saklayın, durumlar geldiğinde kaydı güncelleyin ve ulaşılan en yüksek durumu koruyun; böylece geç gelen bir delivered, read'in üzerine yazmaz. Bilmediğiniz bir wamid'e ait durum, numaradaki başka bir şey tarafından, örneğin bir otomasyon tarafından gönderilmiştir; yok sayılabilir veya kaydedilebilir.
// 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 numarasında ne değişir?
Durumlar, API üzerinden gönderilenleri anlatır: otomasyonlarınızdan gelen yanıtlar, yapay zekanızın bir MCP bağlayıcısıyla gönderdiği mesajlar ve kendi kodunuzun gönderdiği her şey. İşletme sahibinin WhatsApp Business uygulamasında yazdıkları yazılıma farklı ulaşır: Meta'nın, uygulamadan gönderilen mesajların aynası olarak belgelediği smb_message_echoes olarak. Tek seferlik geçmiş içe aktarımıyla gelen mesajlar, kendi durumlarını geçmiş webhook'unun içinde taşır; değerleri delivered, read, played, pending ve error'dur.
Durumlar, numaranın messages alanının gittiği her yere gider. Doğrudan bir hedefle Meta, messages, Meta'nın hedefin geçersiz kılmasına izin verdiği bir alan olduğu için durumları doğrudan uç noktanıza gönderir. Otomasyonlar açık ve bir Forward URL ayarlıysa, durumlar messages olayları olarak o URL'ye ulaşır.
Yapay zekanız veya otomasyonunuz bir mesajın iletildiğini nasıl öğrenir?
Gönderim üzerinden değil, hedefiniz üzerinden. Bir asistan send_template veya send_message çağırdığında, araç sonucu wamid'i taşır ve Meta'nın mesajı kabul ettiğini söyler; iletim daha sonra müşterinin cihazında doğrulanır ve bir durum olarak bildirilir. easyCoexistence sorgulanabilecek bir durum geçmişi tutmaz ve hiçbir MCP aracı durumları okumaz; dolayısıyla iletim onayına ihtiyaç duyan bir ajan, ya gönderimi kendi sisteminiz üzerinden yapmalı ya da Forward URL'nizin aldığı durumları okumalıdır.
Otomasyonlar için de aynısı geçerlidir: Runs sekmesindeki bir çalıştırma, Meta mesajı kabul ettiğinde yanıt adımını tamamlanmış gösterir; sonradan bildirilen bir hata yalnızca hedefinizde failed durumu olarak görünür.
Yaygın hatalar
- Ayrı bir statuses alanı aramak. Durumlar messages üzerinde gelir; yalnızca value.messages okuyan bir işleyici, hata vermeden bunları kaybeder.
- delivered'ı read'den önce şart koşmak. Mesaj geldiği anda okunduğunda Meta delivered webhook'unu atlar.
- Gönderme yanıtını iletim saymak. Bir wamid, Meta'nın isteği kabul ettiği anlamına gelir; hata dakikalar sonra failed durumu olarak gelebilir.
- Müşterileri yalnızca recipient_id ile anahtarlamak. Bu alan BSUID ile gönderdiğinizde ve telefon numarası yokken atlanır; BSUID'i recipient_user_id taşır.
Otomasyonlarınızın, yapay zekanızın veya kodunuzun gönderdiklerine ait durumlar sunucunuza gider: doğrudan modda Meta'dan doğrudan, otomasyonlar açıksa ve bir Forward URL ayarlıysa X-EC-Signature ile imzalanmış olarak iletilir; varsayılan olarak saklanmazlar. Numara başına ayda US$ 9'dan US$ 0.75'e kadar, numara ekledikçe düşer; ilk 3 gün ücretsiz.
Sık sorulan sorular
Durum webhook'ları mesajın metnini içeriyor mu?
Hayır. Bir durum; wamid'i, durumu, alıcıyı, zaman damgalarını ve uygulanabilir olduğunda fiyatlandırma ve hataları taşır. Durumunun yanında göstermek istiyorsanız, gönderdiğiniz metnin kendi kopyanızı wamid ile anahtarlayarak tutun.
Geçmiş durumları daha sonra Meta'dan çekebilir miyim?
Hayır. Meta'nın webhook rehberi, geçmiş webhook verilerini getiren API bulunmadığını söyler. Meta, en fazla 7 güne kadar süren yeniden denemeleri durdurduğunda, uç noktanızın yakalamadığı bir durum kaybolmuş olur.
biz_opaque_callback_data ne için kullanılır?
Gönderirken ayarladığınız bir dizedir; örneğin kendi sipariş veya bilet kimliğiniz. Meta, bu değeri o mesajın statuses içinde geri döndürür; böylece durumu, önce wamid aramadan kaydınızla eşleştirebilirsiniz.
Durum webhook'larına 200 ile yanıt vermem gerekir mi?
Evet, her webhook POST'u gibi. Meta, başka herhangi bir yanıtı başarısız iletim sayar ve yeniden dener; aynı durumun size iki kez ulaşmasının yollarından biri de budur.
Okumaya devam edin
Başlamaya hazır mısınız?
WhatsApp Coexistence'ı aylar değil, dakikalar içinde kurun. Uygulama telefonda çalışmaya devam eder.
Ücretsiz denemeyi başlatınDoğrulama tarihi