Zum Inhalt

Messagio-API-Kompatibilität

SMSBAT unterstützt eine Kompatibilitätsschicht mit der Messagio API. Dadurch können Sie Ihre vorhandenen, für Messagio entwickelten Viber-Integrationen direkt zu SMSBAT migrieren, ohne Ihre Nutzlaststruktur neu schreiben oder die Integrationslogik ändern zu müssen.

Verbindungseinstellungen

Um Anfragen über SMSBAT weiterzuleiten, aktualisieren Sie die Basis-URL und die Authentifizierungsdaten in Ihrer Integration:

  • Basis-URL: https://restapi.smsbat.com
  • Endpunkt: POST /api/SendMessage
  • Anfrageformat: application/x-www-form-urlencoded (Formulardaten)

Authentifizierung und Anmeldeinformationen

Anfragen werden mithilfe von Parametern authentifiziert, die direkt in den Formulardaten des Anfragetexts gesendet werden:

Parameter Geben Sie ein Erforderlich Beschreibung
Benutzer Zeichenfolge Ja Ihr SMSBAT-Konto-Login oder Ihre Benutzerkennung.
Zeichen Zeichenfolge Ja API-Geheimnis oder Signatur, die für den Absendernamen registriert ist.
„von“ Zeichenfolge Ja Registrierter Alpha-Name des Absenders.
sending_method Zeichenfolge Ja Kanaltyp. Verwenden Sie „viber“ für normale Viber Business-Nachrichten oder „viber_otp“ für Viber OTP-Vorlagen.
„Telefon“ Zeichenfolge Ja Telefonnummer des Empfängers im internationalen Format (z. B. „380501234567“).

Viber-Nachrichtentypen

Wählen Sie unten eine Registerkarte aus, um die spezifischen Parameter anzuzeigen und Nutzlasten für verschiedene Viber-Nachrichtenstrukturen anzufordern:

=== „Textnachricht“

Sendet eine einfache Textnachricht.

**Zusätzliche Parameter:**

| Parameter | Geben Sie | ein Erforderlich | Beschreibung |
| :--- | :--- | :--- | :--- |
| `txt` | Zeichenfolge | **Ja** | Nachrichtentext. |

**Beispiel für eine Nutzlastanforderung:**
```http
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=Hello+from+SMSBAT%21
```

Sendet eine Textnachricht mit einer interaktiven Call-to-Action-Schaltfläche.

Zusätzliche Parameter:

Parameter Geben Sie ein Erforderlich Beschreibung
txt Zeichenfolge Ja Nachrichtentext.
button_text Zeichenfolge Ja Text, der auf der Schaltfläche angezeigt wird.
button_link Zeichenfolge Ja Ziel-URL, wenn auf die Schaltfläche geklickt wird.

Beispiel für eine Nutzlastanforderung: 

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=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

=== „Bildnachricht“

Sendet eine öffentliche Bilddatei.

**Zusätzliche Parameter:**

| Parameter | Geben Sie | ein Erforderlich | Beschreibung |
| :--- | :--- | :--- | :--- |
| `image_link` | Zeichenfolge | **Ja** | Öffentliche HTTPS-URL des Bildes. |
| `txt` | Zeichenfolge | Nein | Optionaler Beschriftungstext, der unter dem Bild angezeigt wird. |

**Beispiel für eine Nutzlastanforderung:**
```http
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&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png
```

Sendet eine Rich Card mit Text, einem Bild und einer Schaltfläche.

Zusätzliche Parameter:

Parameter Geben Sie ein Erforderlich Beschreibung
txt Zeichenfolge Ja Beschriftungstext.
image_link Zeichenfolge Ja Öffentliche HTTPS-URL des Bildes.
button_text Zeichenfolge Ja Text, der auf der Schaltfläche angezeigt wird.
button_link Zeichenfolge Ja Ziel-URL, wenn auf die Schaltfläche geklickt wird.

Beispiel für eine Nutzlastanforderung: 

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

=== „Videobotschaft“

Sendet eine Videodatei mit optionaler Textbeschriftung und Aktionsschaltflächen.

**Zusätzliche Parameter:**

| Parameter | Geben Sie | ein Erforderlich | Beschreibung |
| :--- | :--- | :--- | :--- |
| `video.url` | Zeichenfolge | **Ja** | Öffentliche HTTPS-URL der Videodatei. |
| `video.thumbnail` | Zeichenfolge | **Ja** | Öffentliche HTTPS-URL des Videovorschaubilds. |
| `video.size_mb` | Ganzzahl | **Ja** | Ungefähre Videodateigröße in Megabyte. |
| `video.duration_sec` | Ganzzahl | **Ja** | Videodauer in Sekunden. |
| `txt` | Zeichenfolge | Nein | Optionaler Beschreibungstext. |
| `button_text` | Zeichenfolge | Nein | Optionaler Schaltflächentext (kann als Beschriftung oder Link dienen). |
| `button_link` | Zeichenfolge | Nein | Optionale Schaltflächen-Link-URL. |

**Beispiel für eine Nutzlastanforderung:**
```http
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
```

=== „OTP-Vorlage“

Sendet Viber-Einmalpasswörter (OTP) mithilfe einer vorab genehmigten Vorlage.

!!! Hinweis
    Beim Senden von OTP-Nachrichten müssen Sie „sending_method“ auf „viber_otp“ setzen.

Zusätzliche Parameter:

| Parameter | Geben Sie | ein Erforderlich | Beschreibung |
| :--- | :--- | :--- | :--- |
| `template.id` | Zeichenfolge | **Ja** | Vorab genehmigte Viber OTP-Vorlagen-ID. |
| `template.lang` | Zeichenfolge | **Ja** | Code der Vorlagensprache (z. B. „en“, „uk“). |
| `template.params.pin` | Zeichenfolge | **Ja** | Der OTP-Pin-Wert, der in die Vorlage eingefügt werden soll. |
| `template.params.business_platform_name` | Zeichenfolge | **Ja** | Der Platzhalter für den Firmennamen in der Vorlage. |
| `template.params.code_validity_time` | Zeichenfolge | **Ja** | PIN-Gültigkeitsdauer in Minuten. |

**Beispiel für eine Nutzlastanforderung:**
```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
```

=== „Karussellnachricht“

Sendet eine interaktive Nachrichtenkarte mit mehreren Folien (Karten), durch die der Benutzer wischen kann.

**Zusätzliche Parameter:**

| Parameter | Geben Sie | ein Erforderlich | Beschreibung |
| :--- | :--- | :--- | :--- |
| `txt` | Zeichenfolge | **Ja** | Titeltext des Karussells. |
| `carousel[N].title` | Zeichenfolge | **Ja** | Titel der Karte „N“ (beginnend bei 0). |
| `carousel[N].image_url` | Zeichenfolge | **Ja** | Öffentliche HTTPS-Bild-URL der Karte „N“. |
| `carousel[N].primary_label` | Zeichenfolge | **Ja** | Hauptschaltflächenbeschriftung der Karte „N“. |
| `carousel[N].primary_url` | Zeichenfolge | **Ja** | Hauptschaltflächen-Link-URL der Karte „N“. |
| `carousel[N].secondary_label` | Zeichenfolge | Nein | Sekundärschaltflächenbeschriftung der Karte „N“. |
| `carousel[N].secondary_url` | Zeichenfolge | Nein | Sekundäre Schaltflächen-Link-URL der Karte „N“. |

**Beispiel für eine Nutzlastanforderung:**
```http
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
```

Sendet eine Nachricht mit einer interaktiven Umfrage oder Umfragefrage.

Zusätzliche Parameter:

Parameter Geben Sie ein Erforderlich Beschreibung
txt Zeichenfolge Ja Text der Umfragefrage.
survey_options[N] Zeichenfolge Ja Umfrageoptionstext für Element „N“ (Index beginnt bei 0). Es sind mindestens 2 Optionen erforderlich.
option_type Ganzzahl Ja Selektortyp: „1“ (RadioButtons) oder „2“ (normale Buttons).

Beispiel für eine Nutzlastanforderung: 

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

Antwortformat

Der Messagio-API-Kompatibilitätsendpunkt gibt Antworten im XML-Format mit dem Statuscode „HTTP 200 OK“ zurück.

Akzeptierte (Erfolgs-)Antwort

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

Fehlerantworten

Wenn die Validierung von Anforderungsparametern oder die Authentifizierung fehlschlägt, gibt die Antwort einen Code ungleich Null zurück.

=== „Fehlende Signatur“ 

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

=== „Nicht autorisiert“ 

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

Rückrufe

Rückruf-URLs müssen auf Ihrer Plattform implementiert und gehostet werden. SMSBAT sendet HTTP-Rückrufe, um Ihr System hinsichtlich Zustellungsereignissen, Umfrageantworten und Benutzerantworten zu aktualisieren.

1. Rückruf zum Lieferstatus

Wird gesendet, wenn der Status einer Nachricht wechselt (zugestellt, gelesen, fehlgeschlagen).

  • Content-Type: application/x-www-form-urlencoded
  • Methode: POST

Nutzlastformate anfordern:

  • Geliefert: 
    msg_id=MESSAGE_GUID&status=delivered
  • Gesehen/gelesen: 
    msg_id=MESSAGE_GUID&status=delivered&type=seen
  • Nicht zugestellt / fehlgeschlagen: 
    msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Feldbeschreibung:

  • „msg_id“: Eindeutige SMSBAT-Nachrichten-ID (GUID), die in der SendMessage-Antwort zurückgegeben wird.
  • „Status“: Lieferergebnis („geliefert“, „nicht zugestellt“ oder „Status unbekannt“).
  • „Typ“: Wird auf „Gesehen“ gesetzt, wenn die Nachricht vom Empfänger angesehen wurde.
  • „status_extended“: Spezifischer technischer Grund für den nicht zugestellten Status (z. B. „VIBER_EXPIRED“, „VIBER_BLOCKED_BY_USER“, „VIBER_USER_NOT_FOUND“, „VIBER_NO_DEVICE“).

2. Rückruf der Umfrageantwort

Wird ausgelöst, wenn ein Benutzer eine Antwortoption in einer Viber-Umfragenachricht auswählt.

  • Content-Type: application/x-www-form-urlencoded
  • Methode: POST

Nutzlastformat anfordern: 

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Rückruf eingehender Benutzernachrichten

Wird ausgelöst, wenn ein Benutzer eine Text- oder Medienantwort an Ihren Viber Business-Dienst zurücksendet.

  • Content-Type: application/json
  • Methode: POST

Nutzlastformat anfordern: 

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

Feldbeschreibung:

  • „msg_id“: Die eindeutige Nachrichten-ID, die für die eingehende Antwort generiert wurde.
  • „Text“: Vom Benutzer gesendeter Textinhalt (kann „null“ sein, wenn er nur Medien gesendet hat).
  • „Medien“: Direkte URL zum Herunterladen aller vom Benutzer gesendeten Medienanhänge (kann „null“ sein, wenn nur Text).
  • „Telefon“: Telefonnummer des Absenders im internationalen Format.
  • „sender_bm_id“: Die Viber Business-Absender-ID.