База знаний

Общее описание

Данный REST API () предназначен для взаимодействия клиентов с сервером уведомлений. Все запросы к API () осуществляются по протоколу HTTP. Тело запроса передается в формате JSON . При этом необходимо устанавливать Content-type: application/json . Также в параметре charset необходимо передавать значение кодировки - UTF-8. Формат для отправки даты и времени ISO 8601. Время передается в часовом поясе UTC

Аутентификация

Используется Basic аутентификация. При базовой аутентификации клиент вместе с запросом отправляет серверу логин и пароль. Эти данные отправляются в заголовке запроса Authorization в виде base64 кода. Authorization: Basic base64_encode(login:password) Так, например, если логин и пароль admin, нужно добавить такой заголовок: Authorization: Basic YWRtaW46YWRtaW4=

Общий формат ответа

Используются HTTP ответы с соответствующими кодами. Если какая-либо переменная ответа имеет несколько значений, они формируются в виде массива. Если в запросе было несколько значений какой-либо переменной, в ответе значения будут в том же порядке.

Если запрос содержит ошибку (код 400), то в теле ответа обязательно присутствует JSON объект со следующими полями.

Имя Тип Обязательность Описание
error_code string да Код ошибки
error_description string да Описание ошибки

Коды ошибок

Данные коды возвращаются при получении HTTP ответа с кодом 400. И являются значениями поля «error_code», описанного выше.

Код Описание Перевод
100 Internal server error Внутренняя ошибка сервера
101 Syntax error Синтаксическая ошибка
102 Account lock Аккаунт клиента заблокирован
103 Empty channel Не задан канал для отправки сообщений
104 Invalid priority Указано некорректное значение параметра priority
105 Too much IDs Передано слишком много идентификаторов сообщений
202 Empty recipient Адрес получателя не задан (кроме канала email)
204 Empty email address Адрес электронной почты получателя не задан (для канала email)
205 Empty message-id Идентификатор сообщения не задан
206 Invalid variables Указано некорректное значение параметра variables
301 Invalid localtime Указано некорректное значение параметра localtime
302 Invalid start-datetime Указано некорректное значение параметра start-datetime
303 Invalid end-datetime Указано некорректное значение параметра end-datetime
304 Invalid allowedstarttime Указано некорректное значение параметра allowedstarttime
305 Invalid allowedendtime Указано некорректное значение параметра allowedendtime
306 Invalid send-evenly Указано некорректное значение параметра send-evenly
401 Empty originator Адрес отправителя не указан
402 Empty application Приложение не указано
403 Empty ttl Значение ttl не указано (если задано несколько каналов отправки)
404 Empty content Содержимое сообщения не указано
405 Content error Неправильный формат содержимого контента
406 Invalid content Недопустимое значение контента для указанного канала
407 Invalid ttl Неправильно указано значение времени ожидания доставки
408 Invalid attached files Прикрепленные файлы имеют слишком большой объем
410 Invalid retry-attempts Неправильно указано значение количества попыток дозвона
411 Invalid retry-timeout Неправильно указано значение времени повторного дозвона

Отправить сообщения

Сервер Play Mobile принимает запросы от сервера клиента на URL https://127.0.0.1/brokerapi/send

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

Общие параметры.

Название Тип Обязательность Описание
templateid string нет Идентификатор шаблона для отправки сообщения
priority string нет Приоритет: 2 - низкий, 4 - обычный, 6 - высокий, 8 - наивысший. Если не указан, то используется 4
timing object нет Временные настройки
sms object нет Параметры для отправки по соответствующему каналу
call object нет Параметры для отправки по соответствующему каналу
messages array нет Параметры для отправки по соответствующему каналу

Параметры объекта timing.

Название Тип Обязательность Описание
templateid string нет Идентификатор шаблона для отправки сообщения
priority string нет Приоритет: 2 - низкий, 4 - обычный, 6 - высокий, 8 - наивысший. Если не указан, то используется 4
timing object нет Временные настройки
sms object нет Параметры для отправки по соответствующему каналу
call object нет Параметры для отправки по соответствующему каналу
messages array нет Параметры для отправки по соответствующему каналу

Параметры объекта content для sms

Название Тип Обязательность Описание
originator string нет Адрес отправителя

Параметры объекта content для call

Название Тип Обязательность Описание
text string нет Текст сообщения для синтеза TTS, до 2000 байт (1000 символов). Используется один из трех параметров: text, file, ivrmenu. Запрос с более чем одним параметром считается некорректным
priority string нет Приоритет: 2 - низкий, 4 - обычный, 6 - высокий, 8 - наивысший. Если не указан, то используется 4
file string нет Название аудиофайла. Используется один из трех параметров: text, file, ivrmenu. Запрос с более чем одним параметром считается некорректным.
menu string нет Название IVR-меню. Используется один из трех параметров: text, file, ivrmenu. Запрос с более чем одним параметром считается некорректным.
retryattempts Number нет Количество попыток повторного звонка. Допустимы только неотрицательные числа.
retry- Number нет Интервал, через который будет произведен timeout повторный звонок, в миллисекундах

Параметры элемента массива messages.

Название Тип Обязательность Описание
recipient string нет Адрес получателя (как правило MSISDN), указывается строго в формате 9989xxxxxxx, без пробелов и без знака +
message-id string нет Уникальный для системы-отправителя идентификатор сообщения должен быть уникальным для каждого отправленного или переотправленного сообщения. Пример “abc0000001” abc = название организации. Размер поля не более 40 символов
template-id string нет Идентификатор шаблона для отправки сообщения
priority string нет Приоритет: low - низкий, normal - обычный, high - высокий, realtime - наивысший. Если не указан, то используется normal Настраивается в личном кабинете.
timing object нет Временные настройки
variables array нет Объект параметров и их значений для подстановки в сообщение (каждый элемент представлен как запись ПАРАМЕТР: ЗНАЧЕНИЕ, например, {“PARAM1”:”VALUE1”,”PARAM2”:”VALUE2”} ).
sms object нет Параметры для отправки по соответствующему каналу
call object нет Параметры для отправки по соответствующему каналу

Параметры объектов timing и объектов каналов аналогичны параметрам для общей части запроса

Параметры ответа: Успешный запрос имеет статус 200/OK и тела ответа Request is received

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

URL () партнера: /status URL () партнера используется для принудительного получения статусов отправленных сообщений от СМСЦ «Play Mobile». Статус отправляется на URL () партнера, как только получим его от сотового оператора.

Отправка единичного статуса status.json

{
  "messages": [
    {
      "message-id": "",
      "channel": "",
      "status": "",
      "status-date": "",
      "description": ""
    }
  ]
}

Массовая рассылка статуса status.json

{
  "messages": [
    {
      "message-id": "",
      "channel": "",
      "status": "",
      "status-date": "",
      "description": ""
    },
    {
      "message-id": "",
      "channel": "",
      "status": "",
      "status-date": "",
      "description": ""
    }
  ]
}
 

Запрос статусов возвращает следующие статусы сообщений:

Delivered - доставлено; Transmitted - передано оператору, от вас смс получили и отправили оператору, оператор еще не обработал, причиной может быть, когда абонент вне зоны сети или выключен. После 24 часов статус сменится на Доставлено.; NotDelivered - недоставлено, обычно причиной может быть то что абонент блокируется со стороны оператора (недостаточно средств или долг); Rejected - одна из основных причин в том, что номер находится в черном списке; Failed - ошибка при отправки запроса (например когда адрес отправителя указан неверно); Expired - срок жизни смс истек (когда абонент в течение суток не выходил на связь. У билайн если в течение часа).

Примеры

Отправка единичного сообщения

{
  "messages": [
    {
      "recipient": "998900000000",
      "message-id": "abc000000001",
      "sms": {
        "originator": "9800",
        "content": {
          "text": "Test message"
        }
      }
    }
  ]
}

Отправка единичного сообщения

{
  "messages": [
    {
      "recipient": "9989хххххххх",
      "message-id": "abc00000001",
      "sms": {
        "originator": "9800",
        "content": {
          "text": "Test text"
        }
      }
    },
    {
      "recipient": "9989xxxxxxxx",
      "message-id": "abc00000002",
      "sms": {
        "originator": "9800",
        "content": {
          "text": "Test text 1"
        }
      }
    },
    {
      "recipient": "998970000000",
      "message-id": "abc00000003",
      "sms": {
        "originator": 9800,
        "content": {
          "text": "Test text2"
        }
      }
    }
  ]
}