Две полезные нагрузки webhook несут события сообщений. Событие статуса доставки (DLR) сообщает об исходе сообщения — message_id, enum статуса (accepted, delivered, undelivered, expired, rejected), причину ошибки и метки времени. Событие входящего (MO) сообщает о сообщении, которое абонент отправил вам. Оба являются HTTP-эквивалентами отчётов о доставке deliver_sm SMPP и сообщений mobile-originated.
- Ваше приложениеОтправка через REST API или SMPP
- Платформа BroadNetВалидация, маршрутизация и тарификация каждого сообщения
- SMSC оператораПрямое соединение с оператором
- Телефон абонентаСообщение доставлено
Два семейства событий: статус и входящие
Платформа сообщений выдаёт два принципиально разных callback. Событие статуса доставки (DLR, отчёт о доставке) — это асинхронное продолжение отправленного вами сообщения: оно говорит, что в итоге с ним произошло в сети оператора. Событие входящего (MO, mobile-originated) — незапрошенное: сообщение, отправленное абонентом на один из ваших номеров, или ответ на кампанию. Они разделяют транспорт webhook и подпись, но их схемы и смысл различаются, поэтому надёжный потребитель ветвится по дискриминатору типа события перед разбором остального. Оба — это HTTP-выражение того, что SMPP доставляет как PDU deliver_sm: на уровне провода флаг отчёта о доставке отличает DLR от MO, и то же различие на HTTP является явным полем события.
Полезная нагрузка статуса доставки (DLR)
Полезная нагрузка статуса доставки соотносится с исходной отправкой по назначенному сервером message_id и сообщает статус, взятый из небольшого перечисления, плюс причину и метки времени, которые позволяют измерить задержку и сверить биллинг. Enum статуса — его сердце: он отличает промежуточное состояние accepted/enroute от терминальных состояний и отделяет положительное delivered от нескольких способов, которыми сообщение может отказать. Терминальные отрицательные состояния несут код ошибки и человекочитаемую причину, чтобы потребитель мог решить, постоянно ли плох получатель (подавить его) или сбой был временным (безопасно переотправить). Метки времени обычно включают момент, когда платформа приняла сообщение, и момент, когда наступил терминальный статус.
{
"event": "message.delivered",
"message_id": "01HZY8Q3M6",
"to": "+15551234567",
"status": "delivered",
"error": null,
"reason": null,
"submitted_at": "2026-07-19T09:15:22Z",
"done_at": "2026-07-19T09:15:25Z",
"sequence": 3
}Перечисление статусов доставки
Стандартизация значений статуса — это то, что позволяет одному потребителю обрабатывать каждого оператора, поскольку сырые сетевые ответы сильно различаются. Канонический enum отображает их на горстку состояний с ясной семантикой: терминально ли состояние и является ли оно успехом. Промежуточные состояния (accepted, enroute) могут быть вытеснены более поздним событием для того же message id, что и есть причина, по которой полезные нагрузки несут sequence или метку времени и по которой потребители применяют правило самоупорядочивания из надёжности webhook — позднее accepted никогда не должно перезаписывать более раннее delivered.
| status | Терминал | Значение |
|---|---|---|
| accepted | No | Платформа приняла сообщение к доставке |
| enroute | No | Передано оператору, ожидается отчёт о доставке |
| delivered | Да | Подтверждена доставка на телефон |
| undelivered | Да | Оператор не смог доставить (см. ошибку/причину) |
| expired | Да | Срок действия истек до доставки |
| rejected | Да | Отклонено (неверный номер, заблокирован отправитель, спам-фильтр) |
| unknown | Да | Оператор не вернул окончательного состояния |
Полезная нагрузка входящего (MO) сообщения
Событие входящего несёт содержимое сообщения плюс маршрутизацию, необходимую для ответа и для сопоставления диалога. Критические поля — from (MSISDN абонента в формате E.164), to (номер или короткий/длинный код, на который он написал) и text; рядом с ними — message id самого входящего сообщения, метка времени получения и — поскольку входящие SMS подчиняются тем же правилам кодирования и сегментации, что и исходящие, — encoding и, для многочастного сообщения, референс конкатенации и индексы частей, чтобы потребитель мог собрать полный текст. Входящие события — это то, чем управляются кампании с ключевыми словами, двусторонние диалоги и потоки соответствия STOP/HELP.
{
"event": "message.inbound",
"message_id": "01HZY8R7T0",
"from": "+15551234567",
"to": "44160",
"text": "STOP",
"encoding": "GSM7",
"received_at": "2026-07-19T09:20:11Z",
"concat": { "ref": null, "part": 1, "total": 1 }
}Таксономия типов событий
Помимо DLR и MO платформа выдаёт события жизненного цикла и аккаунта, и последовательная схема именования — строка resource.action через точку — позволяет потребителю подписываться на них и маршрутизировать их чисто. События статуса доставки — это вариации message.<status>; событие входящего — message.inbound. Группировка по префиксу ресурса означает, что потребитель может сопоставлять message.* для всего, что касается сообщения, и резервировать другие префиксы для событий аккаунта или номеров. Каждое событие также должно нести стабильный event id (используемый как nonce подписи и ключ дедупликации) и строку типа, чтобы дискриминатор и ключ идемпотентности всегда присутствовали.
| Тип события | Семейство | Срабатывает, когда |
|---|---|---|
| message.accepted | Статус (DLR) | Сообщение принято к доставке |
| message.delivered | Статус (DLR) | Доставка на телефон подтверждена |
| message.undelivered | Статус (DLR) | Оператор не выполнил доставку |
| message.expired | Статус (DLR) | Срок действия истек |
| message.rejected | Статус (DLR) | Сообщение отклонено на вышестоящем узле |
| message.inbound | Входящие (MO) | Абонент отправил вам сообщение |
Отображение HTTP-DLR на SMPP deliver_sm
HTTP-callback статуса доставки и отчёт о доставке SMPP — это одна и та же информация в двух кодировках, и платформа, мостящая REST и SMPP, транслирует между ними. В SMPP отчёт о доставке приходит как PDU deliver_sm, чей esm_class помечает его как отчёт о доставке; поле short-message несёт текстовый отчёт с полями id, stat и err, а TLV message_state несёт числовое состояние. HTTP-DLR поднимает их в JSON: токен stat из SMPP отображается на канонический enum статуса, значение err — на поле error, а времена submit/done отчёта — на submitted_at/done_at. Понимание этого отображения — то, что позволяет одному пути обработки доставки обслуживать оба транспорта; формат отчёта о доставке SMPP и PDU deliver_sm подробно задокументированы в справочнике SMPP.
| Поле отчёта SMPP | Поле HTTP DLR | Примечание |
|---|---|---|
| id (отчёт) | message_id | Соответствует исходному submit_sm / POST |
| stat (DELIVRD/UNDELIV/EXPIRED/REJECTD) | status | Токен соответствует каноническому перечислению |
| err | error | Код ошибки оператора/сети |
| message_state TLV | status (числовое представление) | Числовое состояние SMPP, стоящее за токеном |
| дата отправки / дата завершения | submitted_at / done_at | Временные метки задержки и согласования |
Часто задаваемые вопросы
Что содержит полезная нагрузка webhook статуса доставки (DLR)?
Назначенный сервером message_id, соотносящий её с вашей отправкой, статус из канонического enum (accepted, enroute, delivered, undelivered, expired, rejected, unknown), код ошибки и человекочитаемую причину для сбоев, а также метки времени того, когда сообщение было отправлено и когда наступил терминальный статус.
Чем событие входящего (MO) отличается от DLR?
DLR — это асинхронный исход отправленного вами сообщения. Событие входящего (MO) незапрошено — это сообщение, отправленное абонентом на ваш номер, или ответ на кампанию, — несущее from, to, text, encoding и, для многочастных сообщений, поля конкатенации. Они разделяют транспорт и подпись, но имеют разные схемы, поэтому потребители сначала ветвятся по типу события.
Зачем стандартизировать enum статуса доставки?
Потому что сырые ответы операторов колоссально различаются. Отображение их на небольшой канонический enum с ясной семантикой терминальности и успеха позволяет одному потребителю единообразно обрабатывать каждого оператора и решать по одному лишь статусу, подавить ли плохого получателя, переотправить временный сбой или зафиксировать подтверждённую доставку.
Как не дать позднему «accepted» перезаписать более раннее «delivered»?
Используйте поля самоупорядочивания. Полезные нагрузки DLR несут метку времени и часто номер последовательности; потребитель сравнивает их с последним состоянием, записанным для этого message id, и отбрасывает любое событие старше того, что у него уже есть, — так промежуточное состояние вне порядка никогда не затрёт терминальное.
Как HTTP-DLR отображается на отчёт о доставке SMPP deliver_sm?
Они несут одну и ту же информацию. В SMPP отчёт о доставке — это PDU deliver_sm, помеченный в esm_class, с полями id, stat и err и TLV message_state. HTTP-DLR отображает stat на enum статуса, err на error, а метки времени отчёта на submitted_at/done_at — так один путь обработки доставки может обслуживать оба транспорта.
Какие поля позволяют собрать многочастное входящее SMS?
Поля конкатенации: референс, связывающий части вместе, индекс части и общее число. Поскольку входящие SMS подчиняются тем же правилам кодирования и сегментации, что и исходящие, длинное входящее сообщение приходит как несколько событий MO, которые потребитель сшивает по порядку с помощью этих полей.
Технические характеристики источника
На этой странице представлены опубликованные стандарты, на которых они основаны. (Открывается в новой вкладке)