Центр допомоги Сумісність GMS API

Сумісність GMS API

SMSBAT підтримує рівень сумісності з GMS API. Це дає змогу перенести ваші існуючі інтеграції, розроблені для GMS, безпосередньо до SMSBAT без необхідності змінювати схеми маршрутизації повідомлень, структури корисного навантаження чи прослуховувачів зворотних викликів.

Параметри підключення

Щоб направляти запити через SMSBAT, оновіть базову URL-адресу та облікові дані автентифікації у вашій інтеграції:

Базова URL-адреса: https://restapi.smsbat.com
Кінцева точка: POST /api/GMSMessage/send_message
Формат запиту: application/json
Автентифікація: Базова автентифікація HTTP (використовує ваші облікові дані SMSBAT API)

Параметри запиту

API сумісності GMS приймає об’єкт JSON із такими параметрами верхнього рівня:

Параметр	Тип	Необхідно	Опис
`номер_телефону`	рядок	Так	Номер телефону одержувача в міжнародному форматі (наприклад, `380501234567`).
`тег`	рядок	Так	Зареєстроване ім’я відправника/альфа-ім’я.
`канали`	масив	Так	Список каналів, які слід спробувати, у порядку пріоритету. Підтримувані значення: `viber`, `sms`, `push`. Наприклад, `["viber", "sms"]`.
`параметри_каналу`	об’єкт	Так	Карта з параметрами для кожного активного каналу (див. нижче).
`extra_id`	рядок	Ні	Ваш внутрішній ідентифікатор повідомлення на стороні клієнта.
`url-адреса_зворотного виклику`	рядок	Ні	URL-адреса кінцевої точки у вашій системі для отримання зворотних викликів про стан доставки.
`код_підрозділу`	рядок	Ні	Додатковий ідентифікатор коду підрозділу (за замовчуванням `main`).

Налаштування параметрів каналу

Об’єкт channel_options містить конфігурації для конкретного каналу.

Використовується, коли viber указано в масиві channels.

Параметр	Тип	Необхідно	Опис
`текст`	рядок	Так	Основний текст повідомлення.
`ttl`	ціле	Так	Термін життя в секундах.
`img`	рядок	Ні	Загальнодоступна URL-адреса HTTPS зображення для відображення.
`підпис`	рядок	Ні	Текстова мітка кнопки.
`дія`	рядок	Ні	Цільова URL-адреса після натискання кнопки.
`параметри опитування`	масив	Ні	Масив рядків (від 2 до 5 елементів) для відображення як параметрів опитування.
`carousel_items`	масив	Ні	Масив об’єктів слайдів для відображення як каруселі Viber (див. структуру на вкладці).

Приклад запиту Viber:

{
  "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 не виконується в межах TTL.

Приклад резервного запиту:

{
  "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 зазначено в масиві channels.

Параметр	Тип	Необхідно	Опис
`текст`	рядок	Так	Основний текст повідомлення.
`alpha_name`	рядок	Так	Альфа-ім’я відправника.
`ttl`	ціле	Так	Термін життя в секундах.
`ctr`	логічний	Ні	Увімкнути відстеження кліків CTR для посилань у тексті (`true`/`false`).

Приклад SMS-запиту:

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

Використовується для створення опитувань та опитувань Viber.

Note

Конфігурація опитування Viber має містити від 2 до 5 параметрів у survey_options.

Приклад запиту на опитування:

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

Використовується, коли push зазначено в масиві channels.

Параметр	Тип	Необхідно	Опис
`назва`	рядок	Так	Текст заголовка push-повідомлення.
`текст`	рядок	Так	Основний текст повідомлення.
`ttl`	ціле	Так	Термін життя в секундах.
`img`	рядок	Ні	Загальнодоступна URL-адреса HTTPS зображення для відображення.
`підпис`	рядок	Ні	Текстова мітка кнопки.
`дія`	рядок	Ні	Цільова URL-адреса після натискання кнопки.
`ctr`	логічний	Ні	Увімкнути відстеження кліків.

Приклад Push-запиту:

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

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

Опис полів зворотного виклику

Поле	Тип	Опис
`число`	рядок	Номер телефону отримувача.
`час`	номер	Мітка часу події в мілісекундах Unix.
`статус`	номер	Спрощений ідентифікатор статусу (див. Таблицю кодів статусу).
`підстатус`	номер	Детальний ідентифікатор статусу (див. Таблицю кодів підстанусу).
`hyber_status`	номер	Детальний внутрішній код статусу SMSBAT (див. таблицю стану Hyber).
`id_повідомлення`	рядок	Ідентифікатор повідомлення SMSBAT (GUID), створений під час надсилання.
`extra_id`	рядок	Ідентифікатор клієнта, указаний у вихідному запиті.
`sent_via`	рядок	Канал, який обробив повідомлення: `viber`, `sms` або `rcs`.
`відповідний_ідентифікатор_шаблону`	номер	Статус відповідності шаблону Viber (якщо застосовно).

Відображення статусу

1. Спрощений статус (`статус`)

Код	Значення
`1`	Повідомлення прийнято або доставляється.
`2`	Повідомлення доставлено.
`3`	Помилка обробки або доставки.

2. Детальний статус (`підстатус`)

Код	Значення
`12`	Прийнято в переробку.
`23`	Доставлено.
`24`	Бачив/прочитав.
`35`	Не доставлено протягом TTL (термін дії минув).
`36`	Помилка доставки.

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

Канал	Опис
`viber`	Статус створений каналом Viber.
`sms`	Статус, вироблений SMS-каналом.
`rcs`	Статус створено каналом RCS.

4. Детальний статус SMSBAT (`hyber_status`)

Код	Канал	Статус	Підстатус	Значення
23033	`viber`	`2`	`23`	Повідомлення Viber доставлено.
24013	`viber`	`2`	`24`	Повідомлення Viber прочитано одержувачем (Seen).
36013	`viber`	`3`	`36`	Внутрішня помилка Viber.
36023	`viber`	`3`	`36`	Недійсний або недоступний ID служби Viber.
36033	`viber`	`3`	`36`	Недійсні дані Viber.
36037	`viber`	`3`	`36`	URL-адреса зображення Viber задовга.
36038	`viber`	`3`	`36`	Недійсна URL-адреса зображення Viber.
36039	`viber`	`3`	`36`	Текст Viber задовгий.
36044	`viber`	`3`	`36`	Порожній текст Viber.
36053	`viber`	`3`	`36`	Непідтримуваний тип повідомлення Viber.
36063	`viber`	`3`	`36`	Недійсні параметри Viber.
36073	`viber`	`3`	`36`	Тайм-аут провайдера Viber.
36083	`viber`	`3`	`36`	Відправник Viber заблокований одержувачем.
36093	`viber`	`3`	`36`	Одержувач не зареєстрований як користувач Viber.
36103	`viber`	`3`	`36`	Пристроїв Android/iOS із підтримкою Viber не знайдено.
36113	`viber`	`3`	`36`	Неавторизована IP-адреса для надсилання Viber.
36123	`viber`	`3`	`36`	Виявлено дублікат повідомлення Viber.
36143	`viber`	`3`	`36`	Помилка оплати Viber.
36153	`viber`	`3`	`36`	Повідомлення заблоковано в чорному списку платформи.
36163	`viber`	`3`	`36`	Внутрішня помилка обробки платформи Viber.
36173	`viber`	`3`	`36`	Неправильна або відсутня мітка Viber.
36183	`viber`	`3`	`36`	Недійсне значення TTL Viber.
12011	`sms` / `rcs`	`1`	`12`	Приймаються SMS/RCS.
36011	`sms` / `rcs`	`1`	`12`	SMS/RCS в дорозі.
23011	`sms` / `rcs`	`2`	`23`	SMS/RCS доставлено.
35015	`sms` / `rcs`	`3`	`35`	Термін дії SMS/RCS закінчився (не доставлено протягом TTL).
36021	`sms` / `rcs`	`3`	`36`	SMS/RCS повідомлення видалено.
36031	`sms` / `rcs`	`3`	`36`	Неможливо доставити SMS/RCS.
36041	`sms` / `rcs`	`3`	`36`	Невідомий статус доставки SMS/RCS.
36051	`sms` / `rcs`	`3`	`36`	SMS/RCS повідомлення відхилено.

Результати пошуку

Сумісність GMS API

Параметри підключення

Параметри запиту

Налаштування параметрів каналу

Формат відповіді

Успішна відповідь

Відповіді на помилки

Формат доставки зворотного виклику

Приклад запиту зворотного виклику

Опис полів зворотного виклику

Відображення статусу

1. Спрощений статус (статус)

2. Детальний статус (підстатус)

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

4. Детальний статус SMSBAT (hyber_status)

1. Спрощений статус (`статус`)

2. Детальний статус (`підстатус`)

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

4. Детальний статус SMSBAT (`hyber_status`)