Ana içeriğe geç

SMSBAT RESTful API Kılavuzu

SMSBAT RESTful API'sine ilişkin eksiksiz kılavuz - bilmeniz gereken her şey.

Son güncelleme: 29 Ağustos 2025

SMSBAT RESTful API, çeşitli mesaj türlerini göndermenize olanak tanır: Viber-atlıkarınca, Viber-anket, Viber-promo (resimler, video), Viber iş sohbetleri, OTP mesajları (Viber OTP, Flash Call) ve bunların geri dönüş çeşitleri.

Not: Bu, giden mesajlaşma için birleşik HTTP API'sidir. Gelen botlarla (Viber Bot / Telegram Bot) entegrasyona ihtiyacınız varsa lütfen Cascade API'sine bakın.

1. Protokol

  • Protokol: HTTPS
  • İstek Gövdesi: Bir dizi "mesaj" içeren JSON nesnesi.
  • Yöntemler:
  • Verileri almak için 'GET' (mesaj durumu, bakiye vb.)
  • Nesneler oluşturmak için 'POST' (örneğin bir yayın/gönderme başlatmak)
  • Nesneleri değiştirmek için 'PATCH'

2. Yetkilendirme

Size kolaylık sağlamak için çeşitli yetkilendirme yöntemleri sunuyoruz: - HTTP Temel Kimlik Doğrulaması (kontrol panelinizden kullanıcı adı ve şifre). - Bir API Simgesini içeren özel HTTP Başlığı 'X-Yetkilendirme Anahtarı'. - API Simgesini tutan HTTP Temel Kimlik Doğrulama şifre alanı (oturum açma adı olarak @ iletin).

API Token Kontrol Panelinde Kullanıcı Profili altında oluşturulabilir.

İstek Örnekleri

Temel Kimlik Doğrulama ile: 

curl -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
  --user user:password

'X-Yetkilendirme Anahtarı' ile: 

curl -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist

3. Mesaj Gönderme

SMSBAT platformunda, herhangi bir mesaj gönderimi (tek bir mesaj bile) bir "Yayın" (mesaj listesi) olarak kabul edilir.

Uç nokta - Yöntem: POST - URL: https://api.smsbat.com/bat/messagelist - Başlıklar: İçerik Türü: application/json

Temel Yük Yapısı: 

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "text": "Check out our new products!",
      "type": "viber_carousel",
      "ttl": 300,
      "messageData": { ... }
    }
  ]
}

Her Mesaj Nesnesi için Gerekli Alanlar:

  • `kimden': Doğrulanmış gönderenin alfa adı.
  • kime: Alıcının telefon numarası (E.164 biçimi).
  • type: Mesaj türü numaralandırması.
  • metin: Mesajın ana metni (tür metin gerektirmiyorsa isteğe bağlıdır).

Desteklenen 'tür' Değerleri: - "sms" - "viber_service" (veya "viber_trans") - viber_promo - viber_carousel - viber_anket' - 'viber_otp' -viber_session' - 'flaş arama_geri arama' - 'hızlı arama'

İsteğe Bağlı Ortak Alanlar:

  • customerMessageId: Kendi sisteminizdeki dize kimliği (geri aramaları izlemek için kullanılır). Mesaj başına benzersiz olmalıdır.
  • dtSend: Gelecekteki planlanmış gönderimin ISO8601 Tarihi/Saati.
  • dtExpire: Teslimat son tarihinin ISO8601 Tarihi/Saati.
  • ttl: Saniye cinsinden Yaşam Süresi. ('dtExpire' sağlanmazsa API, varsayılan eşlemeyi 'tür'den hesaplar).

Varsayılan TTL'ler (Saniye):

  • "sms" - 86400 (24 saat)
  • "viber_trans" / "viber_service" - 345600
  • viber_promo - 604800
  • "viber_session" - 604800

4. Geri Dönüş Yönlendirmesi (Basamaklı)

Birincil kanalın başarısız olması veya süresinin dolması durumunda ileti teslimini sağlamak için bir geri dönüş kuyruğu belirtebilirsiniz.

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380500505051",
      "text": "test message",
      "type": "viber_service",
      "ttl": 60,
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "text": "test sms fallback message2",
          "type": "sms"
        }
      ]
    }
  ]
}
Geri dönüşler, sağlayıcı ana mesajı reddettiğinde veya TTL'nin süresi dolduğunda tetiklenir.

5. Mesaj Türlerine ve Mesaj Verilerine Genel Bakış

Karmaşık mesaj türleri, "messageData" özelliğine eklenen ek yapılandırmaları gerektirir.

5.1 Viber Promosyonu (viber_promo)

Yalnızca Resim 

"messageData":{
  "img":"https://domain.com/image.png"
}

Metin + Düğme 

"messageData":{
  "buttonText":"Save Now",
  "buttonAction":"https://help.smsbat.com"
}

Resim + Metin + Düğme 'img', 'buttonText' ve 'buttonAction'ı birleştirir.

Video Yükü: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(Video özelliklerini buttonText ve buttonAction ile de birleştirebilirsiniz).

5.2 Viber İşlemsel / Hizmeti (viber_trans, viber_service)

Ekli bir dosya içeren onaylanmış bir şablonunuz varsa: 

"messageData": {
  "fileUrl": "https://domain.com/receipt.pdf",
  "fileName": "Receipt.pdf",
  "fileType": "pdf"
}

'MessageData' içinde bir 'carousel.items' dizisi gerektirir.

Sınırlamalar: - Öğe uzunluğu: 2 ila 5 öğe arasında - Başlık: 2 ila 38 karakter - imageUrl: JPEG/PNG önerilen boyut 215x185

"messageData": {
  "carousel": {
    "items": [
      {
        "title": "50% Off Shoes!",
        "imageUrl": "https://domain.com/image1.png",
        "primaryButton": { "label": "Shop", "actionUrl": "..." },
        "secondaryButton": { "label": "Details", "actionUrl": "..." }
      }
    ]
  }
}

5.4 Viber Anketi / Listesi (viber_survey)

Sohbet görünümünde etkileşimli bir anket oluşturur. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
Mesajın 'text' özelliği anket başlığı görevi görür (Maks. 85 karakter). Her biri maksimum 50 karakterden oluşan 2 ila 5 seçenek arasında geçiş yapabilirsiniz.

5.5 Viber OTP (viber_otp)

Küresel olarak önceden kayıtlı yerelleştirilmiş Viber şablonlarını kullanır. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Şablon parametreleri ("pin", "business_platform_name") kesinlikle büyük/küçük harfe duyarlıdır. API, çeşitli ISO kodu dili çeşitlerini ('EN', 'ES', 'RU', 'TR', 'UK' vb.) destekler.

5.6 Hızlı Arama (hızlı arama)

Çevirilecek numaranın son rakamları (oluşturulan kod) 'text' parametresi aracılığıyla iletilmelidir. 'Metin' atlanırsa kod rastgele seçilir ve onu API'nin senkronize 200 OK Response gövdesinden ("mesajlar/metin") çıkarmanız gerekir.

{
  "from": "FLASHCALL",
  "to": "380500000000",
  "type": "flashcall",
  "text": "340"
}