Συμβατότητα Messagio API
Το SMSBAT υποστηρίζει ένα επίπεδο συμβατότητας με το Messagio API. Αυτό σας επιτρέπει να μετεγκαταστήσετε τις υπάρχουσες ενσωματώσεις Viber που έχουν σχεδιαστεί για το Messagio απευθείας στο SMSBAT χωρίς να χρειάζεται να ξαναγράψετε τη δομή του ωφέλιμου φορτίου σας ή να αλλάξετε τη λογική ενσωμάτωσης.
Ρυθμίσεις σύνδεσης
Για να δρομολογήσετε αιτήματα μέσω SMSBAT, ενημερώστε τη βασική διεύθυνση URL και τα διαπιστευτήρια ελέγχου ταυτότητας στην ενσωμάτωσή σας:
- Βασική διεύθυνση URL:
https://restapi.smsbat.com - Τελικό σημείο:
POST /api/SendMessage - Μορφή αιτήματος:
application/x-www-form-urlencoded(Δεδομένα φόρμας)
Έλεγχος ταυτότητας και διαπιστευτήρια
Τα αιτήματα επαληθεύονται χρησιμοποιώντας παραμέτρους που αποστέλλονται απευθείας στα δεδομένα της φόρμας σώματος αιτήματος:
| Παράμετρος | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
| "χρήστης" | χορδή | Ναι | Τα στοιχεία σύνδεσης του λογαριασμού SMSBAT ή το αναγνωριστικό χρήστη. |
| "σημάδι" | χορδή | Ναι | Μυστικό API ή υπογραφή που έχει καταχωρηθεί για το όνομα του αποστολέα. |
| «από» | χορδή | Ναι | Το όνομα του εγγεγραμμένου αποστολέα άλφα. |
| «μέθοδος_αποστολής» | χορδή | Ναι | Τύπος καναλιού. Χρησιμοποιήστε το «viber» για τα κανονικά μηνύματα Viber Business ή το «viber_otp» για τα πρότυπα Viber OTP. |
| «τηλέφωνο» | χορδή | Ναι | Αριθμός τηλεφώνου παραλήπτη σε διεθνή μορφή (π.χ. 380501234567). |
Τύποι μηνυμάτων Viber
Επιλέξτε μια καρτέλα παρακάτω για να δείτε τις συγκεκριμένες παραμέτρους και να ζητήσετε ωφέλιμα φορτία για διαφορετικές δομές μηνυμάτων Viber:
Στέλνει ένα απλό μήνυμα κειμένου.
Πρόσθετες παράμετροι:
| Παράμετρος | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
txt |
χορδή | Ναι | Κείμενο μηνύματος. |
Παράδειγμα αιτήματος ωφέλιμου φορτίου:
Στέλνει ένα μήνυμα κειμένου με ένα διαδραστικό κουμπί παρότρυνσης για δράση.
Πρόσθετες παράμετροι:
| Παράμετρος | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
txt |
χορδή | Ναι | Κείμενο μηνύματος. |
| "κουμπί_κείμενο" | χορδή | Ναι | Το κείμενο εμφανίζεται στο κουμπί. |
| "button_link" | χορδή | Ναι | Διεύθυνση URL προορισμού όταν κάνετε κλικ στο κουμπί. |
Παράδειγμα αιτήματος ωφέλιμου φορτίου:
Στέλνει ένα δημόσιο αρχείο εικόνας.
Πρόσθετες παράμετροι:
| Παράμετρος | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
| "σύνδεσμος_εικόνας" | χορδή | Ναι | Δημόσια διεύθυνση URL HTTPS της εικόνας. |
txt |
χορδή | Όχι | Προαιρετικό κείμενο λεζάντας για εμφάνιση κάτω από την εικόνα. |
Παράδειγμα αιτήματος ωφέλιμου φορτίου:
Στέλνει μια πλούσια κάρτα που περιέχει κείμενο, μια εικόνα και ένα κουμπί.
Πρόσθετες παράμετροι:
| Παράμετρος | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
txt |
χορδή | Ναι | Κείμενο λεζάντας. |
| "σύνδεσμος_εικόνας" | χορδή | Ναι | Δημόσια διεύθυνση URL HTTPS της εικόνας. |
| "κουμπί_κείμενο" | χορδή | Ναι | Το κείμενο εμφανίζεται στο κουμπί. |
| "button_link" | χορδή | Ναι | Διεύθυνση URL προορισμού όταν κάνετε κλικ στο κουμπί. |
Παράδειγμα αιτήματος ωφέλιμου φορτίου:
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
Στέλνει ένα αρχείο βίντεο με προαιρετική λεζάντα κειμένου και κουμπιά ενεργειών.
Πρόσθετες παράμετροι:
| Παράμετρος | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
video.url |
χορδή | Ναι | Δημόσια διεύθυνση URL HTTPS του αρχείου βίντεο. |
βίντεο.μικρογραφία |
χορδή | Ναι | Δημόσια διεύθυνση URL HTTPS της εικόνας προεπισκόπησης βίντεο. |
video.size_mb |
ακέραιος | Ναι | Μέγεθος αρχείου βίντεο κατά προσέγγιση σε Megabyte. |
video.duration_sec |
ακέραιος | Ναι | Διάρκεια βίντεο σε δευτερόλεπτα. |
txt |
χορδή | Όχι | Προαιρετικό κείμενο περιγραφής. |
| "κουμπί_κείμενο" | χορδή | Όχι | Προαιρετικό κείμενο κουμπιού (μπορεί να λειτουργήσει ως λεζάντα ή σύνδεσμος). |
| "button_link" | χορδή | Όχι | Προαιρετική διεύθυνση URL συνδέσμου κουμπιού. |
Παράδειγμα αιτήματος ωφέλιμου φορτίου:
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
Στέλνει Viber One-Time Passwords (OTP) χρησιμοποιώντας ένα προεγκεκριμένο πρότυπο.
Σημείωση
Κατά την αποστολή μηνυμάτων OTP, πρέπει να ορίσετε το «send_method» σε «viber_otp».
Πρόσθετες παράμετροι:
| Παράμετρος | Τύπος | Απαιτείται | Περιγραφή |
| :--- | :--- | :--- | :--- |
| `template.id` | χορδή | **Ναι** | Προεγκεκριμένο αναγνωριστικό προτύπου Viber OTP. |
| «πρότυπο.γλώσσα» | χορδή | **Ναι** | Κωδικός γλώσσας προτύπου (π.χ. "en", "uk"). |
| `template.params.pin` | χορδή | **Ναι** | Η τιμή της ακίδας OTP για εισαγωγή στο πρότυπο. |
| `template.params.business_platform_name` | χορδή | **Ναι** | Το σύμβολο κράτησης θέσης ονόματος επιχείρησης στο πρότυπο. |
| `template.params.code_validity_time` | χορδή | **Ναι** | Περίοδος ισχύος PIN σε λεπτά. |
**Παράδειγμα αιτήματος ωφέλιμου φορτίου:**
```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
```
Στέλνει μια διαδραστική κάρτα μηνυμάτων που περιέχει πολλές διαφάνειες (κάρτες) στις οποίες ο χρήστης μπορεί να σαρώσει.
Πρόσθετες παράμετροι:
| Παράμετρος | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
txt |
χορδή | Ναι | Κείμενο τίτλου του καρουζέλ. |
καρουσέλ[Ν].τίτλος |
χορδή | Ναι | Τίτλος κάρτας N (ξεκινά από 0). |
carousel[N].image_url |
χορδή | Ναι | Δημόσια διεύθυνση URL εικόνας HTTPS της κάρτας "N". |
carousel[N].primary_label |
χορδή | Ναι | Λεζάντα του κύριου κουμπιού της κάρτας "N". |
carousel[N].primary_url |
χορδή | Ναι | URL συνδέσμου κύριου κουμπιού της κάρτας "N". |
carousel[N].secondary_label |
χορδή | Όχι | Λεζάντα δευτερεύοντος κουμπιού της κάρτας "N". |
carousel[N].secondary_url |
χορδή | Όχι | Διεύθυνση URL συνδέσμου δευτερεύοντος κουμπιού της κάρτας "N". |
Παράδειγμα αιτήματος ωφέλιμου φορτίου:
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
Στέλνει ένα μήνυμα που περιέχει μια διαδραστική δημοσκόπηση ή ερώτηση έρευνας.
Πρόσθετες παράμετροι:
| Παράμετρος | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
txt |
χορδή | Ναι | Κείμενο ερωτήσεων έρευνας. |
survey_options[N] |
χορδή | Ναι | Κείμενο επιλογής έρευνας για το στοιχείο "N" (ευρετήριο που ξεκινά από 0). Απαιτούνται τουλάχιστον 2 επιλογές. |
| "τύπος_επιλογής" | ακέραιος | Ναι | Τύπος επιλογέα: 1 (RadioButtons) ή 2 (κανονικά κουμπιά). |
Παράδειγμα αιτήματος ωφέλιμου φορτίου:
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
Μορφή απόκρισης
Το τελικό σημείο συμβατότητας Messagio API επιστρέφει απαντήσεις σε μορφή XML με κωδικό κατάστασης «HTTP 200 OK».
Αποδεκτή (επιτυχής) απάντηση
<response>
<code>0</code>
<tech_message>OK</tech_message>
<msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>
Αποκρίσεις σφαλμάτων
Εάν η επικύρωση παραμέτρων αίτησης αποτύχει ή ο έλεγχος ταυτότητας αποτύχει, η απάντηση θα επιστρέψει έναν μη μηδενικό κωδικό.
Επανακλήσεις
Οι διευθύνσεις URL επιστροφής κλήσης πρέπει να υλοποιούνται και να φιλοξενούνται στην πλατφόρμα σας. Το SMSBAT στέλνει ανακλήσεις HTTP για να ενημερώσει το σύστημά σας σχετικά με συμβάντα παράδοσης, απαντήσεις σε έρευνες και απαντήσεις χρηστών.
1. Επανάκληση κατάστασης παράδοσης
Αποστέλλεται όταν ένα μήνυμα μεταβαίνει σε κατάσταση (παραδόθηκε, διαβάστηκε, απέτυχε).
- Τύπος περιεχομένου:
application/x-www-form-urlencoded - Μέθοδος: 'ΑΝΑΡΤΗΣΗ'
Αίτηση μορφών ωφέλιμου φορτίου:
- Παράδοση:
- Είδα/Διαβάστηκε:
- Δεν παραδόθηκε / Απέτυχε:
Περιγραφή πεδίων:
msg_id: Το μοναδικό αναγνωριστικό μηνύματος SMSBAT (GUID) επιστράφηκε στην απάντηση SendMessage.- "κατάσταση": Αποτέλεσμα παράδοσης ("παραδόθηκε", "μη παράδοση" ή "άγνωστη κατάσταση".
- "τύπος": Ρύθμιση σε "βλέπεται" όταν το μήνυμα έχει προβληθεί από τον παραλήπτη.
- "status_extended": Συγκεκριμένος τεχνικός λόγος για την κατάσταση μη παράδοσης (π.χ. "VIBER_EXPIRED", "VIBER_BLOCKED_BY_USER", "VIBER_USER_NOT_FOUND", "VIBER_NO_DEVICE").
2. Έρευνα Απάντηση Επανάκληση
Ενεργοποιείται όταν ένας χρήστης επιλέγει μια επιλογή απάντησης σε ένα μήνυμα Viber Survey.
- Τύπος περιεχομένου:
application/x-www-form-urlencoded - Μέθοδος: 'ΑΝΑΡΤΗΣΗ'
Μορφή αιτήματος ωφέλιμου φορτίου:
3. Επανάκληση εισερχόμενων μηνυμάτων χρήστη
Ενεργοποιείται όταν ένας χρήστης στέλνει μια απάντηση κειμένου ή πολυμέσων πίσω στην υπηρεσία Viber Business.
- Τύπος περιεχομένου:
application/json - Μέθοδος: 'ΑΝΑΡΤΗΣΗ'
Μορφή αιτήματος ωφέλιμου φορτίου:
{
"msg_id": "INBOUND_MESSAGE_GUID",
"text": "Hello, I have a question",
"media": "https://example.com/user-attachment.png",
"phone": "380501234567",
"sender_bm_id": "12345"
}
Περιγραφή πεδίων:
msg_id: Το μοναδικό αναγνωριστικό μηνύματος που δημιουργήθηκε για την εισερχόμενη απάντηση.text: Περιεχόμενο κειμένου που αποστέλλεται από τον χρήστη (μπορεί να είναι "null" εάν έστειλε μόνο μέσα).μέσα: Απευθείας διεύθυνση URL για λήψη τυχόν συνημμένων πολυμέσων που αποστέλλονται από τον χρήστη (μπορεί να είναι "κενό" εάν μόνο κείμενο).τηλέφωνο: Ο αριθμός τηλεφώνου του αποστολέα σε διεθνή μορφή.sender_bm_id: Το αναγνωριστικό αποστολέα Viber Business.