SMS API

Отправка SMS-сообщений

Про процедуру аутентификации и авторизации, которые связывают вызовы API с необходимыми приложениями в Вашей учетной записи см. Авторизация.

Запрос:

Параметры можно передавать в заголовке запроса:

POST/GET https://api.unibell.ru/v2/sms?X-Authorization=AccessKey d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX&sourceAddr=MySender&shortMessage=Текст сообщения&ttl=1000

А также в теле запроса:

{
    "sourceAddr": "MySender",
    "destAddr": "7XXXXXXXXXX",
    "shortMessage": "Текст сообщения",
    "ttl": 1000
}

Пример запроса с использованием CURL:

curl --location --request POST 'https://api.unibell.ru/v2/sms?X-Authorization=AccessKey%20d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX&sourceAddr=MySender&shortMessage=Текст сообщения&ttl=1000'

curl --location --request GET 'https://api.unibell.ru/v2/sms' \
--header 'Content-Type: application/json' \
--data '{
    "sourceAddr": "MySender",
    "destAddr": "7XXXXXXXXXX",
    "shortMessage": "Текст сообщения"
}'

Параметр	Тип	Описание
sourceAddr	string	Имя отправителя (только латиница или номер телефона) *Поле не должно содержать кириллицы*
destAddr	string	Номер телефона, на который отправляется SMS-сообщение в формате e.164, например, для Российской Федерации 7XXXXXXXXXX
shortMessage	string	Текст сообщения

Ответ при успешном выполнении запроса:

{
    "status": "Created",
    "requestId": "11273"
}

Ответ в случае отсутствия destAddr:

{
    "status": "Rejected",
    "error": "Missing destAddr param"
}

Параметр	Тип	Описание
status	string	Статус запроса: _{Created — Сообщение в системе создано, но ещё не отправлено Rejected — Сообщение не было принято к отправке, уточнение ошибки в error prohibitedForServiceError — Ключ не принадлежит услуге SMS invalidAccessKeyError — Ошибка в ключе авторизации} _{accountFinanciallyBlocked — Контрагент заблокирован по балансу/Блокировка по IP адресу} _{unexpectedDataValue — Ошибка в значении TTL}
requestId	string	Уникальный идентификатор запроса
error	string	Описание ошибок: _{Missing destAddr param — destAddr отсутствует в запросе Missing sourceAddr param — sourceAddr отсутствует в запросе Missing shortMessage param — shortMessage отсутствует в запросе Field sourceAddr must not contain Cyrillic — в sourceAddr присутствует кириллица Field ttl must be an integer — Поле ttl должно быть целым числом Field ttl must be in range 1 — 86400 — Поле ttl должно находиться в диапазоне от 1 до 86400}

Массовая отправка SMS-сообщений

Запрос:

POST https://api.unibell.ru/v2/sms_bulk?X-Authorization=AccessKey d8ac9959r12b43545XXXXX

Тело запроса:

{
    "sourceAddr": "MySender",
    "destAddrs": [
        "79123213232",
        "2вауц",
        "71233212323"
    ],
    "shortMessage": "Текст сообщения"
}

Пример запроса с использованием CURL:

curl --location 'https://api.unibell.ru/v2/sms_bulk' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "sourceAddr": "MySender",
    "destAddrs": [
        "79123213232",
        "2вауц",
        "71233212323"
    ],
    "shortMessage": "Текст сообщения"
}'

Параметр	Тип	Описание
sourceAddr	string	Имя отправителя *Поле не должно содержать кириллицы*
destAddrs	string	Список телефонных номеров, на которые отправляются SMS-сообщения в формате e.164, например, для Российской Федерации 7XXXXXXXXXX
shortMessage	string	Текст сообщения

Тело ответа при выполнении запроса:

{
    "status": "ok",
    "results": [
        {
            "status": "Created",
            "requestId": "11276",
            "destAddr": "79123213232"
        },
        {
            "status": "Rejected",
            "error": "Not valid destAddr",
            "destAddr": "2вауц"
        },
        {
            "status": "Created",
            "requestId": "11277",
            "destAddr": "71233212323"
        }
    ]
}

Параметр	Тип	Описание
status	string	Статус запроса: _{Created — Сообщение в системе создано, но ещё не отправлено Enroute — Сообщение смаршрутизировано и ожидает отправки Delivered — Сообщение доставлено, получен статус доставки от оператора Expired — Истекло время жизни сообщения Deleted — Сообщение было отменено Undeliverable — Сообщение не доставлено по причине: номер не существует, нет места для новых СМС в телефоне Accepted — Сообщение отправлено, статус доставки от оператора ещё не получен Unknown — Неизвестная ошибка Rejected — Сообщение не было принято к отправке, уточнение ошибки в error prohibitedForServiceError — Ключ не принадлежит услуге SMS invalidAccessKeyError — Ошибка в ключе авторизации} _{accountFinanciallyBlocked — Контрагент заблокирован по балансу/Блокировка по IP адресу}
results	string	Результаты по каждому получателю
error	string	Описание ошибки: _{Missing destAddr param — destAddr отсутствует в запросе Missing sourceAddr param — sourceAddr отсутствует в запросе Missing shortMessage param — shortMessage отсутствует в запросе Field sourceAddr must not contain Cyrillic — в sourceAddr присутствует кириллица Not valid destAddr — Неправильно введен destAddr}
requestId	string	Уникальный идентификатор запроса
destAddr	string	Номер телефона, на который отправляется SMS-сообщение в формате e.164, например, для Российской Федерации 7XXXXXXXXXX

Получение статуса

Запрос:

Параметры можно передавать в заголовке запроса:

GET https://api.unibell.ru/v2/sms_status?X-Authorization=AccessKey d8ac9959r12b43545XXXXX&requestId=11273

А также в теле запроса:

{
    "requestId": "11273"
}

Пример запросов с использованием CURL:

curl --location 'https://api.unibell.ru/v2/sms_status' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'requestId: 11273'

curl --location --request GET 'https://api.unibell.ru/v2/sms_status' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "requestId": "11273"
}'

Тело ответа при успешном выполнении запроса:

{
    "id": 9654,
    "destAddr": "7XXXXXXXXXX",
    "requestId": "11273",
    "status": "Rejected",
    "networkErrCode": 34,
    "mcc": 0,
    "mnc": 0,
    "ported": 0
}

Ответ в случае отсутствия параметра requestId:

{
    "status": "Rejected",
    "error": "Missing requestId param"
}

Параметр	Тип	Описание
id	integer	Уникальный идентификатор SMS-сообщения
destAddr	string	Номер телефона, на который было отправлено SMS-сообщение в формате e.164, например, для Российской Федерации 7XXXXXXXXXX
requestId	string	Уникальный идентификатор запроса
status	string	Статус запроса отправки SMS-сообщения: _{Created — Сообщение в системе создано, но ещё не отправлено Enroute — Сообщение смаршрутизировано и ожидает отправки Delivered — Сообщение доставлено, получен статус доставки от оператора Expired — Истекло время жизни сообщения Deleted — Сообщение было отменено Undeliverable — Сообщение не доставлено по причине: номер не существует, нет места для новых СМС в телефоне Accepted — Сообщение отправлено, статус доставки от оператора ещё не получен Unknown — Неизвестная ошибка Rejected — Мобильная сеть отклонила сообщение, скорее всего из-за фильтра или другого ограничения notFound — Запись по запрошенному requestId отсутствует/не найдена}
networkErrCode	string	Ошибки SS7, смотрите ниже
mcc	integer	Mobile Country Code – код страны
mnc	integer	Mobile Network Code – код мобильного оператора
ported	integer	Информация о том, был ли портирован номер: _{1 — если номер был портирован 0 — если не был портирован}
error	string	Описание ошибок: _{Missing requestId param — отсутсвтует requestId в запросе}

Получение статусов сообщений на Webhook

Источник запросов:

Webhook будут приходить с IP-адресов 185.175.44.211 и 46.148.235.62, которые необходимо включить в ACL на стороне веб-сервера клиента для обеспечения корректного взаимодействия.

Формат взаимодействия:

Обратные вызовы выполняются по протоколу HTTP.

Данные передаются в формате JSON.

Настройка Webhook происходит по запросу в техническую поддержку.

Отправка запроса:

Запрос отправляется в формате JSON, который имеет следующую структуру:

{
  "ported": 0,
  "mnc": 0,
  "requestId": "35714061",
  "destAddr": "7XXXXXXXXXX",
  "id": 639073386,
  "networkErrCode": 0,
  "mcc": 0,
  "status": "Delivered"
}

Параметр	Тип	Описание
ported	integer	Информация о том, был ли портирован номер: _{1 — если номер был портирован 0 — если не был портирован}
mnc	integer	Mobile Network Code – код мобильного оператора
requestId	string	Уникальный идентификатор запроса
destAddr	string	Номер телефона, на который отправляется SMS-сообщение в формате e.164, например, для Российской Федерации 7XXXXXXXXXX
id	integer	Уникальный идентификатор SMS-сообщения
networkErrCode	string	Ошибки SS7, смотрите ниже
mcc	integer	Mobile Country Code – код страны
status	string	Статус запроса отправки SMS-сообщения: _{Created — Сообщение в системе создано, но ещё не отправлено Enroute — Сообщение смаршрутизировано и ожидает отправки Delivered — Сообщение доставлено, получен статус доставки от оператора Expired — Истекло время жизни сообщения Deleted — Сообщение было отменено Undeliverable — Сообщение не доставлено по причине: номер не существует, нет места для новых СМС в телефоне Accepted — Сообщение отправлено, статус доставки от оператора ещё не получен Unknown — Неизвестная ошибка Rejected — Сообщение не было принято к отправке, уточнение ошибки в error}

Отправка FlashCall запросов

Запрос:

Параметры передаются в заголовке запроса:

POST/GET https://api.unibell.ru/v2/sms?X-Authorization=AccessKey d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX&sourceAddr=FlashCall&shortMessage=7341

Пример запроса с использованием CURL:

curl --location --request POST 'https://api.unibell.ru/sms_new?X-Authorization=AccessKey%d8ac9959r12b43545XXXXX&destAddr=&sourceAddr=FlashCall&shortMessage=7341'

Параметр	Тип	Описание
sourceAddr	string	Указывается метод отправления FlashingCall *Поле не должно содержать кириллицы*
destAddr	string	Номер телефона, на который отправляется FlashCall запрос в формате e.164, например, для Российской Федерации 7XXXXXXXXXX
shortMessage	string	Код сообщения

Ответ при успешном выполнении запроса:

{
    "status": "ok",
    "requestId": "eaa26d85f7c5571bd9d62004a9e6396e"
}

Ответ в случае отсутствия destAddr:

{
    "status": "invalidDataError",
    "error": "Missing destAddr param"
}

Параметр	Тип	Описание
status	string	Статус запроса: _{Created — Сообщение в системе создано, но ещё не отправлено Rejected — Сообщение не было принято к отправке, уточнение ошибки в error prohibitedForServiceError — Ключ не принадлежит услуге SMS invalidAccessKeyError — Ошибка в ключе авторизации} _{accountFinanciallyBlocked — Контрагент заблокирован по балансу/Блокировка по IP адресу}
requestId	string	Уникальный идентификатор запроса
error	string	Описание ошибок: _{Missing destAddr param — destAddr отсутствует в запросе Missing sourceAddr param — sourceAddr отсутствует в запросе Missing shortMessage param — shortMessage отсутствует в запросе Field sourceAddr must not contain Cyrillic — в sourceAddr присутствует кириллица}

Вы также можете получить статусты доставки FlashCall по API (подробнее см. Получение статуса).

Коды ошибок в статусе

Возможные коды ошибок в статусе SMS (значения networkErrCode).

Все неуказанные коды считаются зависящими от поставщика и не обрабатываются отдельно.

Код	Расшифровка	Описание
1	unknownSubscriber	Неизвестный абонент _{Абонент не зарегистрирован в сети}
5	unidentifiedSubscriber	Неопознанный абонент _{Абонент зарегистрирован, но информация о нем отсутствует или недоступна}
9	illegalSubscriber	Незаконный абонент _{Абоненту отказано в доступе из-за нарушения правил}
11	teleserviceNotProvisioned	Телекоммуникационная услуга не представлена _{Абонент не подключен к запрашиваемой услуге}
13	callBarred	Запрещенный вызов _{Запрет на вызов для данного абонента (например, из-за блокировки или ограничений тарифа)}
21	facilityNotSupported	Услуга не поддерживается _{Запрошенная услуга недоступна для абонента или сети}
27	adsentSubscriber	Адрес отправителя отсутствует _{Сообщение не доставлено из-за отсутствия данных об отправителе}
31	subscriberBusyForMT-SMS	Абонент занят для получения MT-SMS _{Абонент не может принять SMS из-за занятости устройства}
32	sm-DeliverFailure	Ошибка доставки SMS _{Общая ошибка, связанная с передачей SMS}
33	messageWaitingListFull	Список ожидания сообщений переполнен _{В памяти устройства абонента нет места для новых сообщений}
34	systemFailure	Системная ошибка _{Общая ошибка на стороне сети}
35	dataMissing	Отсутствуют данные _{Не хватает информации для выполнения операции}
36	unexpectedDataValue	Неожиданное значение данных _{Переданы некорректные или неожиданные данные}

Коды ошибок SMS

Код	Название	Описание
0	No error	Ошибок нет Абонент существует и доступен
1	Unknown subscriber	Номер телефона абонента не существует, неактивен или более не используется
2	Unknown subscriber – NR Changed	Ошибка переноса номера (Number Portability). Может возникать при многократном переносе номера
5	Unidentified subscriber	MSC не распознает IMSI абонента. Возможные причины: HLR не обновлен или сбой MSC
6	Absent subscriber for SMS	Устройство абонента недоступно для получения SMS (телефон выключен или вне зоны действия сети)
7	Unknown equipment	Сообщение отклонено, так как устройство абонента не идентифицировано
8	Roaming not allowed	Сообщение отклонено из-за ошибки аутентификации или фильтрации при роуминге
9	Illegal subscriber	Сообщение отклонено из-за ошибки аутентификации или фильтрации
10	Bearer Service not provisioned	Подписка абонента не поддерживает SMS
11	Teleservice not provisioned	Абонент не может принимать SMS. Причины: услуга не подключена, абонент в роуминге без активации SMS или оператор не налажал обмен SMS
12	Illegal equipment	Сообщение не доставлено из-за ошибки в телефоне абонента или SIM-карте; устройство или сеть не поддерживают SMS
13	Call barred	Абонент заблокирован: нулевой/отрицательный баланс, блокировка оператором, поврежденная SIM-карта, или неправильный PIN/PUK
21	Facility not supported	Подписка или устройство абонента не поддерживают работу с SMS-сервисом
27	Absent subscriber	Устройство абонента не зарегистрировано в сети (выключено или вне зоны покрытия)
28	Incompatible MS terminal error	Функция SMS не поддерживается мобильным устройством абонента
31	Subscriber busy for SM MT	Устройство абонента временно недоступно для доставки SMS
32	Equipment failure	Принимающее устройство не поддерживает SMS или соответствующую функцию
33	MS memory capacity exceeded	Принимающее устройство не имеет достаточной памяти для получения сообщения
34	GSM system failure	MSC отклонил сообщение из-за сбоя протокола SS7 или сетевой ошибки
35	GSM Data Error – data missing	Отсутствуют данные GSM
36	GSM Data Error	Некорректные данные GSM
45	Subscriber busy	Абонент в данный момент не может выполнять GSM-операции
100	RejectedByIpBlockedException	Блокировка по IP адресу
101	RejectedByFinBlockedException	Финансовая блокировка
102	SmsTemplateRejectedException	Шаблон сообщения не найден
500	Invalid destination address	Некорректный номер получателя
501-506	Routing error	Ошибка маршрутизации
507	SystemFailure	Общий системный сбой
508	ThrottledException	Превышен лимит запросов или сообщений (ограничение скорости/rate limit)
509	Invalid parameter length	Некорректная длина сообщения или параметра
510	Invalid destination address	Некорректный адрес получателя (destination address)
511	Loop detection error	Обнаружена петля маршрутизации (циклическая отправка)
512	Invalid source address	Некорректный адрес отправителя (source address)
513	System error	Внутренняя ошибка системы
999	Unspecified error	Неопределенная ошибка (общий код без уточнения причины)

На этой странице