SMSBAT RESTful API-Leitfaden
Vollständiger Leitfaden zur SMSBAT RESTful API – alles, was Sie wissen müssen.
Letzte Aktualisierung: 29. August 2025
Mit der SMSBAT RESTful API können Sie verschiedene Nachrichtentypen senden: Viber-Karussell, Viber-Umfrage, Viber-Promo (Bilder, Video), Viber-Geschäftschats, OTP-Nachrichten (Viber OTP, Flash Call) und deren Fallback-Varianten.
Hinweis: Dies ist die einheitliche HTTP-API für ausgehende Nachrichten. Wenn Sie Integrationen mit Inbound-Bots (Viber Bot/Telegram Bot) benötigen, lesen Sie bitte die Cascade API.
1. Protokoll
- Protokoll: HTTPS
- Anfragetext: JSON-Objekt, das ein Array von „Nachrichten“ enthält.
- Methoden:
- „GET“, um Daten abzurufen (Nachrichtenstatus, Kontostand usw.)
- „POST“ zum Erstellen von Objekten (z. B. Initiieren einer Übertragung/Versand)
- „PATCH“ zum Ändern von Objekten
2. Autorisierung
Für Ihren Komfort bieten wir verschiedene Autorisierungsmethoden an: - HTTP-Basisauthentifizierung (Login und Passwort von Ihrem Dashboard). - Benutzerdefinierter HTTP-Header „X-Authorization-Key“, der ein API-Token enthält. - Passwortfeld für die HTTP-Basisauthentifizierung mit dem API-Token (übergeben Sie „@“ als Login).
API-Token kann im Dashboard unter Benutzerprofil generiert werden.
Beispiele anfordern
Mit Basic Auth:
curl -H "Content-Type: application/json" \
-X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
--user user:password
Mit „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. Nachrichten senden
In der SMSBAT-Plattform gilt jeder Nachrichtenversand (auch eine einzelne Nachricht) als „Broadcast“ (Nachrichtenliste).
Endpunkt - Methode: POST - URL: „https://api.smsbat.com/bat/messagelist“. - Header: „Content-Type: application/json“.
Grundlegende Nutzlaststruktur:
{
"messages": [
{
"from": "ALPHANAME",
"to": "380936670003",
"text": "Check out our new products!",
"type": "viber_carousel",
"ttl": 300,
"messageData": { ... }
}
]
}
Erforderliche Felder für jedes Nachrichtenobjekt:
- „von“: Verifizierter Alpha-Name des Absenders.
- „an“: Telefonnummer des Empfängers (E.164-Format).
- „Typ“: Enumeration des Nachrichtentyps.
- „Text“: Haupttext der Nachricht (optional, wenn der Typ keinen Text erfordert).
Unterstützte „Typ“-Werte:
- „SMS“.
- „viber_service“ (oder „viber_trans“)
- „viber_promo“.
- viber_carousel
- „viber_survey“.
- viber_otp
- „viber_session“.
- flashcall_callback
- „Flashcall“.
Optionale gemeinsame Felder:
- „customerMessageId“: String-ID in Ihrem eigenen System (wird zum Verfolgen von Rückrufen verwendet). Muss pro Nachricht eindeutig sein.
- „dtSend“: ISO8601-Datum/Uhrzeit des geplanten zukünftigen Versands.
- „dtExpire“: ISO8601 Datum/Uhrzeit der Lieferfrist.
ttl: Time-To-Live in Sekunden. (Wenn „dtExpire“ nicht bereitgestellt wird, berechnet die API die Standardzuordnung anhand des „Typs“.)
Standard-TTLs (Sekunden):
- „SMS“ – 86400 (24 Stunden)
- „viber_trans“ / „viber_service“ – 345600
- „viber_promo“ – 604800
- „viber_session“ – 604800
4. Fallback-Routing (Kaskadierung)
Sie können eine Fallback-Warteschlange angeben, um die Nachrichtenzustellung sicherzustellen, wenn der primäre Kanal ausfällt oder abläuft.
{
"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"
}
]
}
]
}
5. Übersicht über Nachrichtentypen und Nachrichtendaten
Komplexe Nachrichtentypen erfordern zusätzliche Konfigurationen, die in die Eigenschaft „messageData“ eingefügt werden.
5.1 Viber Promo (viber_promo)
Nur Bild
Text + Schaltfläche
Bild + Text + Schaltfläche Kombiniert „img“, „buttonText“ und „buttonAction“.
Videonutzlast:
"messageData":{
"video": "https://domain.com/test.mp4",
"thumbnail": "https://domain.com/carusel.png",
"fileSize": 12000000,
"duration": 30
}
5.2 Viber-Transaktional/Dienst („viber_trans“, „viber_service“)
Wenn Sie über eine genehmigte Vorlage verfügen, die eine angehängte Datei enthält:
"messageData": {
"fileUrl": "https://domain.com/receipt.pdf",
"fileName": "Receipt.pdf",
"fileType": "pdf"
}
5.3 Viber-Karussell (viber_carousel)
Erfordert ein „carousel.items“-Array innerhalb von „messageData“.
Einschränkungen: - Artikellänge: zwischen 2 und 5 Artikeln - Titel: 2 bis 38 Zeichen - „imageUrl“: JPEG/PNG empfohlene Größe 215 x 185
"messageData": {
"carousel": {
"items": [
{
"title": "50% Off Shoes!",
"imageUrl": "https://domain.com/image1.png",
"primaryButton": { "label": "Shop", "actionUrl": "..." },
"secondaryButton": { "label": "Details", "actionUrl": "..." }
}
]
}
}
5.4 Viber-Umfrage/-Liste (viber_survey)
Erstellt eine interaktive Umfrage innerhalb der Chat-Ansicht.
Die Eigenschaft „Text“ der Nachricht dient als Umfragetitel (maximal 85 Zeichen). Sie können zwischen 2 und 5 Optionen mit jeweils maximal 50 Zeichen übergeben.5.5 Viber OTP (viber_otp)
Verwendet weltweit vorregistrierte lokalisierte Viber-Vorlagen.
"messageData": {
"templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
"templateLang": "uk",
"templateParams": {
"pin": "3211",
"business_platform_name": "SMSBAT",
"code_validity_time": 7
}
}
5.6 Flash-Anruf („Flashcall“)
Die letzten Ziffern der Rufnummer (der generierte Code) müssen über den Parameter „text“ übergeben werden. Wenn „text“ weggelassen wird, wird der Code randomisiert und Sie müssen ihn aus dem synchronen 200 OK-Antworttext der API („messages/text“) extrahieren.