შიგთავსზე გადასვლა

SMSBAT RESTful API სახელმძღვანელო

სრული გზამკვლევი SMSBAT RESTful API – ყველაფერი რაც თქვენ უნდა იცოდეთ.

_ ბოლოს განახლდა: 2025 წლის 29 აგვისტო _

SMSBAT RESTful API საშუალებას გაძლევთ გაგზავნოთ სხვადასხვა ტიპის შეტყობინებები: Viber-carousel, Viber-Survey, Viber-promo (სურათები, ვიდეო), Viber-ის ბიზნეს ჩეთები, OTP შეტყობინებები (Viber OTP, Flash Call) და მათი სარეზერვო ვარიანტები.

შენიშვნა: ეს არის ერთიანი HTTP API გამავალი შეტყობინებებისთვის. თუ თქვენ გჭირდებათ ინტეგრაცია შემომავალ ბოტებთან (Viber Bot / Telegram Bot), გთხოვთ, მიმართოთ Cascade API-ს.

1. პროტოკოლი

  • პროტოკოლი: HTTPS
  • მოთხოვნის ტექსტი: JSON ობიექტი, რომელიც შეიცავს `შეტყობინებების~ მასივს.
  • ** მეთოდები **:
  • GET მონაცემების მისაღებად (შეტყობინებების სტატუსი, ბალანსი და ა.შ.)
  • POST ობიექტების შესაქმნელად (მაგ., გადაცემის/დისპეტჩერიზაციის დაწყება)
  • PATCH ობიექტების შესაცვლელად

2. ავტორიზაცია

ჩვენ გთავაზობთ ავტორიზაციის რამდენიმე მეთოდს თქვენი მოხერხებულობისთვის: - HTTP ძირითადი ავთენტიფიკაცია (შესვლა და პაროლი თქვენი დაფიდან). - მორგებული HTTP ჰედერი X-Authorization-Key, რომელიც შეიცავს API ტოკენს. - HTTP ძირითადი ავთენტიფიკაციის პაროლის ველი, რომელიც შეიცავს API Token-ს (გაატარეთ @ როგორც შესვლა).

API Token შეიძლება გენერირდეს Dashboard-ში მომხმარებლის პროფილი.

მოითხოვეთ მაგალითები

ძირითადი აუთით: 

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

X-Authorization-Key-ით: 

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 - Headers**: Content-Type: application/json

** ძირითადი დატვირთვის სტრუქტურა: ** 

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

აუცილებელი ველები თითოეული შეტყობინების ობიექტისთვის:

  • from: დადასტურებული გამგზავნის ალფა-სახელი.
  • to: მიმღების ტელეფონის ნომერი (ფორმატი E.164).
  • type: შეტყობინების ტიპი enum.
  • ტექსტი: შეტყობინების ძირითადი ტექსტი (სურვილისამებრ, თუ ტიპი არ საჭიროებს ტექსტს).

** მხარდაჭერილი ტიპის~ მნიშვნელობები:** -sms-viber_service(ანviber_trans) -viber_promo-ვაიბერ_კარუსელი-viber_გამოკითხვა-viber_otp-viber_sesion-flashcall_callback-flashcall`

არჩევითი საერთო ველები:

  • customerMessageId: სიმებიანი ID თქვენს საკუთარ სისტემაში (გამოიყენება გამოძახების თვალყურის დევნებისთვის). უნდა იყოს უნიკალური თითო შეტყობინებაზე.
  • dtSend: ISO8601 დაგეგმილი მომავალი გაგზავნის თარიღი/დრო.
  • dtExpire: ISO8601 მიწოდების ვადის თარიღი/დრო.
  • ttl: Time-to-Live წამებში. (თუ "dtExpire" არ არის მოწოდებული, API ითვლის ნაგულისხმევი რუკების "ტიპიდან").

ნაგულისხმევი TTL-ები (წამები):

  • sms - 86400 (24 სთ)
  • viber_trans / viber_service - 345600
  • viber_promo - 604800
  • viber_session - 604800

4. სარეზერვო მარშრუტი (კასკადური)

თქვენ შეგიძლიათ მიუთითოთ სარეზერვო რიგი, რათა უზრუნველყოთ შეტყობინების მიწოდება, თუ პირველადი არხი ვერ მოხერხდება ან ამოიწურება.

{
  "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. შეტყობინებების ტიპებისა და შეტყობინების მონაცემების მიმოხილვა

შეტყობინებების რთული ტიპები საჭიროებენ დამატებით კონფიგურაციას, რომელიც შეყვანილია messageData თვისებაში.

5.1 Viber Promo ("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 Transaction / სერვისი (viber_trans, viber_service)

თუ თქვენ გაქვთ დამტკიცებული შაბლონი, რომელიც შეიცავს თანდართულ ფაილს: 

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

მოითხოვს carousel.items მასივს messageData-ში.

შეზღუდვები: - ნივთების სიგრძე: 2-დან 5 ელემენტამდე - სათაური: 2-დან 38 სიმბოლომდე - 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 Survey / სია ("viber_survey")

ქმნის ინტერაქტიულ გამოკითხვას ჩატის ხედში. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
შეტყობინების ტექსტის თვისება მოქმედებს როგორც გამოკითხვის სათაური (მაქს. 85 სიმბოლო). შეგიძლიათ გაიაროთ 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
  }
}
შაბლონის პარამეტრები („პინი“, „ბიზნესის_პლატფორმის_სახელი“) მკაცრად მგრძნობიარეა რეგისტრის მიხედვით. API მხარს უჭერს ISO კოდის ენის სხვადასხვა ვარიანტებს (EN, ES, RU, TR, UK და ა.შ.).

5.6 ფლეშ ზარი ('flashcall')

აკრეფის ნომრის ბოლო ციფრები (გენერირებული კოდი) უნდა გადაიცეს ტექსტის პარამეტრით. თუ ტექსტი გამოტოვებულია, კოდი რანდომიზებულია და თქვენ უნდა ამოიღოთ იგი API-ს სინქრონული 200 OK პასუხის ორგანოდან (`შეტყობინებები/ტექსტი“).

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