Zgodność API GMS

SMSBAT obsługuje warstwę kompatybilności z GMS API. Umożliwia to migrację istniejących integracji zaprojektowanych dla GMS bezpośrednio do SMSBAT bez konieczności modyfikowania schematów routingu wiadomości, struktur ładunku lub słuchaczy wywołań zwrotnych.

Ustawienia połączenia

Aby kierować żądania przez SMSBAT, zaktualizuj podstawowy adres URL i dane uwierzytelniające w swojej integracji:

• Podstawowy adres URL: https://restapi.smsbat.com
• Punkt końcowy: POST /api/GMSMessage/send_message
• Format żądania: aplikacja/json
• Uwierzytelnianie: Podstawowe uwierzytelnianie HTTP (wykorzystuje dane uwierzytelniające API SMSBAT)

Parametry żądania

Interfejs API zgodności GMS akceptuje obiekt JSON z następującymi parametrami najwyższego poziomu:

Ustawienia opcji kanału

Obiekt channel_options zawiera konfiguracje specyficzne dla kanału.

=== „Wiadomość Vibera”

Używane, gdy w tablicy `channels` znajduje się `viber`.

| Parametr | Wpisz | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `tekst` | ciąg | **Tak** | Treść wiadomości. |
| `ttl` | liczba całkowita | **Tak** | Czas życia w sekundach. |
| `img` | ciąg | Nie | Publiczny adres URL HTTPS obrazu do wyświetlenia. |
| `podpis` | ciąg | Nie | Etykieta tekstowa przycisku. |
| `akcja` | ciąg | Nie | Docelowy adres URL po kliknięciu przycisku. |
| `opcje_ankiety` | tablica | Nie | Tablica ciągów (od 2 do 5 elementów) wyświetlana jako opcje ankiety. |
| `elementy_karuzeli` | tablica | Nie | Tablica obiektów slajdów do wyświetlenia jako karuzela Viber (patrz struktura w zakładce). |

**Przykład żądania Viber:**
```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 z zastępczym SMS-em”

Umożliwia przesyłanie wiadomości Viber z automatycznym zastępczym SMS-em, jeśli dostarczenie Viber nie powiedzie się w ciągu TTL.

**Przykład żądania zastępczego:**
```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
    }
  }
}
```

=== „Wiadomość SMS”

Używane, gdy w tablicy `channels` znajduje się `sms`.

| Parametr | Wpisz | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `tekst` | ciąg | **Tak** | Treść wiadomości. |
| `nazwa_alfa` | ciąg | **Tak** | Nazwa alfa nadawcy. |
| `ttl` | liczba całkowita | **Tak** | Czas życia w sekundach. |
| `ctr` | wartość logiczna | Nie | Włącz śledzenie kliknięć CTR linków w tekście („prawda”/„fałsz”). |

**Przykład żądania SMS:**
```json
{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}
```

=== „Ankieta Vibera”

Służy do tworzenia ankiet i ankiet Viber.

Konfiguracja ankiety Viber musi zawierać od **2 do 5 opcji** wewnątrz `opcji_survey_opcji`.

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

=== „Karuzela Vibera”

Służy do wysyłania przesuwanych kart ze slajdami. Każdy slajd obsługuje obraz, tytuł i przyciski.

**Przykład żądania karuzeli:**
```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"
        }
      ]
    }
  }
}
```

=== „Wyślij wiadomość”

Używane, gdy w tablicy „channels” znajduje się słowo „push”.

| Parametr | Wpisz | Wymagane | Opis |
| :--- | :--- | :--- | :--- |
| `tytuł` | ciąg | **Tak** | Tekst tytułu powiadomienia push. |
| `tekst` | ciąg | **Tak** | Treść wiadomości. |
| `ttl` | liczba całkowita | **Tak** | Czas życia w sekundach. |
| `img` | ciąg | Nie | Publiczny adres URL HTTPS obrazu do wyświetlenia. |
| `podpis` | ciąg | Nie | Etykieta tekstowa przycisku. |
| `akcja` | ciąg | Nie | Docelowy adres URL po kliknięciu przycisku. |
| `ctr` | wartość logiczna | Nie | Włącz śledzenie kliknięć. |

**Przykład żądania push:**
```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
    }
  }
}
```

##Format odpowiedzi

Punkt końcowy zwraca odpowiedzi w formacie JSON z kodem stanu „HTTP 200 OK”.

Pomyślna odpowiedź

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

Odpowiedzi na błędy

Jeśli sprawdzanie poprawności lub przetwarzanie nie powiedzie się, zostanie zwrócona odpowiedź na błąd z niepustym kodem „ErrorCode” i szczegółowym tekstem „ErrorText”.

=== „Nieobsługiwany kanał/opcja” json { "MessageId": "00000000-0000-0000-0000-000000000000", "ErrorCode": 10221, "ErrorText": "This type of Message is not supported by the system" }

=== „Nieprawidłowa liczba opcji ankiety” json { "MessageId": "00000000-0000-0000-0000-000000000000", "ErrorCode": 10221, "ErrorText": "There can be from 2 to 5 survey options." }

=== „Niezarejestrowana nazwa alfa” json { "MessageId": "00000000-0000-0000-0000-000000000000", "ErrorCode": 400, "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered." }

=== „Wewnętrzny błąd przetwarzania” json { "MessageId": "00000000-0000-0000-0000-000000000000", "ErrorCode": 500, "ErrorText": "Internal server error." }

Format dostarczania wywołania zwrotnego

Jeśli w żądaniu podano callback_url, SMSBAT wysyła aktualizacje statusu dostarczenia jako ładunek JSON POST do Twojego punktu końcowego.

Przykład żądania oddzwonienia

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
}

Opis pól wywołania zwrotnego

Mapowania stanu

1. Status uproszczony („status”)

2. Status szczegółowy („podstatus”)

3. Typ kanału („wysłane_przez”)

4. Szczegółowy status SMSBAT (hyber_status)