Запрос на отправку 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-сообщений необходимо настроить Сервис получения статусов доставки.