GMS API Съвместимост

SMSBAT поддържа слой за съвместимост с GMS API. Това ви позволява да мигрирате вашите съществуващи интеграции, предназначени за GMS, директно към SMSBAT, без да се налага да променяте вашите схеми за маршрутизиране на съобщения, структури на полезен товар или слушатели на обратно извикване.

Настройки на връзката

За да маршрутизирате заявки през SMSBAT, актуализирайте основния URL адрес и идентификационните данни за удостоверяване във вашата интеграция:

• Основен URL: https://restapi.smsbat.com
• Крайна точка: POST /api/GMSMessage/send_message
• Формат на заявката: application/json
• Удостоверяване: HTTP Basic Authentication (използва вашите идентификационни данни за SMSBAT API)

Параметри на заявката

API за съвместимост на GMS приема JSON обект със следните параметри от най-високо ниво:

Настройки на опциите на канала

Обектът channel_options съдържа специфични за канала конфигурации.

=== „Съобщение във Viber“

Използва се, когато `viber` е посочено в масива `channels`.

| Параметър | Тип | Задължително | Описание |
| :--- | :--- | :--- | :--- |
| `text` | низ | **Да** | Основен текст на съобщението. |
| `ttl` | цяло число | **Да** | Време за живот за секунди. |
| `img` | низ | Не | Обществен HTTPS URL адрес на изображението за показване. |
| `caption` | низ | Не | Текстов етикет на бутона. |
| `action` | низ | Не | Целеви URL адрес при щракване върху бутона. |
| `survey_options` | масив | Не | Масив от низове (2 до 5 елемента) за показване като опции за проучване. |
| `carousel_items` | масив | Не | Масив от слайд обекти за показване като въртележка на Viber (вижте структурата в раздела). |

**Пример за заявка във 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 с резервен SMS“

Активира Viber съобщения с автоматичен резервен SMS, ако доставката на Viber е неуспешна в рамките на TTL.

**Пример за резервна заявка:**
```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
    }
  }
}

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

{
  "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"
        }
      ]
    }
  }
}

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

Формат на отговора

Крайната точка връща отговори във JSON формат с код за състояние HTTP 200 OK.

Успешен отговор

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

Отговори за грешка

Ако проверката или обработката са неуспешни, ще бъде върнат отговор за грешка с ненулево ErrorCode и подробно ErrorText.

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

=== „Невалиден брой опции за анкета“ json { "MessageId": "00000000-0000-0000-0000-000000000000", "ErrorCode": 10221, "ErrorText": "There can be from 2 to 5 survey options." }

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

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

Формат за доставка на обратно извикване

Ако callback_url е посочено в заявката, SMSBAT изпраща актуализации на състоянието на доставката като JSON POST полезен товар до вашата крайна точка.

Пример за заявка за обратно повикване

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
}

Описание на полетата за обратно извикване

Съпоставяне на състоянието

1. Опростен статус (status)

2. Подробно състояние (substatus)

3. Тип канал (sent_via)

4. Подробно състояние на SMSBAT (hyber_status)