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:

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
    }
  }
}
```

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

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

{
  "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“ json { "MessageId": "00000000-0000-0000-0000-000000000000", "ErrorCode": 10221, "ErrorText": "This type of Message is not supported by the system" }

=== „Ungültige Anzahl der Umfrageoptionen“ json { "MessageId": "00000000-0000-0000-0000-000000000000", "ErrorCode": 10221, "ErrorText": "There can be from 2 to 5 survey options." }

=== „Nicht registrierter Alpha-Name“ json { "MessageId": "00000000-0000-0000-0000-000000000000", "ErrorCode": 400, "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered." }

=== „Interner Verarbeitungsfehler“ json { "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

Statuszuordnungen

1. Vereinfachter Status („Status“)

2. Detaillierter Status („Substatus“)

3. Kanaltyp („sent_via“)

4. Detaillierter SMSBAT-Status („hyber_status“)