Συμβατότητα GMS API

Το SMSBAT υποστηρίζει ένα επίπεδο συμβατότητας με το GMS API. Αυτό σας επιτρέπει να μετεγκαταστήσετε τις υπάρχουσες ενσωματώσεις σας που έχουν σχεδιαστεί για GMS απευθείας στο SMSBAT χωρίς να χρειάζεται να τροποποιήσετε τα σχήματα δρομολόγησης μηνυμάτων, τις δομές ωφέλιμου φορτίου ή τους ακροατές επανάκλησης.

Ρυθμίσεις σύνδεσης

Για να δρομολογήσετε αιτήματα μέσω SMSBAT, ενημερώστε τη βασική διεύθυνση URL και τα διαπιστευτήρια ελέγχου ταυτότητας στην ενσωμάτωσή σας:

Βασική διεύθυνση URL: https://restapi.smsbat.com
Τελικό σημείο: POST /api/GMSMessage/send_message
Μορφή αιτήματος: application/json
Έλεγχος ταυτότητας: Βασικός έλεγχος ταυτότητας HTTP (χρησιμοποιεί τα διαπιστευτήριά σας SMSBAT API)

Παράμετροι αιτήματος

Το API συμβατότητας GMS δέχεται ένα αντικείμενο JSON με τις ακόλουθες παραμέτρους ανώτατου επιπέδου:

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
"αριθμός_τηλεφώνου"	χορδή	Ναι	Αριθμός τηλεφώνου παραλήπτη σε διεθνή μορφή (π.χ. `380501234567`).
`tag`	χορδή	Ναι	Εγγεγραμμένο όνομα αποστολέα / όνομα άλφα.
"κανάλια"	συστοιχία	Ναι	Λίστα καναλιών προς δοκιμή, με σειρά προτεραιότητας. Υποστηριζόμενες τιμές: «viber», «sms», «push». Π.χ., `["viber", "sms"]".
"επιλογές_καναλιού"	αντικείμενο	Ναι	Χάρτης που περιέχει επιλογές για κάθε ενεργό κανάλι (δείτε παρακάτω).
`extra_id`	χορδή	Όχι	Το εσωτερικό σας αναγνωριστικό μηνύματος από την πλευρά του πελάτη.
`callback_url`	χορδή	Όχι	URL τελικού σημείου στο σύστημά σας για να λαμβάνετε επανακλήσεις κατάστασης παράδοσης.
«κωδικός_διαίρεσης»	χορδή	Όχι	Προαιρετικό αναγνωριστικό κωδικού διαίρεσης (προεπιλογή σε «κύριο»).

Ρυθμίσεις επιλογών καναλιού

Το αντικείμενο "channel_options" περιέχει διαμορφώσεις για συγκεκριμένα κανάλια.

Μήνυμα ViberViber με εναλλακτικό SMSΜήνυμα SMSΈρευνα ViberViber CarouselΜήνυμα ώθησης

Χρησιμοποιείται όταν το "viber" αναφέρεται στη διάταξη "κανάλια".

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
`κείμενο`	χορδή	Ναι	Κείμενο σώματος μηνύματος.
`ttl`	ακέραιος	Ναι	Time-to-Live σε δευτερόλεπτα.
`img`	χορδή	Όχι	Δημόσια διεύθυνση URL HTTPS της εικόνας προς εμφάνιση.
«λεζάντα»	χορδή	Όχι	Κουμπί ετικέτα κειμένου.
«δράση»	χορδή	Όχι	Διεύθυνση URL προορισμού όταν κάνετε κλικ στο κουμπί.
"επιλογές_έρευνας"	συστοιχία	Όχι	Πίνακας συμβολοσειρών (2 έως 5 στοιχεία) για εμφάνιση ως επιλογές έρευνας.
«αντικείμενα_καρουσέλ»	συστοιχία	Όχι	Σειρά αντικειμένων διαφανειών για εμφάνιση ως καρουζέλ του Viber (δείτε τη δομή στην καρτέλα).

Παράδειγμα αιτήματος Viber:

{
  "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"
    }
  }
}

Ενεργοποιεί την ανταλλαγή μηνυμάτων Viber με αυτόματο εναλλακτικό SMS εάν η παράδοση του Viber αποτύχει εντός του TTL.

Παράδειγμα εναλλακτικού αιτήματος:

{
  "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
    }
  }
}

Χρησιμοποιείται όταν το "sms" αναφέρεται στη διάταξη "κανάλια".

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
`κείμενο`	χορδή	Ναι	Κείμενο σώματος μηνύματος.
"άλφα_όνομα"	χορδή	Ναι	Όνομα άλφα αποστολέα.
`ttl`	ακέραιος	Ναι	Time-to-Live σε δευτερόλεπτα.
`ctr`	boolean	Όχι	Ενεργοποιήστε την παρακολούθηση κλικ CTR σε συνδέσμους σε κείμενο ("true"/"false").

Παράδειγμα αιτήματος SMS:

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

Χρησιμοποιείται για τη δημιουργία δημοσκοπήσεων και ερευνών στο Viber.

Προειδοποίηση

Η διαμόρφωση έρευνας του Viber πρέπει να έχει μεταξύ 2 και 5 επιλογές μέσα στο "survey_options".

Παράδειγμα αιτήματος έρευνας:

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

Χρησιμοποιείται για την αποστολή καρτών διαφανειών εικόνας με δυνατότητα σάρωσης. Κάθε διαφάνεια υποστηρίζει εικόνα, τίτλο και κουμπιά.

Παράδειγμα αιτήματος καρουζέλ:

href="#__codelineno-4-1">{ "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" } ] } } }

Χρησιμοποιείται όταν το "push" αναφέρεται στον πίνακα "κανάλια".

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
«τίτλος»	χορδή	Ναι	Κείμενο τίτλου της ειδοποίησης push.
`κείμενο`	χορδή	Ναι	Κείμενο σώματος μηνύματος.
`ttl`	ακέραιος	Ναι	Time-to-Live σε δευτερόλεπτα.
`img`	χορδή	Όχι	Δημόσια διεύθυνση URL HTTPS της εικόνας προς εμφάνιση.
«λεζάντα»	χορδή	Όχι	Κουμπί ετικέτα κειμένου.
«δράση»	χορδή	Όχι	Διεύθυνση URL προορισμού όταν κάνετε κλικ στο κουμπί.
`ctr`	boolean	Όχι	Ενεργοποιήστε την παρακολούθηση κλικ.

Παράδειγμα αιτήματος ώθησης:

{
  "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
    }
  }
}

Μορφή απόκρισης

Το τελικό σημείο επιστρέφει απαντήσεις σε μορφή JSON με κωδικό κατάστασης "HTTP 200 OK".

Επιτυχής απόκριση

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

Αποκρίσεις σφαλμάτων

Εάν αποτύχει η επικύρωση ή η επεξεργασία, θα επιστραφεί μια απάντηση σφάλματος με μη μηδενικό «ErrorCode» και λεπτομερές «ErrorText».

Μη υποστηριζόμενο κανάλι/επιλογήΜη έγκυρος αριθμός επιλογών έρευναςΜη καταχωρημένο Alpha NameΣφάλμα εσωτερικής επεξεργασίας

{
  "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."
}

Μορφή παράδοσης επανάκλησης

Εάν το "callback_url" καθορίστηκε στο αίτημα, το SMSBAT στέλνει ενημερώσεις κατάστασης παράδοσης ως ωφέλιμο φορτίο JSON POST στο τελικό σημείο σας.

Παράδειγμα αιτήματος επανάκλησης

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
}

Περιγραφή πεδίων επανάκλησης

Πεδίο	Τύπος	Περιγραφή
«αριθμός»	χορδή	Αριθμός τηλεφώνου παραλήπτη.
`χρόνος`	αριθμός	Χρονική σήμανση συμβάντος σε χιλιοστά του δευτερολέπτου Unix.
«κατάσταση»	αριθμός	Απλοποιημένο αναγνωριστικό κατάστασης (δείτε πίνακα κωδικών κατάστασης).
«υποκατάσταση»	αριθμός	Αναλυτικό αναγνωριστικό κατάστασης (βλ. πίνακα κωδικών υποκατάστασης).
`hyber_status`	αριθμός	Λεπτομερής εσωτερικός κωδικός κατάστασης SMSBAT (βλ. πίνακα Κατάστασης Hyber).
"αναγνωριστικό_μηνύματος"	χορδή	Το αναγνωριστικό μηνύματος SMSBAT (GUID) δημιουργήθηκε κατά την αποστολή.
`extra_id`	χορδή	Το αναγνωριστικό από την πλευρά του πελάτη που παρέχεται στο αρχικό αίτημα.
`σταλμένο_μέσω`	χορδή	Κανάλι που επεξεργάστηκε το μήνυμα: "viber", "sms" ή "rcs".
`matching_template_id`	αριθμός	Κατάσταση αντιστοίχισης προτύπου Viber (όπου ισχύει).

Αντιστοιχίσεις κατάστασης

1. Απλοποιημένη κατάσταση ('κατάσταση')

Κωδικός	Σημασία
`1`	Το μήνυμα έγινε αποδεκτό ή παραδίδεται.
`2`	Το μήνυμα παραδόθηκε.
`3`	Σφάλμα επεξεργασίας ή παράδοσης.

2. Λεπτομερής κατάσταση ('substatus')

Κωδικός	Σημασία
`12`	Αποδεκτό για επεξεργασία.
`23`	Παραδόθηκε.
`24`	Είδα/διαβάστηκε.
`35`	Δεν παραδίδεται εντός TTL (Έληξε).
`36`	Σφάλμα παράδοσης.

3. Τύπος καναλιού (`sent_via`)

Κανάλι	Περιγραφή
`viber`	Κατάσταση που παράγεται από το κανάλι Viber.
`sms`	Κατάσταση που παράγεται από κανάλι SMS.
`rcs`	Κατάσταση που παράγεται από το κανάλι RCS.

4. Λεπτομερής κατάσταση SMSBAT ("hyber_status")

Κωδικός	Κανάλι	Κατάσταση	Υποκατάσταση	Σημασία
23033	`viber`	`2`	`23`	Παραδόθηκε μήνυμα Viber.
24013	`viber`	`2`	`24`	Μήνυμα Viber που διαβάζεται από τον παραλήπτη (Εμφανίστηκε).
36013	`viber`	`3`	`36`	Εσωτερικό σφάλμα Viber.
36023	`viber`	`3`	`36`	Μη έγκυρο ή μη διαθέσιμο αναγνωριστικό υπηρεσίας Viber.
36033	`viber`	`3`	`36`	Μη έγκυρα δεδομένα ωφέλιμου φορτίου Viber.
36037	`viber`	`3`	`36`	Η διεύθυνση URL εικόνας Viber είναι πολύ μεγάλη.
36038	`viber`	`3`	`36`	Μη έγκυρη διεύθυνση URL εικόνας Viber.
36039	`viber`	`3`	`36`	Το κείμενο Viber είναι πολύ μεγάλο.
36044	`viber`	`3`	`36`	Κενό κείμενο Viber.
36053	`viber`	`3`	`36`	Μη υποστηριζόμενος τύπος μηνύματος Viber.
36063	`viber`	`3`	`36`	Μη έγκυρες παράμετροι Viber.
36073	`viber`	`3`	`36`	Λήξη χρονικού ορίου παρόχου Viber.
36083	`viber`	`3`	`36`	Ο αποστολέας του Viber έχει αποκλειστεί από τον παραλήπτη.
36093	`viber`	`3`	`36`	Ο παραλήπτης δεν έχει εγγραφεί ως χρήστης του Viber.
36103	`viber`	`3`	`36`	Δεν βρέθηκε συσκευή Android/iOS με υποστήριξη Viber.
36113	`viber`	`3`	`36`	Μη εξουσιοδοτημένη διεύθυνση IP για αποστολή Viber.
36123	`viber`	`3`	`36`	Εντοπίστηκε διπλό μήνυμα Viber.
36143	`viber`	`3`	`36`	Σφάλμα χρέωσης Viber.
36153	`viber`	`3`	`36`	Το μήνυμα αποκλείστηκε από τη μαύρη λίστα της πλατφόρμας.
36163	`viber`	`3`	`36`	Εσωτερικό σφάλμα επεξεργασίας πλατφόρμας Viber.
36173	`viber`	`3`	`36`	Λάθος ή λείπει η ετικέτα Viber.
36183	`viber`	`3`	`36`	Μη έγκυρη τιμή Viber TTL.
12011	`sms` / `rcs`	`1`	`12`	Αποδεκτό SMS/RCS.
36011	`sms` / `rcs`	`1`	`12`	Διαδρομή SMS/RCS.
23011	`sms` / `rcs`	`2`	`23`	Παραδόθηκε SMS/RCS.
35015	`sms` / `rcs`	`3`	`35`	Το SMS/RCS έληξε (δεν παραδόθηκε εντός TTL).
36021	`sms` / `rcs`	`3`	`36`	Το μήνυμα SMS/RCS διαγράφηκε.
36031	`sms` / `rcs`	`3`	`36`	Δεν είναι δυνατή η παράδοση SMS/RCS.
36041	`sms` / `rcs`	`3`	`36`	Άγνωστη κατάσταση παράδοσης SMS/RCS.
36051	`sms` / `rcs`	`3`	`36`	Το μήνυμα SMS/RCS απορρίφθηκε.