​

Teslim yaşam döngüsü

Orbit üzerinden gönderdiğiniz her giden mesaj, mesaj API çağrınızdan alıcının cihazına — veya bir başarısızlık sonucuna — doğru ilerlerken ilerleyen bir status alanı taşır. Bu sayfa kavramsal durum makinesini açıklar: durumların ne anlama geldiği, her geçişi neyin yürüttüğü ve operatöre bağlı kenarların nerede olduğu. İlk webhook’unuza abone olmadan veya entegrasyonunuzu bir mesaj sonucuna göre dallandırmadan önce okuyun. Durum semantiği, tam geçiş tablosu ve webhook olay haritası mesaj durumu yaşam döngüsü referansında yaşar; bir mesajın güncel durumunu okumak için yanıt şeması mesajlaşma API referansında bulunur. Bu sayfa ikisini daha üst düzeyde birbirine bağlar.

​

Mutlu yol

Uçtan uca başarılı olan bir mesaj şu yoldan geçer: pending → queued → sending → sent → delivered → read Her geçişi farklı bir bileşen yürütür — hiçbir taraf yolun tamamını görmez: Bu yolun yanında oturan ve bir kaydı ondan çıkarabilecek iki bileşen vardır:

• No-DLR zamanlayıcı. Bir taşıyıcı hiç teslim onayı döndürmediğinde, zamanlayıcı kanala özgü bir hoş görü penceresinden sonra sent’i submitted_no_receipt durumuna yaşlandırır — bkz. Taşıyıcı doğrulamalı vs. hatta aracı.
• Siz (gönderici). Henüz gönderilmemiş planlanmış bir mesajı iptal etmek onu cancelled durumuna sabitler; hiçbir sağlayıcı çağrısının ve hiçbir DLR’nin dokunmadığı nihai bir durumdur. Sandbox gönderimleri, sağlayıcıya herhangi bir yayınlanmadan önce raporlanan nihai bir durum olan test_sent olarak çözülür. Bir kaydı silmek herhangi bir nihai durumu deleted durumuna taşır; ondan sonra hiçbir şey ona dokunamaz.

Gelecek için planlanmış bir mesaj, lansman saatine kadar scheduled durumunda bekler, ardından kuyruğa katılır. scheduled yalnızca üç yoldan çıkabilir: lansman saatinde queued durumuna yükselme, sizden cancelled, ya da yayınlanmadan önce geçerlilik penceresi dolarsa expired.

​

Taşıyıcı doğrulamalı vs. hatta aracı

Raporlama ve mutabakat için en önemli ayrım, bir durumun taşıyıcı doğrulamalı bir sonuç mu yoksa hatta aracı bir anlaşmazlık mı olduğudur:

• delivered ve read taşıyıcı doğrulamalıdır. Gerçek bir DLR geldi; taşıyıcının kendisi sonucu kapattı.
• submitted_no_receipt aracıdır. Anlamı “gönderim için kabul edildi ve hoş görü penceresi içinde hiçbir onay dönmedi”. Her webhook’ta aracı olarak tanımlanır (state_class: "intermediate", is_terminal: false), çünkü gerçek bir delivered, read veya başarısız DLR daha sonra gelip onun yerini alabilir.

submitted_no_receipt’i bir teslim olarak değil, bilinmeyen bir sonuç olarak ele alın. “Bilinmeyen”in olumluya mı yoksa yalnızca aracıya mı yattığı kanala bağlıdır — bkz. Kanal varyasyonları. expired öbür taraftan bakılan görünümdür: bir DLR geldi, ancak onay penceresi çoktan kapanmış olacak kadar geç. Sonuç bilinemez ve kayıt kapanmıştır; expired abonelere bir message.failed olayı olarak dağıtılır.

​

Kanal varyasyonları

• Meta DM kanalları (Instagram, Messenger). Meta’nın gönderim yüzeyi asla teslim onayı yaymaz. Gönderim sent olarak Orbit’ten çıkar, mesaj meta verilerinde no_dlr_channel’ı işaretler ve 5 dakika sonra submitted_no_receipt durumuna düşer. İsteğe bağlı olarak kabul edilmiş bir alıcıda Meta teslimi kabul anında garanti ettiğinden, bu kanallarda submitted_no_receipt işlevsel bir teslim sinyali gibi davranır ve mesaj meta verileri durumu ayırt edebilmeniz için no_dlr_channel: true taşır.
• SMPP destekli kanallar (SMS, MMS, sesli, faks, RCS). Hoş görü penceresi 30 dakikadır. Burada submitted_no_receipt gerçek bir aracıdır: cihaz mesajı raporlanmamış onayla almış olabilir, taşıyıcı bu rotada asla onay yaymıyor olabilir veya onay aktarım sırasında düşmüş olabilir. Bu oranı teslim oranından ayrı bir sinyal olarak izleyin — bir hedefte yerleşmiş bir submitted_no_receipt oranı ilgisiz bir rotaya veya kırık bir onay rotasına işaret eder ve her iki durumda da soruşturmayı hak eder.
• E-posta. Saf DM kanallarının sahip olmadığı bir başarısızlık sonucu ekler: alıcı posta sunucusu mesajı reddettiğinde bounced. Geri dönme, failed gibi nihai başarısızlık oranınıza dahil olur, ancak alıcı tarafı reddetmelerini sağlayıcı tarafı olanlardan ayırmanıza olanak tanıyan ayrı bir durumdur.
• Gönderici iptali. cancelled yalnızca sizin tarafınızdan raporlanır — henüz gönderilmemiş bir mesaj üzerinde POST /messages/:id/cancel aracılığıyla. Hiçbir taşıyıcı bunu asla yazmaz ve sonuç olarak hiçbir webhook olayı tetiklemez; hiçbir şey aboneye iptali bildirmez. İptali arayüzünüzde gösteriyorsanız ve izlemeniz gerekiyorsa GET /messages/:id çağırın.
• Sandbox / test modu. Test gönderimleri, sağlayıcıya herhangi bir yayınlanmadan önce test_sent olarak çözülür. status: "test_sent" ve metadata.test_mode: true ile message.sent tetikler, bu nedenle abone sandbox trafiğini üretim işlemenin dışında tutmak için metadata.test_mode üzerinden dallandırmalıdır.

​

Neye göre dallanılır

Entegrasyonlar yalnızca makine tarafından okunabilir alanlara göre dallanmalı, asla gösterilen açıklamalara göre dallanmamalıdır:

• status — mesajın güncel durumu. Birincil dallanma noktası budur. Kümenin tamamını işleyin: mutlu yol ve başarısızlık durumlarının yanı sıra cancelled, test_sent, submitted_no_receipt ve bounced’ı unutmayın.
• metadata.classified_error_code — nihai başarısızlık sonuçlarında mevcut; makine tarafından tanımlanmış, makine etkin başarısızlık kategorisi. Operatörün sözlerini istediğinizde message.failed webhook’undaki ham error_code / error_message ile birleştirin.
• metadata.no_dlr_channel — Meta DM kayıtlarında mevcut; submitted_no_receipt’in SMPP’den çevrilen aracı değil, Meta’nın garanti ettiği teslim durumu olduğunu söyler.
• state_class / is_terminal — yaşam döngüsü webhook’unda. is_terminal: true (state_class: "terminal" ile eşleşmiş) sonucun nihai olduğu anlamına gelir; submitted_no_receipt tam olarak kitabı üzerine kapatmayasınız diye is_terminal: false raporlar.

​

Sık yapılan hatalar

1. message.created’i kabul olarak ele almak. message.created, kayıt kuyruğa konduğu anda, herhangi bir sağlayıcı çağrısından önce tetiklenir. Eşzamanlı bir ret (gönderimde 4xx veya anında rejected/failed) bu olayı yine de teslim edilmiş bırakır. Mesajın çıktığı sonucuna varmadan önce onu message.sent ile birleştirin.
2. delivered’ın değişmez olduğunu varsaymak. Bazı rotalardaki taşıyıcılar bir teslim onayı yayar ve dakikalar sonra bir düzeltme yayar — bazı Hintli ve Brezilyalı taşıyıcılar bunu yapar. Orbit buna saygı duyar: bir kayıt delivered → undelivered veya delivered → failed durumuna geçebilir. Durumları kendi veri deponuzda yansıtıyorsanız, güncellemeleri mesaj kimliğine göre idempotent olarak uygulayın; daha önce servis edilmiş bir mesaj için geçişleri atmak yerine.
3. cancelled için webhook beklemek. Asla gelmeyecek — iptal sizin API çağrınıza bağlıdır, bir taşıyıcı çağrısına değil, bu nedenle platform onun için bir olay yaymaz. Kayıt, siz silene kadar cancelled durumunda oturur.
4. submitted_no_receipt’i başarısızlık akışına atmak. Sınıflandırma nedenleriyle message.failed olay türü olarak gelir (ayrı bir rota yoktur), ancak olay türüne değil data.status’a göre dallan ve onu sert başarısızlık tonlarından uzak tut.
5. Mesaj başına tek bir nihai olay beklemek. Bir mesaj, status: "submitted_no_receipt" ile message.failed yayabilir ve ardından yavaş taşıyıcı onayı nihayet geç varış penceresinde geldiğinde message.delivered yayabilir. message_id’ye göre güncelleyin ve tekilleştirin, geç olayın kazanmasına izin verin.

Durum makinesi netleştiğinde, durum başına olay yükleri webhook olayları referansında ve durum semantiği tek başına mesaj durumu yaşam döngüsü referansında bulunur.