Help Center GMS API Uyumluluğu

GMS API Uyumluluğu

SMSBAT, GMS API ile uyumluluk katmanını destekler. Bu, GMS için tasarlanmış mevcut entegrasyonlarınızı, mesaj yönlendirme şemalarınızı, veri yükü yapılarınızı veya geri arama dinleyicilerinizi değiştirmek zorunda kalmadan doğrudan SMSBAT’a taşımanıza olanak tanır.

Bağlantı Ayarları

İstekleri SMSBAT aracılığıyla yönlendirmek için entegrasyonunuzdaki temel URL’yi ve kimlik doğrulama bilgilerini güncelleyin:

Temel URL: https://restapi.smsbat.com
Bitiş noktası: ‘POST /api/GMSMessage/send_message’
İstek Formatı: application/json
Kimlik Doğrulama: HTTP Temel Kimlik Doğrulaması (SMSBAT API kimlik bilgilerinizi kullanır)

İstek Parametreleri

GMS uyumluluk API’si, aşağıdaki üst düzey parametrelere sahip bir JSON nesnesini kabul eder:

Parametre	Tür	Gerekli	Açıklama
’telefon_numarası’	dize	Evet	Alıcının uluslararası biçimdeki telefon numarası (ör. “380501234567”).
‘etiket’	dize	Evet	Kayıtlı gönderenin adı / alfa adı.
‘kanallar’	dizi	Evet	Denenecek kanalların öncelik sırasına göre listesi. Desteklenen değerler: “viber”, “sms”, “push”. Örneğin, `["viber", "sms"]`.
‘kanal_seçenekleri’	nesne	Evet	Her aktif kanal için seçenekleri içeren harita (aşağıya bakın).
‘ekstra_id’	dize	Hayır	Dahili müşteri tarafı mesaj kimliğiniz.
‘geri arama_url’	dize	Hayır	Teslimat durumu geri aramalarını almak için sisteminizdeki uç nokta URL’si.
‘bölüm_kodu’	dize	Hayır	İsteğe bağlı bölüm kodu tanımlayıcısı (varsayılanı ‘ana’dır).

Kanal Seçenekleri Ayarları

‘channel_options’ nesnesi kanala özgü yapılandırmalar içerir.

‘Kanallar’ dizisinde ‘viber’ listelendiğinde kullanılır.

Parametre	Tür	Gerekli	Açıklama
’metin’	dize	Evet	Mesaj gövde metni.
‘ttl’	tamsayı	Evet	Saniyeler içinde Yaşama Süresi.
‘img’	dize	Hayır	Görüntülenecek resmin genel HTTPS URL’si.
‘başlık’	dize	Hayır	Düğme metin etiketi.
‘eylem’	dize	Hayır	Düğmeye tıklandığında hedef URL.
`anket_seçenekleri`	dizi	Hayır	Anket seçenekleri olarak görüntülenecek dize dizisi (2 ila 5 öğe).
`carousel_items`	dizi	Hayır	Viber atlıkarınca olarak görüntülenecek slayt nesneleri dizisi (sekmedeki yapıya bakın).

Viber İstek Örneği:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}

TTL içinde Viber teslimatı başarısız olursa, otomatik SMS geri dönüşüyle Viber mesajlaşmasını etkinleştirir.

Geri Dönüş İsteği Örneği:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

‘Kanallar’ dizisinde ‘sms’ listelendiğinde kullanılır.

Parametre	Tür	Gerekli	Açıklama
’metin’	dize	Evet	Mesaj gövde metni.
‘alfa_adı’	dize	Evet	Gönderenin alfa adı.
‘ttl’	tamsayı	Evet	Saniyeler içinde Yaşama Süresi.
‘ctr’	boole	Hayır	Metindeki bağlantılarda TO tıklama izlemeyi etkinleştirin (“doğru”/“yanlış”).

SMS Talep Örneği:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Viber anketleri ve araştırmaları oluşturmak için kullanılır.

Note

Viber anket yapılandırmasının “survey_options” içinde 2 ila 5 seçenek olması gerekir.

Anket Talebi Örneği:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

Kaydırılabilir resim slayt kartları göndermek için kullanılır. Her slayt resmi, başlığı ve düğmeleri destekler.

Atlıkarınca İsteği Örneği:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Choose an offer",
      "ttl": 60,
      "carousel_items": [
        {
          "title": "Offer 1",
          "image_url": "https://www.example.com/offer-1.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-1",
          "secondary_label": "More",
          "secondary_url": "https://www.example.com/offers"
        },
        {
          "title": "Offer 2",
          "image_url": "https://www.example.com/offer-2.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-2"
        }
      ]
    }
  }
}

‘Kanallar’ dizisinde ‘Push’ listelendiğinde kullanılır.

Parametre	Tür	Gerekli	Açıklama
’başlık’	dize	Evet	Anlık bildirimin başlık metni.
‘metin’	dize	Evet	Mesaj gövde metni.
‘ttl’	tamsayı	Evet	Saniyeler içinde Yaşama Süresi.
‘img’	dize	Hayır	Görüntülenecek resmin genel HTTPS URL’si.
‘başlık’	dize	Hayır	Düğme metin etiketi.
‘eylem’	dize	Hayır	Düğmeye tıklandığında hedef URL.
‘ctr’	boole	Hayır	Tıklama izlemeyi etkinleştirin.

Push İsteği Örneği:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}

Yanıt Formatı

Uç nokta, yanıtları JSON biçiminde bir “HTTP 200 OK” durum koduyla döndürür.

Başarılı Yanıt

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

Hata Yanıtları

Doğrulama veya işleme başarısız olursa, boş olmayan bir “Hata Kodu” ve ayrıntılı “Hata Metni” içeren bir hata yanıtı döndürülür.

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

Geri Arama Teslim Formatı

İstekte “callback_url” belirtildiyse SMSBAT, teslimat durumu güncellemelerini uç noktanıza JSON POST yükü olarak gönderir.

Geri Arama İsteği Örneği

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

Geri Arama Alanları Açıklaması

Alan	Tür	Açıklama
’sayı’	dize	Alıcının telefon numarası.
‘zaman’	sayı	Unix milisaniye cinsinden olay zaman damgası.
‘durum’	sayı	Basitleştirilmiş durum tanımlayıcı (bkz. Durum kodu tablosu).
‘alt durum’	sayı	Ayrıntılı durum tanımlayıcı (bkz. Alt durum kodu tablosu).
‘hyber_status’	sayı	Ayrıntılı SMSBAT dahili durum kodu (bkz. Hyber Durum tablosu).
‘mesaj_kimliği’	dize	Gönderme sırasında oluşturulan SMSBAT mesaj kimliği (GUID).
‘ekstra_id’	dize	Orijinal istekte sağlanan müşteri tarafı kimliği.
`sent_via`	dize	Mesajı işleyen kanal: “viber”, “sms” veya “rcs”.
‘eşleşen_şablon_kimliği’	sayı	Viber şablon eşleşme durumu (varsa).

Durum Eşlemeleri

1. Basitleştirilmiş Durum (`durum`)

Kod	Anlamı
’1’	Mesaj kabul edildi veya teslim ediliyor.
‘2’	Mesaj teslim edildi.
‘3’	İşleme veya teslimat hatası.

2. Ayrıntılı Durum (`alt durum`)

Kod	Anlamı
’12’	İşlenmek üzere kabul edildi.
‘23’	Teslim edilmiş.
‘24’	Görüldü/okundu.
‘35’	TTL (Süresi Dolmuş) dahilinde teslim edilmedi.
‘36’	Teslimat hatası.

3. Kanal Türü (`sent_via`)

Kanal	Açıklama
’viber’	Viber kanalı tarafından üretilen durum.
‘sms’	SMS kanalı tarafından oluşturulan durum.
‘rc’	RCS kanalı tarafından oluşturulan durum.

4. Ayrıntılı SMSBAT Durumu (`hyber_status`)

Kod	Kanal	Durum	Alt Durum	Anlamı
23033	’viber'	'2'	'23’	Viber mesajı iletildi.
24013	’viber'	'2'	'24’	Alıcı tarafından okunan Viber mesajı (Görüldü).
36013	’viber'	'3'	'36’	Viber dahili hatası.
36023	’viber'	'3'	'36’	Geçersiz veya kullanılamayan Viber hizmet kimliği.
36033	’viber'	'3'	'36’	Geçersiz Viber verisi.
36037	’viber'	'3'	'36’	Viber resim URL’si çok uzun.
36038	’viber'	'3'	'36’	Geçersiz Viber resim URL’si.
36039	’viber'	'3'	'36’	Viber metni çok uzun.
36044	’viber'	'3'	'36’	Viber metnini boşaltın.
36053	’viber'	'3'	'36’	Desteklenmeyen Viber mesaj türü.
36063	’viber'	'3'	'36’	Geçersiz Viber parametreleri.
36073	’viber'	'3'	'36’	Viber sağlayıcı zaman aşımı.
36083	’viber'	'3'	'36’	Viber göndereni alıcı tarafından engellendi.
36093	’viber'	'3'	'36’	Alıcı Viber kullanıcısı olarak kayıtlı değil.
36103	’viber'	'3'	'36’	Viber desteğine sahip Android/iOS cihazı bulunamadı.
36113	’viber'	'3'	'36’	Viber gönderimi için yetkisiz IP adresi.
36123	’viber'	'3'	'36’	Yinelenen Viber mesajı algılandı.
36143	’viber'	'3'	'36’	Viber faturalandırma hatası.
36153	’viber'	'3'	'36’	İleti platform kara listesi tarafından engellendi.
36163	’viber'	'3'	'36’	Viber platformu dahili işleme hatası.
36173	’viber'	'3'	'36’	Yanlış veya eksik Viber etiketi.
36183	’viber'	'3'	'36’	Geçersiz Viber TTL değeri.
12011	’sms’ / ‘rcs'	'1'	'12’	SMS/RCS kabul edildi.
36011	’sms’ / ‘rcs'	'1'	'12’	SMS/RCS yolda.
23011	’sms’ / ‘rcs'	'2'	'23’	SMS/RCS teslim edildi.
35015	’sms’ / ‘rcs'	'3'	'35’	SMS/RCS’nin süresi doldu (TTL dahilinde teslim edilmedi).
36021	’sms’ / ‘rcs'	'3'	'36’	SMS/RCS mesajı silindi.
36031	’sms’ / ‘rcs'	'3'	'36’	SMS/RCS teslim edilemiyor.
36041	’sms’ / ‘rcs'	'3'	'36’	Bilinmeyen SMS/RCS teslim durumu.
36051	’sms’ / ‘rcs'	'3'	'36’	SMS/RCS mesajı reddedildi.

Search Results

GMS API Uyumluluğu

Bağlantı Ayarları

İstek Parametreleri

Kanal Seçenekleri Ayarları

Yanıt Formatı

Başarılı Yanıt

Hata Yanıtları

Geri Arama Teslim Formatı

Geri Arama İsteği Örneği

Geri Arama Alanları Açıklaması

Durum Eşlemeleri

1. Basitleştirilmiş Durum (durum)

2. Ayrıntılı Durum (alt durum)

3. Kanal Türü (sent_via)

4. Ayrıntılı SMSBAT Durumu (hyber_status)

1. Basitleştirilmiş Durum (`durum`)

2. Ayrıntılı Durum (`alt durum`)

3. Kanal Türü (`sent_via`)

4. Ayrıntılı SMSBAT Durumu (`hyber_status`)