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

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

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

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

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

Базова URL-адреса: https://restapi.smsbat.com
Кінцева точка: POST /api/SendMessage
Формат запиту: application/x-www-form-urlencoded (дані форми)

Автентифікація та облікові дані

Запити автентифікуються за допомогою параметрів, які надсилаються безпосередньо в даних форми запиту:

Параметр	Тип	Необхідно	Опис
`користувач`	рядок	Так	Ваш обліковий запис SMSBAT або ідентифікатор користувача.
`знак`	рядок	Так	Секрет API або підпис, зареєстрований для імені відправника.
`від`	рядок	Так	Альфа-ім’я зареєстрованого відправника.
`метод_надсилання`	рядок	Так	Тип каналу. Використовуйте `viber` для звичайних повідомлень Viber Business або `viber_otp` для шаблонів Viber OTP.
`телефон`	рядок	Так	Номер телефону одержувача в міжнародному форматі (наприклад, `380501234567`).

Типи повідомлень Viber

Виберіть вкладку нижче, щоб переглянути конкретні параметри та запитати дані для різних структур повідомлень Viber:

Надсилає просте текстове повідомлення.

Додаткові параметри:

Параметр	Тип	Необхідно	Опис
`txt`	рядок	Так	Текст повідомлення.

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

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

Надсилає текстове повідомлення з інтерактивною кнопкою із закликом до дії.

Додаткові параметри:

Параметр	Тип	Необхідно	Опис
`txt`	рядок	Так	Текст повідомлення.
`текст_кнопки`	рядок	Так	Текст, що відображається на кнопці.
`кнопка_посилання`	рядок	Так	Цільова URL-адреса після натискання кнопки.

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

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Надсилає загальнодоступний файл зображення.

Додаткові параметри:

Параметр	Тип	Необхідно	Опис
`посилання_на_зображення`	рядок	Так	Публічна HTTPS URL-адреса зображення.
`txt`	рядок	Ні	Додатковий текст підпису для відображення під зображенням.

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

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png

Надсилає розширену картку з текстом, зображенням і кнопкою.

Додаткові параметри:

Параметр	Тип	Необхідно	Опис
`txt`	рядок	Так	Текст підпису.
`посилання_на_зображення`	рядок	Так	Публічна HTTPS URL-адреса зображення.
`текст_кнопки`	рядок	Так	Текст, що відображається на кнопці.
`кнопка_посилання`	рядок	Так	Цільова URL-адреса після натискання кнопки.

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

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hot+deals+inside%21&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Надсилає відеофайл із додатковим текстовим підписом і кнопками дій.

Додаткові параметри:

Параметр	Тип	Необхідно	Опис
`video.url`	рядок	Так	Публічна URL-адреса HTTPS відеофайлу.
`video.thumbnail`	рядок	Так	Публічна URL-адреса HTTPS зображення попереднього перегляду відео.
`video.size_mb`	ціле	Так	Приблизний розмір відеофайлу в мегабайтах.
`video.duration_sec`	ціле	Так	Тривалість відео в секундах.
`txt`	рядок	Ні	Додатковий текст опису.
`текст_кнопки`	рядок	Ні	Необов’язковий текст кнопки (може виступати як підпис або посилання).
`кнопка_посилання`	рядок	Ні	Додаткова URL-адреса посилання на кнопку.

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

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Додаткові параметри:

| Параметр | Тип | Необхідно | Опис |
| :--- | :--- | :--- | :--- |
| `template.id` | рядок | **Так** | Попередньо затверджений ідентифікатор шаблону Viber OTP. |
| `template.lang` | рядок | **Так** | Код мови шаблону (наприклад, `en`, `uk`). |
| `template.params.pin` | рядок | **Так** | Значення PIN-коду одноразового пароля, яке потрібно додати до шаблону. |
| `template.params.business_platform_name` | рядок | **Так** | Заповнювач назви компанії в шаблоні. |
| `template.params.code_validity_time` | рядок | **Так** | Термін дії PIN-коду в хвилинах. |

**Приклад запиту корисного навантаження:**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber_otp&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&template.id=otp_template_123&template.lang=en&template.params.pin=123456&template.params.business_platform_name=SMSBAT&template.params.code_validity_time=7
```

Надсилає інтерактивну картку повідомлення, що містить кілька слайдів (карток), які користувач може гортати.

Додаткові параметри:

Параметр	Тип	Необхідно	Опис
`txt`	рядок	Так	Текст заголовка каруселі.
`carousel[N].title`	рядок	Так	Заголовок картки `N` (починаючи з 0).
`карусель[N].image_url`	рядок	Так	Загальнодоступна URL-адреса зображення HTTPS картки “N”.
`карусель[N].основна_мітка`	рядок	Так	Підпис головної кнопки картки `N`.
`carousel[N].primary_url`	рядок	Так	URL-адреса посилання на головну кнопку картки `N`.
`carousel[N].secondary_label`	рядок	Ні	Підпис вторинної кнопки картки “N”.
`carousel[N].secondary_url`	рядок	Ні	URL-адреса посилання на вторинну кнопку картки “N”.

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

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2

Надсилає повідомлення, що містить інтерактивне опитування або питання опитування.

Додаткові параметри:

Параметр	Тип	Необхідно	Опис
`txt`	рядок	Так	Текст опитування.
`параметри опитування[N]`	рядок	Так	Текст варіанта опитування для пункту `N` (індекс починається з 0). Потрібно принаймні 2 варіанти.
`тип_опції`	ціле	Так	Тип селектора: `1` (RadioButtons) або `2` (звичайні кнопки).

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

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1

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

Кінцева точка сумісності API Messagio повертає відповіді у форматі XML із кодом статусу «HTTP 200 OK».

Відповідь прийнято (успішно).

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

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

Якщо перевірка параметрів запиту не вдається або автентифікація не вдається, відповідь поверне ненульовий код.

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

Зворотні виклики

URL-адреси зворотного виклику мають бути реалізовані та розміщені на вашій платформі. SMSBAT надсилає зворотні виклики HTTP, щоб оновлювати вашу систему щодо подій доставки, відповідей на опитування та відповідей користувачів.

1. Зворотний дзвінок про статус доставки

Надсилається, коли повідомлення змінює статус (доставлено, прочитано, не вдалося).

Content-Type: application/x-www-form-urlencoded
Метод: POST

Формати запиту корисного навантаження:

Доставлено:
```
msg_id=MESSAGE_GUID&status=delivered
```

Бачив/Прочитав:

msg_id=MESSAGE_GUID&status=delivered&type=seen

Недоставлено / Помилка:

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Опис полів:

msg_id: унікальний ідентифікатор повідомлення SMSBAT (GUID), який повертається у відповіді SendMessage.
статус: результат доставки (доставлено, недоставлено або статус невідомий).
type: установіть значення seen, коли повідомлення переглянуто одержувачем.
status_extended: конкретна технічна причина статусу недоставленого (наприклад, VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Відповідь на опитування

Активується, коли користувач вибирає варіант відповіді в повідомленні Viber Survey.

Content-Type: application/x-www-form-urlencoded
Метод: POST

Формат запиту корисного навантаження:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Зворотний виклик вхідного повідомлення користувача

Активується, коли користувач надсилає текстову або медіа-відповідь вашій службі Viber Business.

Content-Type: application/json
Метод: POST

Формат запиту корисного навантаження:

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

Опис полів:

msg_id: унікальний ідентифікатор повідомлення, згенерований для вхідної відповіді.
text: текстовий вміст, надісланий користувачем (може бути null, якщо він надіслав лише медіа).
media: Пряма URL-адреса для завантаження будь-яких мультимедійних вкладень, надісланих користувачем (може бути null, якщо лише текст).
phone: номер телефону відправника в міжнародному форматі.
sender_bm_id: ідентифікатор відправника Viber Business.

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

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

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

Автентифікація та облікові дані

Типи повідомлень Viber

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

Відповідь прийнято (успішно).

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

Зворотні виклики

1. Зворотний дзвінок про статус доставки

2. Відповідь на опитування

3. Зворотний виклик вхідного повідомлення користувача