SMS ve desteklenen MMS gönderin

Göndermeden önce

Hesabınız için yapılandırılmış bir gönderici numarası kullanarak SMS veya desteklenen MMS gönderin. Bu, alıcılara ulaşabilen ve ücret doğurabilen bir canlı ortam işlemidir. Yalnızca yetki verilen alıcılara, onaylanmış mesaj trafiği gönderin; aşağıdaki örnek numaralar ve referans kurgusaldır.

Hesabınızın giden mesajlaşma onayına ve geçerli gönderici, ülke ve trafik izinlerine sahip olması gerekir. Doğrudan Kişisel/Tüketici kullanıcı kimlik bilgileri bu API için uygun değildir. Onaylanmış, API'ye özel kimlik bilgilerinin ayrı bir uygunluk süreci vardır; mobil P2P göndericileri için ek P2P ve ABD/Kanada izinleri gerekebilir. API kimlik bilgilerini her türlü trafiği göndermek için otomatik izin olarak görmek yerine, doğru hesap yapılandırmasını MultiTEL ile teyit edin.

Gönderim isteği

Etkinleştirilmiş bir API hesabıyla, bu hesap için izin verilen kaynak IP adresinden HTTPS üzerinden kimlik doğrulayın. Kimlik bilgilerini sunucu tarafındaki gizli bilgi deposunda tutun. Form kodlamalı alanlarla POST kullanın; hiçbir form veya sorgu alanı sağlanmadığında ise bir JSON nesnesi kullanın. Kimlik bilgilerini veya mesaj metnini URL'ye koymayın.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'from=12025550123' \
  --data-urlencode 'to=12025550124' \
  --data-urlencode 'text=Your requested update is ready.' \
  --data-urlencode 'reference=order-update-example' \
  https://api.multitel.net/v3/sendsms

JSON dizisi için to alanında gerçek bir dizi kullanın; bir form alanına JSON dizisini metin olarak koymayın. İlk entegrasyon testini tek alıcıya gönderimle yapın. Grup ve MMS desteği rotaya göre değişir; bu nedenle bunları kullanmadan önce desteklenen birleşimi teyit edin.

Sonucun tamamını okuyun

Yalnızca örnek amaçlı seçilmiş alanlar gösterilmiştir; gösterilen maliyet bir fiyat teklifi değildir.

{
  "status": {
    "code": "200",
    "msg": ""
  },
  "response": {
    "sms_log_id_ori": 42,
    "to": "12025550124",
    "from": "12025550123",
    "status": "Success",
    "message": "Message queued",
    "causecode": 0,
    "uniqueid": "fixture-message",
    "cost": "$0.0120",
    "carrier_fee_usd": "0.0020000000",
    "chars": 31,
    "parts": 1,
    "encoding": "GSM-7",
    "permsg": "$0.0120",
    "pid": "fixture-reference"
  }
}

HTTP durumunu, JSON status.code alanını ve yanıtın status/message alanlarını birlikte kontrol edin. Sonuç kodları metin türünde olabilir. Destek sırasında eşleştirme yapılabilmesi için sms_log_id_ori alanını ve döndürülen mesaj/referans değerlerini saklayın. Eski sistemden gelen uniqueid ve pid değerleri rotaya göre değişir; biçimlerine ilişkin çıkarım yapmayın veya bunların istemci idempotans belirteçleri olduğunu varsaymayın.

Success veya Message queued genellikle seçilen rotanın kabulünü ifade eder; mesajın bir kişinin telefonuna ulaştığı anlamına gelmez. sent gibi bir ilk geri çağrı durumu, tek başına nihai teslimatı kanıtlamaz.

Segmentler ve ücretler

Göndermeden önce son metnin tamamı üzerinde SMS uzunluk analizini kullanın. SMS fiyatları hedefe ve hesabın hizmetine bağlıdır; geçerli operatör ücretleri segment başına eklenir. Gönderim akışı, alıcı fiyatlarını ve geçerli ücretleri toplar, ardından hesaplanan SMS segment sayısıyla çarpar. Bu hesaplamada bir MMS isteğini tek mesaj olarak ele alır.

cost ve permsg, eski yanıt biçiminde biçimlendirilmiş parasal metin değerleridir. carrier_fee_usd, operatör ücreti bileşenini USD cinsinden bildirir ve hesaplanan gönderim toplamına zaten dahildir; bunu ikinci kez eklemeyin. Gerçek hesap fiyatlandırması ve rota kullanılabilirliği, hesabınız özelinde kontrol edilmelidir. Bu istek yalnızca fiyat sorgulayan bir işlem değildir.

İncelenen kod, başarılı operatör gönderim akışından sonra hesaptan tutar düşer; ancak operatör kabulü, verilerin yerel olarak kalıcı kaydı ve faturalandırma tek bir atomik işlem değildir. Üst sisteme yapılan bir istek kabul edildikten sonra hata veya zaman aşımı oluşabilir. İstemciye bir idempotans anahtarı sunulmaz: aynı referansın tekrarlanması yeniden gönderime ve yeniden ücretlendirmeye neden olabilir.

Yerel teslimat ve karma sonuçlar

Yerel olarak barındırılan numaralar, harici bir operatör gönderimi olmadan MultiTEL'in gelen mesajlaşma akışına kabul edilebilir (accepted). Tamamı yerel alıcılardan oluşan bir istekte yanıt, accepted, message_id, provider ve delivery_status alanlarını içerebilir. Yerel kabul, alıcının yapılandırılmış yönlendirme hedefinin çalıştığını garanti etmez.

Mevcut olduklarında local_delivery_results ve partial alanlarını inceleyin. Bir alıcı için accepted değeri true olarak görünebilirken yönlendirme sonucu başarısız olabilir. Karma bir istekte, operatör tarafından kabul edilmiş (accepted) alıcılar bulunurken yerel kısım başarısız olabilir. Tüm grubu otomatik olarak yeniden göndermeyin: önce her alıcının sonucunu kayıtlarla karşılaştırarak netleştirin.

Tamamı yerel alıcılardan oluşan bir isteğin kabulü, bu akışta sıfır giden mesaj maliyeti bildirir; ancak alıcılar yine de normal gelen mesajlaşma ücretlerine tabi olabilir. Sıfır giden mesaj maliyetini, hiçbir hesabın ücretlendirilmeyeceğinin garantisi olarak yorumlamayın.

Geri çağrılar ve eşleştirme

notifyurl sağlandığında, ilk geri çağrı bir status kapsayıcısına ve message_id, reference, from, to, status, status_text, error_code, timestamp ve accepted dahil yanıt alanlarına sahiptir. Yerel sonuçlar da bulunabilir. API kimlik bilgilerini veya gereksiz mesaj içeriklerini günlüklere kaydetmeden eşleştirme bilgilerini saklayın.

Bu işleyici, söz konusu ilk geri çağrıya bir imzalama alanı eklemez. Doğrulanmamış bir geri çağrıyı başka bir işlem için tek başına yetkilendirme olarak kullanmayın. Hesabınız için desteklenen entegrasyon/webhook yapılandırmasına başvurun ve belirsiz sonuçları portal kayıtlarıyla karşılaştırarak veya destek yardımıyla netleştirin. Geri çağrıların yalnızca bir kez veya nihai teslimat sırasına göre geleceğini varsaymayın.

Hatalar ve güvenli kurtarma

Doğrulama hatalarında API kodu 403 kullanılabilir. Hesap onayı, P2P ve ülke politikası retlerinde HTTP durumu da 403 olarak ayarlanabilir ve makine tarafından okunabilir bir response.code alanı bulunabilir. Hız sınırlarında yeniden deneme bilgisiyle birlikte 429 kullanılabilir. Bir politikanın kullanılamaması veya gönderim/yerel kalıcı kayıt hatası durumunda 503 ya da 500 kullanılabilir; eski sistemdeki yetersiz bakiye durumu da 500 döndürebilir.

429 durumunda Retry-After başlığına ve varsa response.retry_after değerine uyun. Hesap, gönderici, ülke veya alıcı reddi durumunda yeniden denemeden önce nedeni giderin. Zaman aşımı veya belirsiz bir gönderim sonucu durumunda istek zamanını, referansı ve döndürülen tanımlayıcıları saklayın; yeniden göndermeden önce portalı inceleyin ve destekle iletişime geçin. Tek başına günlük kaydının bulunmaması, hiçbir operatörün isteği kabul etmediğinin kanıtı değildir.