Данный 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" } } } ] }