Данный REST API предназначен для взаимодействия клиентов с сервером уведомлений PLAY MOBILE. Все запросы к 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 allowed-starttime Указано некорректное значение параметра allowed-starttime
305 Invalid allowed-endtime Указано некорректное значение параметра allowed-endtime
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://send.smsxabar.uz/broker-api/send
http://91.204.239.39/broker-api/send

Тело запроса

Приведенный JSON демонстрирует все доступные в запросе параметры.

allexample.json
{
  "template-id": "",
  "priority": "",
  "blacklist-id": "", 
“timing”: {
    "localtime": "",
    "start-datetime": "",
    "end-datetime": "", “allowed-starttime”: “”, 
“allowed-endtime”: “”,
    "send-evenly": ""
  },
  "sms": { 
“originator”: “smsSender”, 
“ttl”: “300”, 
“content”: { 
“text”: “Test text”
    }
  },
  "call": {  
“originator”: “998900000000”, 
“ttl”: “300”, 
“content”: { 
“text”: “Test text”, 
“menu”: “Test”, 
“file”: “”
    },
    "retry-attempts": "",
    "retry-timeout": ""
  },
  "messages": [
    { 
“recipient”: “998900000001”, 
“message-id”: “abc000001”,
      "template-id": "",
      "priority": "",
      "variables": [], 
“timing”: {
        "localtime": "",
        "start-datetime": "",
        "end- datetime": "",  	 
	 	“allowed-starttime”: “”, 
 	“allowed-endtime”: “”
      },
      "sms": { 
 
	“originator”: “smsSender”, 	“ttl”: “300”, 
“content”: { 
“text”: “Test text”
        }
      },
      "call": {  
“originator”: “998900000002”, 
“ttl”: “300”, 
“content”: { 
“text”: “Test text”, 
“menu”: “Test”, 
“file”: “”
        },
        "retry-attempts": "",
        "retry-timeout": ""
      }
    ]
  }
Параметры запроса

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

Название Тип Обязательность Описание
template-id string Нет Идентификатор шаблона для отправки сообщения
priority string Нет Приоритет:
low - низкий,
normal - обычный,
high - высокий,
realtime - наивысший.
Если не указан, то используется normal
timing object Нет Временные настройки
sms object Нет Параметры для отправки по соответствующему каналу
call object Нет Параметры для отправки по соответствующему каналу
messages array Да Параметры для отправки по соответствующему каналу

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

Название Тип Обязательность Описание
localtime Number Нет Отправлять по местному времени
0  - получателя
1  - системы
start-datetime datetime Нет Дата начала отправки.
Формат YYYY-MM-DD hh:mm.
Если не указана, то сообщения отправляются сразу же.
end-datetime datetime Нет Дата завершения отправки.
Формат YYYY-MM- DD hh:mm.
Если не указана, то система не стремится отправиться все сообщения до определенного времени.
allowed-starttime datetime Нет Время, с которого разрешена отправка.\\Формат hh:mm
allowed-endtime datetime Нет Время, до которого разрешена отправка.
Формат hh:mm
send-evenly Number Нет Равномерно распределять отправку
1 - распределять
0 - не распределять

Параметры объектов каналов (sms, call).

Название Тип Обязательность Описание
originator string Нет Адрес отправителя
ttl Number Нет Время жизни сообщения в секундах. По истечении данного времени сообщению присваивается статус expired и производится отправка сообщения по альтернативному каналу, если он задана
content object Нет Параметры для отправки по каналу

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

Название Тип Обязательность Описание
text string Нет Текст сообщения.

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

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

Параметры элемента массива 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 партнера: <base-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 - срок жизни смс истек(когда абонент в течение сутки не выходил на связь. У билайн если в теение часа).

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

send.json
{
    "messages": [
      {
        "recipient": "998900000000",
        "message-id": "abc000000001",
        "sms": {
          "originator": "3700",
          "content": {
            "text": "Test message"
          }
        }
      }
    ]
  }
 


Отправка массовой рассылки

sendMas.json
{
    "messages": [
        {
            "recipient": "9989хххххххх",
            "message-id": "abc00000001",
            "sms": {
                "originator": "3700",
                "content": {
                    "text": "Test text"
                }
            }
        },
        {
            "recipient": "9989xxxxxxxx",
            "message-id": "abc00000002",
            "sms": {
                "originator": "3700",
                "content": {
                    "text": "Test text 1"
                }
            }
        },
        {
            "recipient": "998970000000",
            "message-id": "abc00000003",
            "sms": {
                "originator": 3700,
                "content": {
                    "text": "Test text 2"
                }
            }
        }
    ]
}

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

sendTemplate.json
{
    "messages": [
        {
            "template-id": "111",
            "recipient": "998900000000",
            "message-id": "abc0000001",
            "variables": {
                "NAME": "IVAN",
                "SURNAME": "IVANOV"
            }
        }
    ]
} 


Отправка массовой рассылки по расписанию

sendTiming.json
{priority": "",
    "timing": 
        {"localtime": "true",
            "start-datetime": "2017-11-05 10-00",
            "end-datetime": "2017-11-25 19-00",
            "allowed-starttime'""': "10-00 ","allowed-endtime": "19-00""send-evenly": "false"
},
"sms": {
    "originator": "smsSender",
    "content": {
        "text": "Test text"
    }
},
"messages": [
    {
        "recipient": "998900000000",
        "message-id": "abc00000145"
    },
    {
        "recipient": "998900000001",
        "message-id": "abc00000146"
    }
]
}
} 


Отправка массовой рассылки по шаблону

sendMasTemplate.json
{
"template-id": "112",
"messages": [
{
    "recipient": "998900000000",
    "message-id": "abc000001",
    "variables": {
        "NAME": "IVAN",
        "SURNAME": "IVANOV"
    }
},
{
    "recipient": "998900000001",
    "message-id": "abc000002",
    "variables": {
        "NAME": "PETR",
        "SURNAME": "KUZIN"
    }
},
{
    "recipient": "998900000002",
    "message-id": "abc000003",
    "variables": {
        "NAME": "VLADIMIR",
        "SURNAME": "NESTEROV"
    }
}
]
}
  • Last modified: 14 months ago