Callback-сповіщення
Шлюз самостійно надсилає події на ваш сервер. Адреса береться з поля URL/Email для повідомлення про статуси SMS у налаштуваннях API або з адреси сповіщень вашого виділеного номера.
На цій сторінці описані callback-сповіщення HTTP та XML API. Вони не замінюють JSON вебхук: повідомлення, надіслане через JSON API з параметром hook, породжує обидва сповіщення — JSON вебхук на адресу з hook і звіт про доставку нижче на адресу з налаштувань.
Вхідне SMS
Надсилається, коли абонент надсилає SMS на ваш виділений номер.
HTTP метод: POST
Content-Type: multipart/form-data
| Параметр | Тип | Опис |
|---|---|---|
id | number | Ідентифікатор повідомлення, присвоєний шлюзом |
message | string | Текст повідомлення в тому вигляді, в якому його отримано від абонента |
phone | string | Номер телефону абонента |
short_phone | string | Ваш виділений номер, на який надіслано повідомлення |
test | number | 1 — тестове повідомлення, не тарифікується; 0 — реальне повідомлення |
timestamp | number | Unix-час отримання повідомлення |
password | string | md5(api_key). Використовуйте для перевірки того, що запит надійшов від шлюзу |
Приклад запиту
id=1234567&message=INFO%20123&phone=380501234567&short_phone=7060&test=0×tamp=1755772800&password=5f4dcc3b5aa765d61d8327deb882cf99
Відповідь
Тіло вашої відповіді надсилається абоненту у відповідь SMS.
| Ваша відповідь | Що отримає абонент |
|---|---|
Тіло від 1 до 200 символів без тега <html> | Тіло вашої відповіді |
Порожнє тіло, довше за 200 символів або містить тег <html> | Відповідь за замовчуванням, налаштована для виділеного номера |
Таймаути: 5 секунд на з'єднання, 20 секунд сумарно.
Для окремого виділеного номера замість password може бути узгоджено параметр signature. Він розраховується як sha1(значення всіх параметрів, відсортованих за іменем параметра та склеєних поспіль + api_key).
Відповідь Viber 2 Way
Надсилається, коли абонент відповідає на ваше Viber-повідомлення.
Це сповіщення використовується тільки для повідомлень, надісланих не через JSON API. Для повідомлень JSON API відповідь надходить у масиві replies JSON вебхука.
HTTP метод: POST
Content-Type: application/x-www-form-urlencoded
| Параметр | Тип | Опис |
|---|---|---|
action | string | Завжди viber/2way |
sender | string | Ім'я відправника, на яке відповів абонент |
phone | string | Номер телефону абонента |
message | string | Текст відповіді |
datetime | string | Дата і час відповіді Формат: YYYY-MM-DDThh:mm:ss±hh:mm |
Приклад запиту
action=viber%2F2way&sender=SMSTest&phone=380501234567&message=Yes&datetime=2026-08-19T12%3A55%3A39%2B03%3A00
Відповідь
У відповіді буде отримано код 200. Тіло відповіді ігнорується.
Сповіщення не містить ідентифікатора повідомлення — зіставляйте відповідь із повідомленням за phone та sender. Медіафайли, прикріплені до відповіді, цим сповіщенням не передаються, вони доступні тільки в JSON вебхуку.
Таймаути: 5 секунд на з'єднання, 5 секунд сумарно. Запит надсилається один раз, без повторів — що б не відповів ваш сервер, відповідь абонента повторно не надійде. Повтори, описані нижче, стосуються звіту про доставку і на це сповіщення не поширюються.
Звіт про доставку на URL
Надсилається при кожній зміні статусу повідомлення. На відміну від callback-сповіщень вище, цей звіт іде по кожному повідомленню акаунта, яким би API воно не було надіслане — HTTP, XML чи JSON.
HTTP метод: POST
Content-Type: application/x-www-form-urlencoded
| Параметр | Тип | Опис |
|---|---|---|
id | number | Ідентифікатор повідомлення, присвоєний шлюзом |
status | number | Код статусу повідомлення. Перелік значень — Коди статусів повідомлення |
datetime | string | Дата і час зміни статусу Формат: YYYY-MM-DDThh:mm:ss±hhmm |
api_key | string | Ваш API ключ. За ним можна переконатися, що запит прийшов від шлюзу |
parts | number | Кількість частин, на які розбито повідомлення |
price | number | Вартість відправки |
user_id | string | Унікальний ідентифікатор повідомлення у вашій системі ⚠️ Присутній, тільки якщо був переданий при відправці |
Приклад запиту
id=1234567&status=101&datetime=2026-08-21T10%3A12%3A33%2B0300&api_key=bb56a4369eb19***cfec6d1776bd25&parts=1&price=0.35&user_id=100500
Відповідь
Від вашого сервера очікується відповідь із кодом 200, тіло відповіді ігнорується. Успіхом вважається строго цей код — будь-яка інша відповідь записується як невдача.
Таймаути: 5 секунд на з'єднання, 5 секунд сумарно. До трьох спроб: повтори через 10 і 60 секунд після невдачі і лише при обриві зв'язку, таймауті, 5xx або 429 — будь-яка інша відповідь, включно з 4xx, вважається остаточною. Обробник робіть ідемпотентним: один і той самий статус може прийти повторно.
Звіт про доставку на e-mail
Якщо в полі сповіщень указано адресу електронної пошти замість URL, звіт про доставку надсилається не по HTTP, а листом на цю адресу з темою SMS delivery report.
У тілі листа перелічені поля звіту, по одному в рядку, у форматі параметр: значення.
| Параметр | Опис |
|---|---|
id | Ідентифікатор повідомлення, присвоєний шлюзом |
status | Код статусу повідомлення |
datetime | Дата і час зміни статусу Формат: YYYY-MM-DDThh:mm:ss±hhmm |
parts | Кількість частин, на які розбито повідомлення |
price | Вартість відправки |
api_key | Ваш API ключ |
user_id | Унікальний ідентифікатор повідомлення у вашій системі ⚠️ Присутній, тільки якщо був переданий при відправці |
Приклад листа
id: 1234567
status: 101
datetime: 2026-08-21T10:12:33+0300
api_key: bb56a4369eb19***cfec6d1776bd25
parts: 1
price: 0.35
user_id: 100500
Звіт на e-mail не підходить для автоматичної обробки — у нього немає підпису, а доставка листа не гарантується. Для інтеграції вказуйте HTTP адресу.