Ana içeriğe geç

Messagio API Uyumluluğu

SMSBAT, Messagio API ile uyumluluk katmanını destekler. Bu, Messagio için tasarlanmış mevcut Viber entegrasyonlarınızı, yük yapınızı yeniden yazmaya veya entegrasyon mantığını değiştirmeye gerek 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
  • Uç nokta: 'POST /api/SendMessage'
  • İstek Formatı: application/x-www-form-urlencoded (Form Verisi)

Kimlik Doğrulama ve Kimlik Bilgileri

İsteklerin kimlik doğrulaması, doğrudan istek gövdesi form verileri içerisinde gönderilen parametreler kullanılarak yapılır:

Parametre Tür Gerekli Açıklama
'kullanıcı' dize Evet SMSBAT hesabı giriş bilgileriniz veya kullanıcı tanımlayıcınız.
'işaret' dize Evet Gönderen adı için kayıtlı API sırrı veya imzası.
'dan' dize Evet Kayıtlı gönderenin alfa adı.
gönderme_yöntemi dize Evet Kanal türü. Normal Viber Business mesajları için "viber"i veya Viber OTP şablonları için "viber_otp"yi kullanın.
'telefon' dize Evet Alıcının uluslararası biçimdeki telefon numarası (ör. "380501234567").

Viber Mesaj Türleri

Belirli parametreleri görüntülemek ve farklı Viber mesaj yapılarına yönelik yük talep etmek için aşağıdan bir sekme seçin:

Basit bir metin mesajı gönderir.

Ek Parametreler:

Parametre Tür Gerekli Açıklama
'txt' dize Evet Mesaj metni.

Yük Yükü Örneği İste: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

Etkileşimli harekete geçirici mesaj düğmesi içeren bir kısa mesaj gönderir.

Ek Parametreler:

Parametre Tür Gerekli Açıklama
'txt' dize Evet Mesaj metni.
'button_text' dize Evet Düğmede görüntülenen metin.
'button_link' dize Evet Düğme tıklandığında hedef URL.

Yük Yükü Örneği İste: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Herkese açık bir resim dosyası gönderir.

Ek Parametreler:

Parametre Tür Gerekli Açıklama
"resim_bağlantısı" dize Evet Resmin genel HTTPS URL'si.
'txt' dize Hayır Resmin altında görüntülenecek isteğe bağlı başlık metni.

Yük Yükü Örneği İste: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png

Metin, resim ve düğme içeren zengin bir kart gönderir.

Ek Parametreler:

Parametre Tür Gerekli Açıklama
'txt' dize Evet Başlık metni.
"resim_bağlantısı" dize Evet Resmin genel HTTPS URL'si.
'button_text' dize Evet Düğmede görüntülenen metin.
'button_link' dize Evet Düğme tıklandığında hedef URL.

Yük Yükü Örneği İste: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hot+deals+inside%21&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

İsteğe bağlı metin başlığı ve eylem düğmeleri içeren bir video dosyası gönderir.

Ek Parametreler:

Parametre Tür Gerekli Açıklama
'video.url' dize Evet Video dosyasının genel HTTPS URL'si.
'video.küçük resim' dize Evet Video önizleme görüntüsünün genel HTTPS URL'si.
'video.size_mb' tamsayı Evet Megabayt cinsinden yaklaşık video dosyası boyutu.
video.duration_sec tamsayı Evet Saniye cinsinden video süresi.
'txt' dize Hayır İsteğe bağlı açıklama metni.
'button_text' dize Hayır İsteğe bağlı düğme metni (başlık veya bağlantı görevi görebilir).
'button_link' dize Hayır İsteğe bağlı düğme bağlantı URL'si.

Yük Yükü Örneği İste: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Önceden onaylanmış bir şablon kullanarak Viber Tek Kullanımlık Şifreleri (OTP) gönderir.

Not

OTP mesajları gönderirken "sending_method"u "viber_otp" olarak ayarlamanız gerekir.

Ek Parametreler:

| Parametre | Tür | Gerekli | Açıklama |
| :--- | :--- | :--- | :--- |
| 'şablon.id' | dize | **Evet** | Önceden onaylanmış Viber OTP şablon kimliği. |
| 'şablon.lang' | dize | **Evet** | Şablon dil kodu (ör. "en", "uk"). |
| 'şablon.params.pin' | dize | **Evet** | Şablona eklenecek OTP pin değeri. |
| `template.params.business_platform_name` | dize | **Evet** | Şablondaki işletme adı yer tutucusu. |
| 'template.params.code_validity_time' | dize | **Evet** | Dakika cinsinden PIN geçerlilik süresi. |

**Yük Yükü Örneği İste:**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber_otp&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&template.id=otp_template_123&template.lang=en&template.params.pin=123456&template.params.business_platform_name=SMSBAT&template.params.code_validity_time=7
```

Kullanıcının kaydırabileceği birden fazla slayt (kart) içeren etkileşimli bir mesaj kartı gönderir.

Ek Parametreler:

Parametre Tür Gerekli Açıklama
'txt' dize Evet Döngünün başlık metni.
atlıkarınca[N].başlık dize Evet Kartın başlığı 'N' (0'dan başlayarak).
`atlıkarınca[N].image_url' dize Evet 'N' kartının genel HTTPS resim URL'si.
'atlıkarınca[N].birincil_etiket' dize Evet 'N' kartının ana düğme başlığı.
'atlıkarınca[N].birincil_url' dize Evet 'N' kartının ana düğme bağlantısı URL'si.
atlıkarınca[N].ikincil_etiket dize Hayır 'N' kartının ikincil düğme başlığı.
`atlıkarınca[N].ikincil_url' dize Hayır 'N' kartının ikincil düğme bağlantısı URL'si.

Yük Yükü Örneği İste: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2

Etkileşimli bir anket veya anket sorusu içeren bir mesaj gönderir.

Ek Parametreler:

Parametre Tür Gerekli Açıklama
'txt' dize Evet Anket soru metni.
`anket_options[N]' dize Evet 'N' öğesi için anket seçeneği metni (0'dan başlayan dizin). En az 2 seçenek gereklidir.
'seçenek_türü' tamsayı Evet Seçici türü: "1" (RadioButtons) veya "2" (normal Buttons).

Yük Yükü Örneği İste: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1

Yanıt Formatı

Messagio API uyumluluğu uç noktası, yanıtları "HTTP 200 OK" durum koduyla birlikte XML biçiminde döndürür.

Kabul Edildi (Başarılı) Yanıtı

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

Hata Yanıtları

Bir istek parametre doğrulaması başarısız olursa veya kimlik doğrulama başarısız olursa yanıt sıfır olmayan bir kod döndürecektir.

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

Geri aramalar

Geri arama URL'leri platformunuzda uygulanmalı ve barındırılmalıdır. SMSBAT, sisteminizi teslimat olayları, anket yanıtları ve kullanıcı yanıtlarıyla ilgili olarak güncellemek için HTTP geri aramaları gönderir.

1. Teslimat Durumu Geri Araması

Bir mesajın durumu değiştiğinde (teslim edildi, okundu, başarısız oldu) gönderilir.

  • İçerik Türü: application/x-www-form-urlencoded
  • Yöntem: 'POST'

Yük Yükü Formatlarını Talep Edin:

  • Teslim edildi: 
    msg_id=MESSAGE_GUID&status=delivered
  • Görüldü/Okundu: 
    msg_id=MESSAGE_GUID&status=delivered&type=seen
  • Teslim Edilmedi / Başarısız Oldu: 
    msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Alan Açıklaması:

  • msg_id: SendMessage yanıtında döndürülen SMSBAT benzersiz mesaj kimliği (GUID).
  • "durum": Teslimat sonucu ("teslim edildi", "teslim edilmedi" veya "durumu bilinmiyor").
  • tür: Mesaj alıcı tarafından görüntülendiğinde göründü olarak ayarlayın.
  • "status_extished": Teslim edilmeyen durumun özel teknik nedeni (ör. "VIBER_EXPIRED", "VIBER_BLOCKED_BY_USER", "VIBER_USER_NOT_FOUND", "VIBER_NO_DEVICE").

2. Anket Yanıtını Geri Arama

Kullanıcı bir Viber Survey mesajında bir yanıt seçeneğini seçtiğinde tetiklenir.

  • İçerik Türü: application/x-www-form-urlencoded
  • Yöntem: 'POST'

Talep Yükü Formatı: 

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Gelen Kullanıcı Mesajını Geri Arama

Bir kullanıcı Viber Business hizmetinize kısa mesaj veya medya yanıtı gönderdiğinde tetiklenir.

  • İçerik Türü: "application/json"
  • Yöntem: 'POST'

Talep Yükü Formatı: 

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

Alan Açıklaması:

  • msg_id: Gelen yanıt için oluşturulan benzersiz mesaj kimliği.
  • metin: Kullanıcı tarafından gönderilen metin içeriği (yalnızca medya gönderdiyse 'boş' olabilir).
  • medya: Kullanıcı tarafından gönderilen medya eklerini indirmek için doğrudan URL (yalnızca metin ise 'boş' olabilir).
  • telefon: Gönderenin uluslararası formattaki telefon numarası.
  • sender_bm_id: Viber Business gönderen kimliği.