GMS-API-Kompatibilität

SMSBAT unterstützt eine Kompatibilitätsschicht mit der GMS-API. Dadurch können Sie Ihre vorhandenen, für GMS entwickelten Integrationen direkt zu SMSBAT migrieren, ohne Ihre Nachrichtenroutingschemata, Nutzlaststrukturen oder Rückruf-Listener ä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/GMSMessage/send_message
Anfrageformat: application/json
Authentifizierung: HTTP-Basisauthentifizierung (verwendet Ihre SMSBAT-API-Anmeldeinformationen)

Parameter anfordern

Die GMS-Kompatibilitäts-API akzeptiert ein JSON-Objekt mit den folgenden Parametern der obersten Ebene:

Parameter	Geben Sie	ein Erforderlich	Beschreibung
`Telefonnummer`	Zeichenfolge	Ja	Telefonnummer des Empfängers im internationalen Format (z. B. „380501234567“).
`Tag`	Zeichenfolge	Ja	Registrierter Absendername/Alphaname.
`Kanäle`	Array	Ja	Liste der auszuprobierenden Kanäle in der Reihenfolge ihrer Priorität. Unterstützte Werte: „viber“, „sms“, „push“. Z. B. „[„viber“, „sms“]“.
`channel_options`	Objekt	Ja	Karte mit Optionen für jeden aktiven Kanal (siehe unten).
`extra_id`	Zeichenfolge	Nein	Ihre interne kundenseitige Nachrichten-ID.
`callback_url`	Zeichenfolge	Nein	Endpunkt-URL auf Ihrem System zum Empfangen von Rückrufen zum Lieferstatus.
`division_code`	Zeichenfolge	Nein	Optionaler Bereichscode-Bezeichner (standardmäßig „main“).

Kanaloptionen-Einstellungen

Das Objekt „channel_options“ enthält kanalspezifische Konfigurationen.

=== „Viber-Nachricht“

Wird verwendet, wenn „viber“ im Array „channels“ aufgeführt ist.

| Parameter | Geben Sie | ein Erforderlich | Beschreibung |
| :--- | :--- | :--- | :--- |
| `Text` | Zeichenfolge | **Ja** | Nachrichtentext. |
| `ttl` | Ganzzahl | **Ja** | Time-To-Live in Sekunden. |
| `img` | Zeichenfolge | Nein | Öffentliche HTTPS-URL des anzuzeigenden Bildes. |
| `Beschriftung` | Zeichenfolge | Nein | Schaltflächentextbeschriftung. |
| „Aktion“ | Zeichenfolge | Nein | Ziel-URL, wenn auf die Schaltfläche geklickt wird. |
| `survey_options` | Array | Nein | Array von Zeichenfolgen (2 bis 5 Elemente), die als Umfrageoptionen angezeigt werden sollen. |
| `carousel_items` | Array | Nein | Array von Folienobjekten zur Anzeige als Viber-Karussell (siehe Struktur auf der Registerkarte). |

**Beispiel für eine Viber-Anfrage:**
```json
{
  "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 mit SMS-Fallback“

Ermöglicht Viber-Messaging mit einem automatischen SMS-Fallback, wenn die Viber-Zustellung innerhalb der TTL fehlschlägt.

**Beispiel für eine Fallback-Anfrage:**
```json
{
  "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-Nachricht

Wird verwendet, wenn „sms“ im Array „channels“ aufgeführt ist.

Parameter	Geben Sie	ein Erforderlich	Beschreibung
`Text`	Zeichenfolge	Ja	Nachrichtentext.
`alpha_name`	Zeichenfolge	Ja	Alphaname des Absenders.
`ttl`	Ganzzahl	Ja	Time-To-Live in Sekunden.
`ctr`	boolescher Wert	Nein	Aktivieren Sie die CTR-Klickverfolgung für Links im Text („true“/„false“).

Beispiel für eine SMS-Anfrage:

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

=== „Viber-Umfrage“

Wird zum Erstellen von Viber-Umfragen und Umfragen verwendet.

!!! Warnung
    Die Viber-Umfragekonfiguration muss zwischen **2 und 5 Optionen** in „survey_options“ enthalten.

**Beispiel für eine Umfrageanfrage:**
```json
{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}
```

=== „Viber-Karussell“

Wird zum Versenden von wischbaren Bild-Diakarten verwendet. Jede Folie unterstützt Bilder, Titel und Schaltflächen.

**Beispiel für eine Karussell-Anfrage:**
```json
{
  "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-Nachricht“

Wird verwendet, wenn „push“ im Array „channels“ aufgeführt ist.

| Parameter | Geben Sie | ein Erforderlich | Beschreibung |
| :--- | :--- | :--- | :--- |
| `Titel` | Zeichenfolge | **Ja** | Titeltext der Push-Benachrichtigung. |
| `Text` | Zeichenfolge | **Ja** | Nachrichtentext. |
| `ttl` | Ganzzahl | **Ja** | Time-To-Live in Sekunden. |
| `img` | Zeichenfolge | Nein | Öffentliche HTTPS-URL des anzuzeigenden Bildes. |
| `Beschriftung` | Zeichenfolge | Nein | Schaltflächentextbeschriftung. |
| „Aktion“ | Zeichenfolge | Nein | Ziel-URL, wenn auf die Schaltfläche geklickt wird. |
| `ctr` | boolescher Wert | Nein | Aktivieren Sie die Klickverfolgung. |

**Beispiel für eine Push-Anfrage:**
```json
{
  "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
    }
  }
}
```

Antwortformat

Der Endpunkt gibt Antworten im JSON-Format mit dem Statuscode „HTTP 200 OK“ zurück.

Erfolgreiche Antwort

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

Fehlerantworten

Wenn die Validierung oder Verarbeitung fehlschlägt, wird eine Fehlerantwort mit einem „ErrorCode“ ungleich Null und einem detaillierten „ErrorText“ zurückgegeben.

=== „Nicht unterstützter Kanal/Option“

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

=== „Ungültige Anzahl der Umfrageoptionen“

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

=== „Nicht registrierter Alpha-Name“

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

=== „Interner Verarbeitungsfehler“

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

Rückruf-Übermittlungsformat

Wenn „callback_url“ in der Anfrage angegeben wurde, sendet SMSBAT Aktualisierungen des Lieferstatus als JSON POST-Nutzlast an Ihren Endpunkt.

Beispiel für eine Rückrufanfrage

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
}

Beschreibung der Rückruffelder

Feld	Geben Sie	ein Beschreibung
`Nummer`	Zeichenfolge	Telefonnummer des Empfängers.
„Zeit“	Nummer	Ereigniszeitstempel in Unix-Millisekunden.
`Status`	Nummer	Vereinfachte Statuskennung (siehe Statuscodetabelle).
`Unterstatus`	Nummer	Detaillierte Statuskennung (siehe Substatus-Codetabelle).
`hyber_status`	Nummer	Detaillierter SMSBAT-interner Statuscode (siehe Hyber-Statustabelle).
`message_id`	Zeichenfolge	SMSBAT-Nachrichten-ID (GUID), die beim Senden generiert wird.
`extra_id`	Zeichenfolge	Kundenseitige ID, die in der ursprünglichen Anfrage angegeben wurde.
`sent_via`	Zeichenfolge	Kanal, der die Nachricht verarbeitet hat: „viber“, „sms“ oder „rcs“.
`matching_template_id`	Nummer	Übereinstimmungsstatus der Viber-Vorlage (sofern zutreffend).

Statuszuordnungen

1. Vereinfachter Status („Status“)

Code	Bedeutung
`1`	Nachricht angenommen oder zugestellt.
`2`	Nachricht zugestellt.
`3`	Verarbeitungs- oder Lieferfehler.

2. Detaillierter Status („Substatus“)

Code	Bedeutung
`12`	Zur Bearbeitung angenommen.
`23`	Geliefert.
`24`	Gesehen/gelesen.
`35`	Nicht innerhalb der TTL geliefert (abgelaufen).
`36`	Lieferfehler.

3. Kanaltyp („sent_via“)

Kanal	Beschreibung
`viber`	Vom Viber-Kanal erstellter Status.
„SMS“	Vom SMS-Kanal erzeugter Status.
`rcs`	Vom RCS-Kanal erzeugter Status.

4. Detaillierter SMSBAT-Status („hyber_status“)

Code	Kanal	Status	Unterstatus	Bedeutung
23033	`viber`	`2`	`23`	Viber-Nachricht zugestellt.
24013	`viber`	`2`	`24`	Viber-Nachricht vom Empfänger gelesen (Gesehen).
36013	`viber`	`3`	`36`	Interner Viber-Fehler.
36023	`viber`	`3`	`36`	Ungültige oder nicht verfügbare Viber-Dienst-ID.
36033	`viber`	`3`	`36`	Ungültige Viber-Nutzlastdaten.
36037	`viber`	`3`	`36`	Viber-Bild-URL zu lang.
36038	`viber`	`3`	`36`	Ungültige Viber-Bild-URL.
36039	`viber`	`3`	`36`	Viber-Text zu lang.
36044	`viber`	`3`	`36`	Leerer Viber-Text.
36053	`viber`	`3`	`36`	Nicht unterstützter Viber-Nachrichtentyp.
36063	`viber`	`3`	`36`	Ungültige Viber-Parameter.
36073	`viber`	`3`	`36`	Zeitüberschreitung beim Viber-Anbieter.
36083	`viber`	`3`	`36`	Viber-Absender vom Empfänger blockiert.
36093	`viber`	`3`	`36`	Der Empfänger ist nicht als Viber-Benutzer registriert.
36103	`viber`	`3`	`36`	Kein Android/iOS-Gerät mit Viber-Unterstützung gefunden.
36113	`viber`	`3`	`36`	Unautorisierte IP-Adresse für Viber-Versand.
36123	`viber`	`3`	`36`	Doppelte Viber-Nachricht erkannt.
36143	`viber`	`3`	`36`	Viber-Abrechnungsfehler.
36153	`viber`	`3`	`36`	Nachricht durch Plattform-Blacklist blockiert.
36163	`viber`	`3`	`36`	Interner Verarbeitungsfehler der Viber-Plattform.
36173	`viber`	`3`	`36`	Falsches oder fehlendes Viber-Label.
36183	`viber`	`3`	`36`	Ungültiger Viber-TTL-Wert.
12011	`sms` / `rcs`	`1`	`12`	SMS/RCS akzeptiert.
36011	`sms` / `rcs`	`1`	`12`	SMS/RCS unterwegs.
23011	`sms` / `rcs`	`2`	`23`	SMS/RCS zugestellt.
35015	`sms` / `rcs`	`3`	`35`	SMS/RCS abgelaufen (nicht innerhalb der TTL zugestellt).
36021	`sms` / `rcs`	`3`	`36`	SMS/RCS-Nachricht gelöscht.
36031	`sms` / `rcs`	`3`	`36`	SMS/RCS können nicht zugestellt werden.
36041	`sms` / `rcs`	`3`	`36`	Unbekannter SMS/RCS-Zustellungsstatus.
36051	`sms` / `rcs`	`3`	`36`	SMS/RCS-Nachricht abgelehnt.