SMSBAT RESTful API Οδηγός

Πλήρης οδηγός για το SMSBAT RESTful API – όλα όσα πρέπει να γνωρίζετε.

Τελευταία ενημέρωση: 29 Αυγούστου 2025

Το SMSBAT RESTful API σάς επιτρέπει να στέλνετε διάφορους τύπους μηνυμάτων: Viber-carousel, Viber-survey, Viber-promo (εικόνες, βίντεο), επαγγελματικές συνομιλίες Viber, μηνύματα OTP (Viber OTP, Flash Call) και τις εναλλακτικές παραλλαγές τους.

Σημείωση: Αυτό είναι το ενοποιημένο API HTTP για εξερχόμενα μηνύματα. Εάν χρειάζεστε ενσωματώσεις με εισερχόμενα bot (Viber Bot / Telegram Bot), ανατρέξτε στο Cascade API.

1. Πρωτόκολλο

Πρωτόκολλο: HTTPS
Σώμα αιτήματος: αντικείμενο JSON που περιέχει έναν πίνακα «μηνυμάτων».
Μέθοδοι:
"GET" για ανάκτηση δεδομένων (κατάσταση μηνύματος, υπόλοιπο κ.λπ.)
«POST» για τη δημιουργία αντικειμένων (π.χ. έναρξη εκπομπής/αποστολής)
«PATCH» για τροποποίηση αντικειμένων

2. Εξουσιοδότηση

Παρέχουμε διάφορες μεθόδους εξουσιοδότησης για τη διευκόλυνσή σας: - Βασικός έλεγχος ταυτότητας HTTP (σύνδεση και κωδικός πρόσβασης από τον πίνακα ελέγχου σας). - Προσαρμοσμένη κεφαλίδα HTTP «X-Authorization-Key» που περιέχει ένα διακριτικό API. - Πεδίο κωδικού πρόσβασης Βασικού ελέγχου ταυτότητας HTTP που κρατά το διακριτικό API (περάστε το @ ως σύνδεση).

Το API Token μπορεί να δημιουργηθεί στον Πίνακα ελέγχου στο Προφίλ χρήστη.

Ζητήστε παραδείγματα

Με Βασική Εξουσιοδότηση:

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, οποιαδήποτε αποστολή μηνύματος (ακόμα και ένα μόνο μήνυμα) θεωρείται «Μετάδοση» (messagelist).

Τερματικό σημείο - Μέθοδος: ΑΝΑΡΤΗΣΗ - URL: https://api.smsbat.com/bat/messagelist - Κεφαλίδες: Τύπος περιεχομένου: εφαρμογή/json

Βασική δομή ωφέλιμου φορτίου:

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

Απαιτούμενα πεδία για κάθε αντικείμενο μηνύματος:

από: επαληθευμένο άλφα όνομα αποστολέα.
προς: Αριθμός τηλεφώνου παραλήπτη (μορφή E.164).
τύπος: Τύπος μηνύματος enum.
text: Κύριο κείμενο του μηνύματος (προαιρετικό εάν ο τύπος δεν απαιτεί κείμενο).

Υποστηριζόμενες τιμές "τύπου": - sms - "viber_service" (ή "viber_trans") - viber_promo - viber_carousel - 'viber_survey' - viber_otp - "viber_session". - "flashcall_callback". - «flashcall».

Προαιρετικά κοινά πεδία:

customerMessageId: Αναγνωριστικό συμβολοσειράς μέσα στο δικό σας σύστημα (χρησιμοποιείται για την παρακολούθηση επιστροφών κλήσης). Πρέπει να είναι μοναδικό ανά μήνυμα.
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. Εναλλακτική δρομολόγηση (Cascading)

Μπορείτε να καθορίσετε μια εναλλακτική ουρά για να διασφαλίσετε την παράδοση μηνυμάτων εάν το κύριο κανάλι αποτύχει ή λήξει.

Τα εναλλακτικά ενεργοποιούνται όταν ο πάροχος απορρίπτει το κύριο href="#__codelineno-3-1">{ "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».

Μόνο εικόνα

"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 («viber_trans», «viber_service»)

Εάν έχετε ένα εγκεκριμένο πρότυπο που περιέχει ένα συνημμένο αρχείο:

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

5.3 Viber Carousel («viber_carousel»)

Απαιτεί έναν πίνακα «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 ("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
  }
}

Οι παράμετροι προτύπου (pin, business_platform_name) είναι αυστηρά διάκριση πεζών-κεφαλαίων. Το API υποστηρίζει διάφορες παραλλαγές γλώσσας κώδικα ISO («EN», «ES», «RU», «TR», «UK» κ.λπ.).

5.6 Flash Call ("flashcall")

Τα τελευταία ψηφία του αριθμού κλήσης (ο κωδικός που δημιουργείται) πρέπει να περάσουν μέσω της παραμέτρου «κείμενο». Εάν το "κείμενο" παραλειφθεί, ο κώδικας τυχαιοποιείται και πρέπει να τον εξαγάγετε από το σώμα σύγχρονης απάντησης 200 OK του API ("μηνύματα/κείμενο").

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