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 адрес.