Запрос на отправку SMS#

Примеры запросов#

 1 {
 2     "messages": [
 3         {
 4             "from": "MyCompany",
 5             "to": "79034567890",
 6             "text": "Code: 1234"
 7         },
 8         {
 9             "from": "TAXI",
10             "to": " 89034567890",
11             "text": "Code: 1234"
12         }
13     ]
14 }

Параметры запроса#

Обязательные параметры выделены полужирным шрифтом.

Параметр

Тип

Описание

shortenUrl

boolean
Флаг, который сокращает длину ссылки: если true, то ссылка будет сокращена.
По умолчанию: false.

Примечание

Значение параметра применяется для всех SMS-сообщений переданного пакета.

По умолчанию опция недоступна. Для подключения данной опции следует обратиться в Службу технической поддержки.

scheduleInfo

object

Расписание рассылки. Если расписание не указано, сообщения отправляются сразу же, в момент получения запроса.

scheduleInfo/timeBegin

string

Время начала рассылки в формате ЧЧ:ММ, например, «10:00».

scheduleInfo/timeEnd

string

Время окончания рассылки в формате ЧЧ:ММ, например, «21:00».

scheduleInfo/weekdaysSchedule

string

Дни рассылки. Задаются цифрами от 1 (понедельник) до 7 (воскресение), например, «12345».

Если ограничений по дням недели нет, то данный параметр может быть пустым или не передан в запросе.

scheduleInfo/deadline

string

Дата окончания рассылки в формате «YYYY-MM-ДДTчч:мм:сс+UTC», например, «2024-05-10T16:29:30+0300», где:

  • YYYY – указывает год;

  • ММ – месяц;

  • DD – день;

  • T – указатель, указывающий на начальную часть времени;

  • чч – час;

  • мм – минута;

  • сс – секунды;

  • знак “+” или “-” – положительный или отрицательный метод смещения времени;

  • UTC – всемирное координированное время.

Примечание

Всем сообщениям, которые не были переданы до наступления даты окончания рассылки, Платформой присваивается статус EXPIRED (Сообщение просрочено по сроку жизни).

useTimeDiff

boolean
Если true, то сообщение отправляется с учетом часового пояса абонента.
Если false, то часовой пояс абонента не учитывается.
Значение по умолчанию: false.

messages

array of object

Массив объектов, который содержит пакет сообщений на отправку.

Примечание

В данном параметре возможно отправить сообщения абонентам с разных Сервисных имён, доступных Партнёру, а также с разным текстом.

messages/from

string

Сервисное имя.

messages/to

string

Номер телефона в международном формате XXX YYY ZZZ ZZ ZZ, согласно стандарту E.164, где:

  • XXX – международный код страны;

  • YYY – код оператора или города;

  • ZZZ ZZ ZZ – абонентский номер телефона.

Пример: 79031234567

messages/text

string
Текст сообщения.
Максимальная длина текста: 2000 символов.

messages/id

string
Уникальный идентификатор сообщения на стороне Партнёра.
Максимальная длина: 50 символов.
Сервис-провайдер возвращает этот параметр в ответе на запрос вместе со статусом сообщения (см. Сервис получения статусов доставки).
Данный параметр может быть использован, в том числе, для контроля повторных отправок и дублирования.
В случае, если установлен запрет на отправку дубликатов, будет произведена проверка дубликатов сообщений по переданному id.

messages/validity

integer
Срок жизни сообщения в секундах.
Минимальное значение: 60 секунд.
Максимальное значение: 259200 секунд (3 суток).
По умолчанию: 172800 секунд (2 суток).

messages/priority

integer
Приоритет отправки сообщения, от 0 до 3, где 0 – низкий приоритет, 3 – наивысший.
По умолчанию: 0.
По умолчанию опция недоступна. Для подключения данной опции следует обратиться в Службу технической поддержки.

messages/callbackUrl

string

URL, на который Платформа будет отправлять уведомления об изменениях статуса сообщения. Любой валидный URL со схемой HTTP или HTTPS.

Ответ на запрос#

После отправки сообщения Сервис-провайдер синхронно возвращает ответ.
В теле ответа передается массив объектов result, содержащий результаты обработки для каждого SMS-сообщения исходного пакета.
 1   {
 2       "result": [
 3           {
 4               "code": "OK",
 5               "messageId": "3482512350952730368"
 6           },
 7           {
 8               "code": "REJECTED",
 9               "messageId": null,
10               "reasons": [
11                   {
12                       "key": "not.available",
13                       "ref": "messages[0].from"
14                   }
15               ],
16               "description": "Error: Source address in not available. Source address: TAXI"
17           }
18       ]
19   }

Ошибки при отправке#

Ошибки параметра reasons/key, возвращаемые при первичном приёме пакета сообщений.

key

ref

Описание

forbidden

Отправка запрещена.

unknown

Неизвестная ошибка.

invalid

messages[i].to

Неправильно указан номер телефона.

messages[i].validity

Неправильно указан срок жизни.

messages[i].callbackUrl

Неправильно указан URL.

length.too.long

messages[i].text

Превышена максимальная длина текста сообщения.

must.be.not.null

messages

Массив messages не может быть пустым.

not.available

messages[i].from

Неправильно указан отправитель.

too.many.messages

messages

Превышен максимальный размер массива messages.

Статусы доставки SMS-сообщений#

Для получения статусов SMS-сообщений необходимо настроить Сервис получения статусов доставки.