​

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 doğru — ya da bir hata sonucuna doğru — ilerlerken değişen bir status alanı taşır. Bu sayfa, bu durum makinesini kavram düzeyinde açıklar: durumların ne anlama geldiğini, her geçişi neyin tetiklediğini ve operatöre özgü uçların nerede olduğunu. İlk webhook’unuza abone olmadan veya entegrasyonunuzu mesaj sonuçlarına göre dallamadan önce bunu okuyun. Durum başına anlamlar, tam geçiş tablosu ve webhook-olay eşlemesi mesaj durumu yaşam döngüsü referansında; bir mesajın güncel durumunu okumak için yanıt şeması Messaging API referansında bulunur. Bu sayfa ikisini daha üst bir düzeyde birbirine bağlar.

​

Başarı yolu

Uçtan uca başarılı olan bir mesaj şunları geçer: pending → queued → sending → sent → delivered → read Her geçiş farklı bir aktör tarafından tetiklenir — hiçbir tek taraf tüm yolu görmez: Bu yolun yanında duran ve bir kaydı yoldan çıkarabilen iki aktör vardır:

• DLR-olmayan zamanlayıcı. Bir operatör hiç teslim onayı döndürmediğinde, bir zamanlayıcı kanal başına belirlenen zaman aşımı penceresinden sonra sent’i submitted_no_receipt’e yükseltir — bkz. Operatör onaylı vs. hat ara bekçisi.
• Siz (operatör). Henüz gönderilmemiş bir zamanlanmış mesajın iptali onu cancelled’e taşır — hiçbir sağlayıcı çağrısının ve hiçbir DLR’ın dokunmayacağı bir nihai durum. Sandbox gönderileri test_sent’e çözünür — herhangi bir sağlayıcı gönderisinden önce ulaşılan bir nihai durum. Bir kaydı silmek herhangi bir nihai durumu deleted’e taşır; ardından hiçbir şey ona dokunamaz.

Gelecek için zamanlanmış bir mesaj, ateşleme zamanına kadar scheduled’da bekler ve sonra kuyruğa katılır. scheduled’dan sadece üç şekilde çıkabilir: ateşleme zamanında queued’a yükselen, siz tarafından cancelled ya da gönderimden önce geçerlilik penceresi kapanırsa expired.

​

Operatör onaylı vs. hat ara bekçisi

Raporlama ve uzlaşma açısından en önemli ayrım, bir durumun bir operatör onaylı sonuç mu yoksa bir hat ara bekçisi mi olduğudur:

• delivered ve read operatör onaylıdır. Gerçek bir DLR geldi; operatör sonucu bizzat iddia etti.
• submitted_no_receipt hat aradır. Anlamı “gönderim kabul edildi ve belirlenen süre içinde hiçbir onay gelmedi” dir. Her webhook’ta ara olarak işaretlenir (state_class: "intermediate", is_terminal: false), çünkü gerçek bir delivered, read veya hata DLR’si sonradan gelip üzerine yazabilir.

submitted_no_receipt’i sonuç bilinmiyor olarak ele alın, bir teslim olarak değil. “Bilinmiyor” un olumluya mı yoksa gerçekten belirsiz bir duruma mı yattığı kanala bağlıdır — bkz. Kanal başına uyarılar. expired karşı taraftaki eşdövcüdür: Bir DLR geldi, ama onay penceresinin çoktan kapandığı kadar geç geldi. Sonuç bilinemez ve kayıt kapanır; expired abonlere bir message.failed olayı olarak dağıtılır.

​

Kanal başına uyarılar

• Meta DM kanalları (Instagram, Messenger). Meta’nın Send API’si asla teslim onayı yayınlamaz. Gönderi Orbit’ten sent olarak ayrılır, mesaj meta verilerinde no_dlr_channel olarak işaretlenir ve 5 dakika sonra submitted_no_receipt’e dönüşür. Katılmış (opt-in) bir alıcı için Meta, kabulde teslimi garanti eder — bu kanallarda submitted_no_receipt bu yüzden işlevsel bir teslim sinyali gibi davranır ve mesaj meta verileri bu durumu ayırt edebilmeniz için no_dlr_channel: true taşır.
• SMPP destekli kanallar (SMS, MMS, ses, faks, RCS). Zaman aşımı penceresi 30 dakikadır. Burada submitted_no_receipt gerçekten belirsizdir: cihaz mesajı almış olabilir ama bir onay bildirilmemiş, operatör o rotada hiç onay göndermeyebilir veya onay yolda düşmüş olabilir. Bu oranı teslim oranınızdan ayrı izleyin — bir hedefte yükselen submitted_no_receipt payı, işbirliği yapmayan bir rotaya ya da kırık bir onay yoluna işaret eder ve her iki durumda da araştırmaya değer.
• E-posta. Diğer kanallarda olmayan bir hata sonucu ekler: bounced, alıcı posta sunucusu mesajı reddettiğinde. Bounced, nihai hata oranınıza failed gibi katılır, ama alıcı tarafı retlerini sağlayıcı tarafı retlerinden ayırt edebilmeniz için ayrı bir durumdur.
• Operatör iptali. cancelled yalnızca sizin tarafınızdan ulaşılabilir — gönderilmemiş bir mesajda POST /messages/:id/cancel üzerinden. Hiçbir operatör bunu yazmaz ve dolayısıyla hiçbir webhook olayı tetiklenmez; bir iptal hakkında hiçbir abone bilgilendirilemediği için. Kendi arayüzünüzde iptali sunduyorsanız ve onu gözlemekzorsanız GET /messages/:id’yi sorgulayın.
• Sandbox / test modu. Test gönderileri herhangi bir sağlayıcı gönderisinden önce test_sent’e çözünür. status: "test_sent" ve metadata.test_mode: true ile message.sent tetiklerler, bu nedenle bir abonenin sandbox trafiğini üretim işleminden dışarıda tutmak için metadata.test_mode üzerine dallanması gerekir.

​

Ne üzerine dallanmalı

Entegrasyonlar yalnızca makine tarafından okunabilir alanlara bakmalı, görüntü etiketlerine asla bakmamalıdır:

• status — mesajın güncel durumu. Bu birincil dallanma noktasıdır. Kuruluşunuzu bütün küme üzerine kurun: başarı yolu ve sık hata durumlarının yanı sıra cancelled, test_sent, submitted_no_receipt ve bounced’ı unutmayın.
• metadata.classified_error_code — nihai hatalarda bulunur; normalleştirilmiş, makine tarafından okunabilir hata kategorisi. Operatörün kendi kelime seçimini istediğinizde onu message.failed webhook’larındaki ham error_code / error_message ile birleştirin.
• metadata.no_dlr_channel — Meta DM kayıtlarında bulunur; bir submitted_no_receipt’in teslim garantili Meta durumu olduğunu, belirsiz SMPP durumu olmadığını söyler.
• state_class / is_terminal — yaşam döngüsü webhook’larında. is_terminal: true (eş değeri state_class: "terminal") sonucun nihai olduğu anlamına gelir; submitted_no_receipt özellikle dosyayı kapatmamanız için is_terminal: false rapor eder.

​

Yaygın tuzaklar

1. message.created’i kabul olarak ele almak. message.created, kayıt kuyruğa konulduğu anda, herhangi bir sağlayıcı çağrısından önce tetiklenir. Eşzamanlı bir ret (gönderi sırasında bir 4xx veya anında rejected/failed) yine de bu olayı teslim edilmiş bırakır. Mesajın çıktığı sonucuna varmadan önce onu message.sent ile eşleştirin.
2. delivered’in değiştirilemez olduğunu varsaymak. Bazı rotalardaki operatörler bir teslim onayı verir, sonra dakikalar sonra bir düzeltme yayınlar — bazı Hindistan ve Brezilya operatörleri bunu yapar. Orbit bunu onaylar: kayıt delivered → undelivered veya delivered → failed şeklinde hareket edebilir. Durumları kendi veri deposunuza yansıtıyorsanız, güncellemeleri mesaj kimliğine göre idempotent olarak uygulayın — zaten teslim olarak işaretlediğiniz bir mesaj için geçişleri görmezden gelmeyin.
3. cancelled için webhook beklemek. Asla gelmeyecek — iptal kendi API çağrınızdan çıkar, bir operatör geri çağrısından değil, bu yüzden platform onun için hiçbir olay yayınlamaz. Kayıt sadece cancelled’da kalır, siz silene kadar.
4. submitted_no_receipt’i hata kutuna atmak. Taşıma nedenleriyle message.failed olay türünde gelir (özel bir olay yok), ama yükünün status’u submitted_no_receipt ve is_terminal: false’tur. data.status üzerine dallanım, olay türüne değil; ve onu kesin hata metriklerinden dışarıda tutun.
5. Her mesaj için tam bir nihai olay beklemek. Bir mesaj, yavaş bir operatör onayı geç gelme penceresinin içinde sonunda gelirse, önce status: "submitted_no_receipt" ile message.failed, sonra message.delivered yayınlayabilir. message_id ile tekrarları ayıklayın ve uzlaştın, sonraki olayın üstün gelmesine izin verin.

Durum makinesi netleştiğinde, durum başı webhook yükleri webhook olayları referansında, uç nokta düzeyindeki durum anlamları da mesaj durumu yaşam döngüsü referansında yer alır.