အကြောင်းအရာသို့ ကရန်

SMSBAT RESTful API လမ်းညွှန်

SMSBAT RESTful API အတွက် လမ်းညွှန်ချက်အပြည့်အစုံ - သင်သိလိုသမျှ။

နောက်ဆုံးမွမ်းမံပြင်ဆင်သည်- သြဂုတ် ၂၉၊ ၂၀၂၅

SMSBAT RESTful API သည် သင့်အား အမျိုးမျိုးသော မက်ဆေ့ချ်အမျိုးအစားများကို ပေးပို့နိုင်သည်- Viber-carousel၊ Viber-survey၊ Viber-promo (ပုံများ၊ ဗီဒီယို)၊ Viber business chats၊ OTP မက်ဆေ့ချ်များ (Viber OTP၊ Flash Call) နှင့် ၎င်းတို့၏ နောက်ပြန်လှည့်မှုမျိုးကွဲများ။

မှတ်ချက်- ဤသည်မှာ ပြင်ပစာတိုပေးပို့ခြင်းအတွက် ပေါင်းစည်းထားသော HTTP API ဖြစ်သည်။ အကယ်၍ သင်သည် inbound bots (Viber Bot / Telegram Bot) နှင့် ပေါင်းစည်းမှု လိုအပ်ပါက Cascade API ကို ကိုးကားပါ။

1. ပရိုတိုကော

  • Protocol- HTTPS
  • တောင်းဆိုမှုကိုယ်ထည်- စာများ ၏ array တစ်ခုပါရှိသော JSON အရာဝတ္ထု။
  • နည်းလမ်းများ
  • ဒေတာရယူရန် GET (မက်ဆေ့ခ်ျအခြေအနေ၊ လက်ကျန်ငွေ၊ စသည်ဖြင့်)
  • အရာဝတ္ထုများဖန်တီးရန် POST (ဥပမာ၊ ထုတ်လွှင့်မှု/ပေးပို့မှု စတင်ခြင်း)
  • အရာဝတ္ထုများကိုမွမ်းမံရန် PATCH

2. ခွင့်ပြုချက်

သင့်အဆင်ပြေစေရန်အတွက် ခွင့်ပြုချက်နည်းလမ်းများစွာကို ကျွန်ုပ်တို့ ပံ့ပိုးပေးသည်- - HTTP Basic Authentication (သင်၏ dashboard မှ login နှင့် password)။ - API တိုကင်ပါရှိသော စိတ်ကြိုက် HTTP Header X-Authorization-Key။ - HTTP Basic Authentication စကားဝှက်အကွက်တွင် API တိုကင်ကို ကိုင်ဆောင်ထားပါ (လော့ဂ်အင်အဖြစ် @ ကိုဖြတ်သန်းပါ။

API Token သည် User Profile အောက်ရှိ Dashboard တွင် ထုတ်ပေးနိုင်သည်။

ဥပမာများ တောင်းဆိုခြင်း။

Basic Auth ဖြင့်- 

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

X-ခွင့်ပြုချက်-ကီး ဖြင့်- 

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. စာတိုပေးပို့ခြင်း။

SMSBAT ပလပ်ဖောင်းတွင်၊ မည်သည့်မက်ဆေ့ဂျ်ပေးပို့မှု (မက်ဆေ့ချ်တစ်ခုတည်းပင်) ကို "ထုတ်လွှင့်ခြင်း" (မက်ဆေ့ချ်စာရင်း) အဖြစ် သတ်မှတ်သည်။

အဆုံးမှတ် - နည်းလမ်း- POST - URL- https://api.smsbat.com/bat/messagelist - ခေါင်းစီးများ- အကြောင်းအရာ-အမျိုးအစား- application/json

** အခြေခံ ပေးချေမှု ဖွဲ့စည်းပုံ-** 

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

Message Object တစ်ခုစီအတွက် လိုအပ်သော အကွက်များ-

  • from- ပေးပို့သူ အယ်လ်ဖာအမည်ကို အတည်ပြုပြီးပါပြီ။
  • to- လက်ခံသူဖုန်းနံပါတ် (E.164 ဖော်မတ်)။
  • type: မက်ဆေ့ချ် အမျိုးအစား enum။
  • text- မက်ဆေ့ခ်ျ၏ အဓိကစာသား (စာသားအမျိုးအစားမလိုအပ်ပါက ရွေးချယ်နိုင်သည်)။

** ပံ့ပိုးထားသော အမျိုးအစား တန်ဖိုးများ-** - sms - viber_service (သို့မဟုတ် viber_trans) - viber_promo - viber_carousel - viber_survey - viber_otp - viber_session - flashcall_callback - flashcall

ရွေးချယ်နိုင်သော ဘုံအကွက်များ-

  • customerMessageId- သင့်ကိုယ်ပိုင်စနစ်အတွင်းရှိ စာတန်း ID (ပြန်ခေါ်မှုများကို ခြေရာခံရန်အတွက် အသုံးပြုသည်)။ မက်ဆေ့ချ်တစ်ခုစီတွင် ထူးခြားမှုရှိရမည်။
  • dtSend: ISO8601 စီစဉ်ထားသော အနာဂတ် ပေးပို့မှု၏ ရက်စွဲ/အချိန်။
  • dtExpire: ISO8601 ပေးပို့မှုနောက်ဆုံးရက်၏ ရက်စွဲ/အချိန်။
  • ttl- အချိန်-To-Live စက္ကန့်ပိုင်းအတွင်း။ (dtExpire ကို မပေးပါက၊ API သည် type မှ ပုံသေမြေပုံဆွဲခြင်းကို တွက်ချက်သည်)။

မူရင်း TTLs (စက္ကန့်)-

  • sms - 86400 (24 နာရီ)
  • viber_trans / viber_service - 345600
  • viber_promo - 604800
  • viber_session - 604800

4. Fallback Routing (Cascading)

ပင်မချန်နယ် ပျက်ကွက် သို့မဟုတ် သက်တမ်းကုန်ဆုံးပါက မက်ဆေ့ဂျ်ပေးပို့မှုသေချာစေရန်အတွက် နောက်ပြန်တန်းစီခြင်းကို သတ်မှတ်နိုင်သည်။

{
  "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"
        }
      ]
    }
  ]
}
ပံ့ပိုးပေးသူက ပင်မမက်ဆေ့ဂျ်ကို ငြင်းပယ်သည့်အခါ သို့မဟုတ် TTL သက်တမ်းကုန်သွားသည့်အခါ မှားယွင်းမှုများ ဖြစ်ပေါ်လာသည်။

5. Message Types & messageData ၏ ခြုံငုံသုံးသပ်ချက်

ရှုပ်ထွေးသော မက်ဆေ့ချ်အမျိုးအစားများသည် messageData ပိုင်ဆိုင်မှုထဲသို့ ထည့်သွင်းထားသော နောက်ထပ်ဖွဲ့စည်းပုံများ လိုအပ်သည်။

5.1 Viber ပရိုမိုရှင်း (viber_promo)

ရုပ်ပုံသီးသန့် 

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

** စာသား + ခလုတ် ** 

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

** ရုပ်ပုံ + စာသား + ခလုတ် ** img၊ buttonText နှင့် buttonAction တို့ကို ပေါင်းစပ်ထားသည်။

** ဗီဒီယိုပေးချေမှု- 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(သင်သည် ဗီဒီယိုဂုဏ်သတ္တိများကို buttonText နှင့် buttonAction တို့နှင့်လည်း ပေါင်းစပ်နိုင်သည်)။

5.2 Viber Transactional / Service (viber_trans၊ viber_service)

ပူးတွဲဖိုင်ပါရှိသော အတည်ပြုထားသော နမူနာပုံစံတစ်ခုရှိပါက- 

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

messageData အတွင်းရှိ carousel.items array တစ်ခု လိုအပ်သည်။

ကန့်သတ်ချက်များ- - ပစ္စည်းအရှည်- 2 နှင့် 5 ခုကြား - ခေါင်းစဉ်- စာလုံး ၂ လုံးမှ ၃၈ လုံး - imageUrl- JPEG/PNG အကြံပြုထားသော အရွယ်အစား 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 စစ်တမ်း / စာရင်း (viber_survey)

ချတ်မြင်ကွင်းအတွင်း အပြန်အလှန်တုံ့ပြန်မှုစစ်တမ်းတစ်ခု ဖန်တီးပါ။ 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
မက်ဆေ့ဂျ်၏ စာသား ပိုင်ဆိုင်မှုသည် စစ်တမ်းခေါင်းစဉ် (အများဆုံး ၈၅ လုံး) အဖြစ် လုပ်ဆောင်သည်။ ရွေးချယ်စရာ 2 ခုမှ 5 ခုကြား၊ အများဆုံး 50 စာလုံးစီကို သင်ဖြတ်သန်းနိုင်သည်။

5.5 Viber OTP (viber_otp)

တစ်ကမ္ဘာလုံးအတိုင်းအတာဖြင့် ကြိုတင်စာရင်းသွင်းထားသော Viber နမူနာများကို အသုံးပြုသည်။ 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
နမူနာပုံစံဘောင်များ (pin၊ business_platform_name) သည် တင်းကြပ်စွာ အကြီးအသေး အထိမခံပါ။ API သည် ISO ကုဒ်ဘာသာစကားမျိုးကွဲအမျိုးမျိုး (EN၊ ES၊ RU၊ TR၊ UK စသည်ဖြင့်) ပံ့ပိုးပေးပါသည်။

5.6 Flash Call (flashcall)

ဖုန်းခေါ်ဆိုသည့်နံပါတ်၏ နောက်ဆုံးဂဏန်းများ (ထုတ်လုပ်လိုက်သောကုဒ်) ကို စာသား ကန့်သတ်ချက်မှတစ်ဆင့် ပေးပို့ရပါမည်။ စာသား ကိုချန်လှပ်ထားပါက၊ ကုဒ်ကို ကျပန်းလုပ်ဆောင်ပြီး ၎င်းကို API ၏ synchronous 200 OK တုံ့ပြန်မှုကိုယ်ထည် (messages/text) မှ ထုတ်ယူရပါမည်။

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