Compatibilitate GMS API

SMSBAT acceptă un strat de compatibilitate cu GMS API. Acest lucru vă permite să migrați integrările existente concepute pentru GMS direct la SMSBAT fără a fi nevoie să vă modificați schemele de rutare a mesajelor, structurile de încărcare utilă sau ascultătorii de apel invers.

Setări de conexiune

Pentru a direcționa solicitările prin SMSBAT, actualizați adresa URL de bază și acreditările de autentificare în integrarea dvs.:

• Adresa URL de bază: https://restapi.smsbat.com
• Endpoint: POST /api/GMSMessage/send_message
• Format de solicitare: application/json
• Autentificare: Autentificare de bază HTTP (folosește acreditările API SMSBAT)

Solicitare parametri

API-ul de compatibilitate GMS acceptă un obiect JSON cu următorii parametri de nivel superior:

Setări opțiuni canal

Obiectul channel_options conține configurații specifice canalului.

=== „Mesaj Viber”

Folosit când `viber` este listat în matricea `canale`.

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `text` | șir | **Da** | Textul corpului mesajului. |
| `ttl` | întreg | **Da** | Time-To-Live în secunde. |
| `img` | șir | Nu | Adresa URL publică HTTPS a imaginii de afișat. |
| `legendă` | șir | Nu | Etichetă text pentru buton. |
| `acțiune` | șir | Nu | Adresa URL de destinație când se face clic pe butonul. |
| `survey_options` | matrice | Nu | Matrice de șiruri (2 până la 5 elemente) pentru a fi afișate ca opțiuni de sondaj. |
| `articole_carusel` | matrice | Nu | Matrice de obiecte de diapozitive pentru a fi afișate ca un carusel Viber (vezi structura din filă). |

**Exemplu de solicitare 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 cu SMS de rezervă”

Activează mesageria Viber cu un SMS automat de rezervă dacă livrarea Viber nu reușește în TTL.

**Exemplu de solicitare de rezervă:**
```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
    }
  }
}
```

=== „Mesaj SMS”

Folosit când `sms` este listat în matricea `canale`.

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `text` | șir | **Da** | Textul corpului mesajului. |
| `alpha_name` | șir | **Da** | Numele alfa expeditorului. |
| `ttl` | întreg | **Da** | Time-To-Live în secunde. |
| `ctr` | boolean | Nu | Activați urmărirea clicurilor CTR pe linkurile din text (`adevărat`/`fals`). |

**Exemplu de solicitare 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
    }
  }
}
```

=== „Sondaj Viber”

Folosit pentru a crea sondaje și sondaje Viber.

Configurația sondajului Viber trebuie să aibă între **2 și 5 opțiuni** în interiorul `survey_options`.

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

=== „Carusel Viber”

Folosit pentru a trimite carduri cu diapozitive cu imagini care pot fi glisate. Fiecare diapozitiv acceptă imaginea, titlul și butoanele.

**Exemplu de solicitare carusel:**
```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"
        }
      ]
    }
  }
}
```

=== „Mesaj push”

Folosit când `push` este listat în matricea `canale`.

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `titlu` | șir | **Da** | Textul titlului notificării push. |
| `text` | șir | **Da** | Textul corpului mesajului. |
| `ttl` | întreg | **Da** | Time-To-Live în secunde. |
| `img` | șir | Nu | Adresa URL publică HTTPS a imaginii de afișat. |
| `legendă` | șir | Nu | Etichetă text pentru buton. |
| `acțiune` | șir | Nu | Adresa URL de destinație când se face clic pe butonul. |
| `ctr` | boolean | Nu | Activați urmărirea clicurilor. |

**Exemplu de solicitare 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 de răspuns

Punctul final returnează răspunsuri în format JSON cu un cod de stare HTTP 200 OK.

Răspuns de succes

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

Răspunsuri de eroare

Dacă validarea sau procesarea eșuează, va fi returnat un răspuns de eroare cu un ErrorCode non-null și un ErrorText detaliat.

=== „Canal/Opțiune neacceptată” json { "MessageId": "00000000-0000-0000-0000-000000000000", "ErrorCode": 10221, "ErrorText": "This type of Message is not supported by the system" }

=== „Număr de opțiuni de sondaj nevalide” json { "MessageId": "00000000-0000-0000-0000-000000000000", "ErrorCode": 10221, "ErrorText": "There can be from 2 to 5 survey options." }

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

=== „Eroare internă de procesare” json { "MessageId": "00000000-0000-0000-0000-000000000000", "ErrorCode": 500, "ErrorText": "Internal server error." }

Format de livrare pentru apel invers

Dacă callback_url a fost specificat în solicitare, SMSBAT trimite actualizări de starea livrării sub formă de încărcare utilă JSON POST către punctul final.

Exemplu de solicitare de apel invers

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
}

Câmpuri de apel invers Descriere

Mapări de stare

1. Stare simplificată (status)

2. Stare detaliată („substatus”)

3. Tip de canal (sent_via)

4. Starea SMSBAT detaliată (hyber_status)