Mesajlaşma API Entegrasyonu: REST, SMPP ve Webhook

Bu rehber, bir uygulamayı WhatsApp, SMS veya e-posta için bir mesajlaşma sağlayıcısına bağlayan arka uç geliştiricileri, çözüm mimarları ve CTO'lar için hazırlandı. Hangi arayüzün kullanılacağını; kimlik doğrulama, idempotency, iletim raporları, yeniden denemeler, hız sınırları ve testlerin nasıl ele alınacağını, örnek istek ve yanıt yapılarıyla anlatır. Konuşmaları CRM ile senkronize etmek için webhook'larla CRM bağlama rehberine de göz atabilirsiniz.

Hangi arayüzü kullanmalısınız: REST, SMPP veya webhook?

Göndermek için REST, almak için webhook kullanın; SMPP'yi ise yalnızca zaten SMPP işlettiğiniz yüksek hacimli SMS için tercih edin. Bunlar rakip değil, birbirini tamamlayan yöntemlerdir: çoğu entegrasyon, giden tarafta REST çağrılarını, dönüş tarafında webhook'ları birlikte kullanır.

SMPP (Short Message Peer-to-Peer) oturumları bir bind ile (transmitter, receiver veya transceiver) başlar, mesajları submit_sm ile gönderir, iletim raporlarını ve gelen SMS'leri deliver_sm ile alır ve enquire_link ile canlı kalır. Verimlidir ancak işletmesi HTTPS'ten daha ağırdır.

Kimlik doğrulama nasıl yapılmalı?

Sağlayıcının sunduğu en güçlü yöntemi kullanın, gizli anahtarları koddan uzak tutun ve her iki yönü de doğrulayın.

• Giden çağrılar: TLS üzerinden Authorization başlığında gönderilen API anahtarları veya OAuth 2.0 bearer token'lar. Bunları bir gizli anahtar yöneticisinde saklayın; düzenli aralıklarla ve personel değişikliklerinden sonra yenileyin.
• SMPP: bind sırasında sistem kimliği ve parola; genellikle izin verilen IP adresleriyle sınırlandırılır ve destekleniyorsa TLS üzerinden kullanılır.
• Gelen webhook'lar: her olayda imzayı doğrulayın. Meta, WhatsApp Cloud API webhook yüklerini uygulama gizli anahtarınızla hesaplanan, X-Hub-Signature-256 başlığındaki bir HMAC-SHA256 imzasıyla imzalar; sağlayıcılar genellikle benzer bir şema sunar. İmzayı, içeriği ayrıştırmadan önce ham gövde üzerinden hesaplayın.

Sızan bir test anahtarının canlı trafik gönderememesi için her ortam için ayrı kimlik bilgileri kullanın.

Bir mesaj güvenli biçimde nasıl gönderilir?

Kuyruk üzerinden gönderin, bir idempotency anahtarı ekleyin ve yanıtı "iletildi" değil, "kabul edildi" olarak değerlendirin.

Örnek gönderim isteği

Aşağıdaki yapı, belirli bir sağlayıcının API'si değil, açıklama amaçlı sözde JSON'dur.

POST /v1/messages
Authorization: Bearer <token>
Idempotency-Key: 7f3c9a2e-order-55821-shipped

{
  "channel": "whatsapp",
  "to": "+9715XXXXXXXX",
  "template": {
    "name": "order_shipped",
    "language": "ar",
    "variables": ["Layla", "55821", "15 March"]
  },
  "client_reference": "order-55821",
  "callback_url": "https://api.example.com/webhooks/messaging"
}

Örnek yanıt

202 Accepted

{
  "message_id": "msg_01HZX...",
  "status": "accepted",
  "client_reference": "order-55821",
  "created_at": "2026-10-09T12:00:00Z"
}

message_id değerini hemen kendi referansınızla birlikte saklayın. Bundan sonra olan her şey asenkron olarak gelir.

Idempotency neden önemlidir?

Çünkü ağ zaman aşımları, sunucu işlemi zaten yaptıktan sonra gerçekleşebilir. Gönderim isteğiniz zaman aşımına uğradığında körlemesine yeniden denerseniz müşteri iki OTP veya iki kargo bildirimi alabilir. Idempotency anahtarı, sunucunun yeniden denemeyi tanımasını ve ilk sonucu döndürmesini sağlar.

İşe yarayan kurallar:

1. Anahtarı her denemede rastgele bir değerden değil, iş olayından türetin (örneğin sipariş kimliği ile olay türü).
2. Aynı gönderimin her yeniden denemesinde aynı anahtarı kullanın.
3. Anahtarları, yeniden deneme pencerenizi kapsayacak kadar uzun süre saklayın.
4. Sağlayıcı anahtarları desteklemiyorsa göndermeden önce mükerrer kayıtları kendi tarafınızda ayıklayın.

IETF'nin taslak Idempotency-Key başlığı bu deseni HTTP API'leri için standartlaştırır; sağlayıcıların uygulamaları farklılık gösterdiğinden dokümantasyonlarını okuyun.

İletim raporları nasıl çalışır?

İletim durumu sonradan olay olarak gelir: WhatsApp ve çoğu REST API için webhook'larla, SMPP'de ise deliver_sm raporlarıyla. Durumların anlamı kanala göre değişir; mesaj iletim durumu rehberimiz her birini açıklar.

Örnek durum webhook'u

POST /webhooks/messaging
X-Signature: sha256=<hmac>

{
  "event_id": "evt_9c1...",
  "type": "message.status",
  "message_id": "msg_01HZX...",
  "client_reference": "order-55821",
  "status": "delivered",
  "timestamp": "2026-10-09T12:00:04Z",
  "error": null
}

Durum olaylarını savunmacı biçimde işleyin:

• Mükerrer olayları ayıklayın: event_id üzerinden ya da mesaj kimliği artı durum üzerinden.
• Geri gitmeyin: olaylar sırasız geldiğinde bir mesajı okundu durumundan tekrar iletildi durumuna döndürmeyin.
• Hızlıca 2xx ile yanıtlayın, sonra işlemeyi bir kuyruktan yapın.
• Hata kodlarını kaydedin: başarısız mesajlar için hangilerinin yeniden denenebilir olduğuna karar verin.
• Boşluklar beklenmeli: bazı SMS rotaları sınırlı rapor döndürür; okundu durumu ise kanala ve kullanıcının ayarlarına bağlıdır.

Yeniden denemeler ve hız sınırları nasıl yönetilmeli?

Yalnızca başarılı olabilecek istekleri yeniden deneyin, jitter ile üstel geri çekilme uygulayın ve sunucunun sinyallerine uyun.

RFC 9110, saniye veya tarih taşıyabilen Retry-After başlığını tanımlar. Sağlayıcının belgelenmiş sınırlarını hatalar üzerinden öğrenmek yerine altında kalmak için gönderimlerinizin önüne istemci tarafında bir hız sınırlayıcı koyun. WhatsApp'ta ayrıca Meta tarafında, kaç benzersiz müşteriye mesaj atabileceğinize dair sınırlar da vardır; bunlar mesajlaşma limitleri ve kalite puanı yazısında anlatılır.

Canlıya geçmeden önce nasıl test etmelisiniz?

Yalnızca sorunsuz senaryoyu değil, hata senaryolarını da test edin.

Canlı öncesi kontrol listesi

1. Her şablonu, Arapça metin dahil gerçek uzunlukta değerlerle gönderin.
2. Bir zaman aşımını zorlayın ve yeniden denemenin mesajı çoğaltmadığını doğrulayın.
3. Geçersiz bir numaraya gönderin ve hatanın yeniden deneme yapılmadan ele alındığını doğrulayın.
4. Bir webhook'u iki kez ve sırasız tekrar oynatın; tek bir nihai durum oluştuğunu doğrulayın.
5. Hatalı imzalı bir webhook gönderin; reddedildiğini doğrulayın.
6. İzin veriliyorsa sandbox'a yük testi uygulayarak 429 yanıtlarını tetikleyin.
7. Bir API anahtarını yenileyin ve kesinti olmadığını doğrulayın.
8. Günlüklerde mesaj kimliklerinin bulunduğunu, ancak tam mesaj içeriklerinin veya OTP kodlarının bulunmadığını kontrol edin.
9. Her kanalda şirket içi numaralarla küçük bir canlı pilot çalıştırın.

Sandbox ortamları operatör ve Meta davranışını nadiren birebir yansıttığından, canlıya geçişin ilk haftalarında izlemeyi sürdürün.

Uygulamalı örnek: OTP ve sipariş bildirim servisi

Suudi Arabistan'da faaliyet gösteren bir kargo şirketi olan "Qafilah Logistics" (kurgusal), WhatsApp üzerinden sipariş güncellemeleri gönderiyor, SMS'i yedek olarak kullanıyor ve kimlik doğrulama OTP'leri iletiyor.

• Mimari: sipariş olayları bir kuyruğa gider; gönderici işçi (worker), shipment-id:event biçimindeki idempotency anahtarıyla REST API'yi çağırır.
• Yedek: WhatsApp kullanmayan bir kullanıcı için başarısız durumu dönerse, işçi yeni bir anahtarla (shipment-id:event:sms) SMS gönderir.
• OTP: kodların süresi çabuk dolduğundan, OTP gönderimleri süre penceresi geçtikten sonra yeniden denenmez; kullanıcı yeni kod ister. OTP kimlik doğrulama mesajları rehberine bakın.
• Raporlar: bir webhook alıcısı imzaları doğrular, mükerrer olayları ayıklar ve asla geriye gitmeyen bir durum tablosunu günceller.
• Sınırlar: token bucket tabanlı bir sınırlayıcı, kanal başına gönderim hızını belgelenmiş sınırların altında tutar.

Entegrasyonda sık yapılan hatalar nelerdir?

• "Kabul edildi" durumunu "iletildi" sanmak.
• Her denemede yeni bir idempotency anahtarıyla yeniden denemek.
• Webhook isteğinin içinde ağır işlem yapmak.
• Webhook'larda imza doğrulamasını atlamak.
• 4xx doğrulama hatalarını döngü halinde yeniden denemek.
• OTP kodlarını ve tam mesaj içeriğini günlüğe yazmak.
• Test ortamlarında canlı kimlik bilgileri kullanmak.

OmniChannels.ai nasıl yardımcı olur?

BroadNet Technologies altyapısıyla çalışan OmniChannels.ai; SMS, WhatsApp, RCS, Messenger, Instagram, Telegram, e-posta ve push kanallarını kapsayan, OpenAPI 3.1 spesifikasyonu ve TypeScript SDK'sı bulunan, herkese açık dokümante edilmiş bir REST/JSON API sunar. Buna tek dokunuşlu, sıfır dokunuşlu ve kod kopyalama OTP seçenekli WhatsApp kimlik doğrulama şablonları da dahildir. Webhook'lar iletim durumlarını tek bir normalleştirilmiş biçimde bildirir, SMPP 3.4 TLS üzerinden yüksek hacimli SMS'e hizmet eder ve bir MCP sunucusu yapay zeka ajanlarını bağlar. Filtreli ve CSV dışa aktarımlı iletim raporları, entegrasyonunuzun gönderdiklerini mutabakata bağlamanıza yardımcı olur. Geliştirici dokümanları ve hızlı başlangıç ile başlayın.