| Управление рассылкамиДействия с рассылкамиДля создания рассылки необходимо вызвать методом GET или POST адрес:
https://smsc.ru/sys/jobs.php?add=1&login=<login>&psw=<password>&name=<name>&phones=<phones>&mes=<message>
Для удаления рассылки необходимо вызвать методом GET или POST адрес:
https://smsc.ru/sys/jobs.php?del=1&login=<login>&psw=<password>&id=<id>
Для отключения рассылки, ожидающей отправки, необходимо вызвать методом GET или POST адрес:
https://smsc.ru/sys/jobs.php?cancel=1&login=<login>&psw=<password>&id=<id>
Для получения информации о конкретной рассылке, необходимо вызвать методом GET или POST адрес:
https://smsc.ru/sys/jobs.php?get=1&login=<login>&psw=<password>&id=<id>
Для получения списка рассылок, необходимо вызвать методом GET или POST адрес:
https://smsc.ru/sys/jobs.php?get_all=1&login=<login>&psw=<password>
Описание параметров, передаваемых Серверу при создании рассылки (любой из дополнительных параметров применяется к каждому сообщению в рассылке; для работы с e-mail рассылками необходимо в запросе передавать дополнительный параметр mail=1):
| Параметр | Значение
|
|---|
| login | Логин Клиента.
|
|---|
| psw | Пароль Клиента (можно добавить или изменить на данной странице).
|
|---|
| apikey | Специальный API-ключ, используемый для упрощенной авторизации вместо пары "логин+пароль" (можно создать на данной странице).
|
|---|
| name | Название рассылки.
|
|---|
| phones | Номер или разделенный запятой или точкой с запятой список номеров мобильных телефонов в международном формате,
на которые отправляется сообщение. Номера могут передаваться без знака "+".
Если номер передан без знака "+", то он может быть исправлен автоматическим форматированием
и приведен к правильному международному формату. Таким образом, некоторые
ошибки при вводе номеров телефонов могут быть исправлены автоматически.
Для отключения автоисправления передайте номер со знаком "+".
Также можно отправлять сообщение на группу номеров, указав специальный код "G<номер группы>".
Сообщение будет отправлено на все номера, принадлежащие данной группе. Для e-mail сообщения передается список e-mail адресов
получателей. Для telegram в качестве получателя сообщения возможно указание ника абонента или его ID в виде #ID.
|
|---|
| mes | Текст отправляемого сообщения. Максимальный размер – 1000 символов. Сообщение при
необходимости будет разбито на несколько SMS, отправленных абоненту и оплаченных по отдельности. Размер одного
SMS – 160 символов в латинице или 70 символов в кириллице. При разбивке сообщения на несколько SMS в каждую часть
добавляется заголовок для объединения частей в одно сообщение на телефоне получателя, и максимальная длина становится
67 для кириллицы и 153 для латинских букв. В текст сообщения можно добавлять комментарии,
предназначенные для просмотра отправителем истории в личном кабинете.
|
|---|
| Дополнительные параметры
|
|---|
| sender | Имя отправителя, отображаемое в телефоне получателя.
Разрешены английские буквы, цифры, пробел и некоторые символы. Длина – 11 символов или 15 цифр.
Все имена регистрируются в личном кабинете на данной странице.
|
|---|
| sender2 | Данный параметр используется в качестве имени отправителя при автоповторе по SMS в случае недоставки сообщений через первоначальный вариант отправки.
|
|---|
| translit | Признак того, что сообщение необходимо перевести в транслит.
0 (по умолчанию) – не переводить в транслит.
1 – перевести в транслит в виде "translit".
2 – перевести в транслит в виде "mpaHc/Ium".
|
|---|
| tinyurl | Автоматически сокращать ссылки в сообщениях. Позволяет заменять ссылки в тексте
сообщения на короткие для сокращения длины, а также для отслеживания количества переходов на
этой странице.
0 (по умолчанию) – оставить ссылки в тексте сообщения без изменений.
1 – сократить ссылки.
|
|---|
| time | Время отправки SMS-сообщения абоненту.
Форматы:
- DDMMYYhhmm или DD.MM.YY hh:mm.
- h1-h2. Задает диапазон времени в часах. Если текущее время меньше h1, то SMS-сообщение
будет отправлено абоненту при наступлении времени h1, если текущее время попадает в промежуток от h1 до h2,
то сообщение будет отправлено немедленно, в другом случае отправка будет выполнена на следующий день при
достижении времени h1. Данная функция, например, полезна для того, чтобы не допустить получение SMS-сообщений
абонентами в ночное время.
- 0ts, где ts – timestamp, время в секундах, прошедшее с 1 января 1970 года.
- +m. Задает относительное смещение времени от текущего в минутах. Символ + должен кодироваться как %2B в http-запросе.
Если time = 0 или указано уже прошедшее время, то сообщение будет отправлено немедленно.
|
|---|
| rpt | Определяет периодичность отправки вновь создаваемой рассылки.
0 (по умолчанию) – вручную.
1 – каждый час.
2 – каждый день.
3 – каждый рабочий день.
4 – каждые выходные.
5 – каждую неделю.
6 – каждый месяц.
7 – каждый год.
|
|---|
| rptn | Устанавливает максимальное количество повторов для отложенной периодической рассылки.
|
|---|
| tz | Часовой пояс, в котором задается параметр time. Указывается относительно московского времени.
Параметр tz может быть как положительным, так и отрицательным. Если tz равен 0, то будет использован московский часовой
пояс, если же параметр tz не задан, то часовой пояс будет взят из настроек Клиента.
|
|---|
| period | Промежуток времени, в течение которого необходимо отправить рассылку. Представляет собой число
в диапазоне от 0.1 до 720 часов. Применяется совместно с параметром freq. Данный параметр позволяет растянуть рассылку во
времени для постепенного получения SMS-сообщений абонентами.
|
|---|
| freq | Интервал или частота, с которой нужно отправлять SMS-рассылку на очередную группу номеров. Количество
номеров в группе рассчитывается автоматически на основе параметров period и freq. Задается в промежутке от 1 до 1440 минут.
Без параметра period параметр freq игнорируется.
|
|---|
| flash | Признак Flash сообщения, отображаемого сразу на экране телефона.
0 (по умолчанию) – обычное сообщение.
1 – Flash сообщение.
|
|---|
| bin | Признак бинарного сообщения.
0 (по умолчанию) – обычное сообщение.
1 – бинарное сообщение. В http-запросе необходимо закодировать с помощью функции urlencode.
2 – бинарное сообщение, представленное в виде шестнадцатеричной строки (hex).
Бинарное сообщение передается вместе с UDH заголовком в начале в параметре mes, в котором первый байт задает длину заголовка.
Чтобы передать бинарное сообщение без UDH заголовка, укажите нулевой байт в начале сообщения (00 в hex).
Для возможности передачи параметров pid и dcs необходимо в конец бинарного сообщения добавить специальную комбинацию
"\n~~~\n" (перевод строки, 3 символа тильды и снова перевод строки) и затем текст "pid: значение1, dcs: значение2" с точным сохранением
пробелов.
|
|---|
| push | Признак wap-push сообщения, с помощью которого можно отправить интернет-ссылку на телефон.
0 (по умолчанию) – обычное сообщение.
1 – wap-push сообщение. В параметре mes необходимо передать ссылку и заголовок через перевод строки.
|
|---|
| hlr | Признак HLR-запроса для получения информации о номере из базы оператора без отправки реального SMS.
0 (по умолчанию) – обычное сообщение.
1 – HLR-запрос. Будет выполнен HLR-запрос для каждого номера телефона в списке. Параметр mes не используется.
|
|---|
| ping | Признак специального SMS, не отображаемого в телефоне, для проверки номеров на доступность в реальном времени по статусу доставки.
0 (по умолчанию) – обычное сообщение.
1 – ping-sms. Будет отправлено Ping-SMS на каждый номер телефона в списке.
Параметр mes не используется.
|
|---|
| mms | Признак MMS-сообщения, с помощью которого можно передавать текст (txt), изображения различных форматов (jpg, gif, png),
музыку (wav, amr, mp3, mid) и видео (mp4, 3gp). Файлы передаются в теле http-запроса.
0 (по умолчанию) – обычное сообщение.
1 – MMS-сообщение. Будет отправлено MMS на каждый номер телефона в списке.
|
|---|
| mail | Признак e-mail сообщения. Файлы, прикрепляемые к сообщению, передаются методом POST в теле http-запроса.
0 (по умолчанию) – обычное сообщение.
1 – e-mail сообщение.
|
|---|
| soc | Признак soc-сообщения, отправляемого пользователям социальных сетей "Одноклассники", "ВКонтакте" или пользователям "Mail.Ru Агент".
0 (по умолчанию) – обычное сообщение.
1 – soc-сообщение.
|
|---|
| viber | Признак viber-сообщения, отправляемого пользователям мессенджера Viber.
0 (по умолчанию) – обычное сообщение.
1 – viber-сообщение.
|
|---|
| whatsapp | Признак whatsapp-сообщения, отправляемого пользователям мессенджера WhatsApp.
0 (по умолчанию) – обычное сообщение.
1 – whatsapp-сообщение.
|
|---|
| tg | При указании значения данного параметра равным 1 будет отправлено telegram-сообщение с кодом подтверждения, переданным в параметре mes.
|
|---|
| bot | Имя бота (telegram), в который необходимо отправить сообщение в формате "@botname_bot".
|
|---|
| smsreq | При указании данного параметра, система не будет отображать текст сообщения, отправленного пользователю и выводить предупреждение о необходимости подтверждения номера телефона, если с момента последнего подтверждения прошло больше smsreq дней. Диапазон значений от 10 до 999.
|
|---|
| fileurl | Полный http-адрес файла для загрузки и передачи в сообщении. Минимальный размер файла составляет 101 байт.
|
|---|
| mes2 | Данный параметр задает вариант сообщения для пересылки по SMS в режиме автоматического повтора при недоставке на альтернативные маршруты, например, отправка в мессенджеры. Для включения автоматического повтора необходимо в запросе дополнительно передать флаг fl[5], равный 1.
|
|---|
| call | Признак голосового сообщения. При формировании голосового сообщения можно передавать как текст, так и прикреплять файлы.
Файлы, добавляемые к сообщению, должны передаваться методом POST в теле http-запроса.
0 (по умолчанию) – обычное сообщение.
1 – голосовое сообщение.
|
|---|
| voice | Голос, используемый для озвучивания текста (только для голосовых сообщений).
m – мужской голос.
m2 – мужской голос 2.
m3 (по умолчанию) – мужской голос 3.
m4 – мужской голос 4.
w – женский голос.
w2 – женский голос 2.
w3 – женский голос 3.
w4 – женский голос 4.
При отправке сообщений также возможно указание языка озвучивания текста в виде: "m,en", "w,fr", "w,de" и т.п.
|
|---|
| param | Разделенный запятой список параметров для голосового сообщения в формате "param=w,i,n".
Здесь:
- w – время ожидания поднятия трубки абонентом после начала звонка в секундах. Если в течение указанного времени абонент не поднимет трубку,
то звонок уйдет на повтор с ошибкой "абонент занят". Рабочий диапазон значений параметра от 10 до 35, но можно указывать интервал от 0 до 99
(в случае, если значение меньше 10, то оно будет приведено к 10, аналогично для верхней границы).
- i – интервал повтора, то есть промежуток времени, по истечении которого произойдет повторный звонок (в секундах). Рабочий диапазон параметра
от 10 до 3600 (в случае, если значение меньше 10, то оно будет приведено к 10).
- n – общее количество попыток дозвона. Рабочий диапазон значений от 1 до 9 (0 будет приведен к 1).
При указании значения любого параметра, отличного от возможных, будут использованы значения всех параметров по умолчанию
(n = 8, w = 25, i от 3 до 14 секунд по нарастающей), кроме сообщений рекламного характера.
|
|---|
| subj | Тема MMS или e-mail сообщения. При отправке e-mail указание темы, текста и адреса отправителя обязательно. Для MMS обязательным
является указание темы или текста. Если не указать тему MMS, то в ее качестве будет использовано имя отправителя, переданное в запросе или
используемое по умолчанию.
|
|---|
| charset | Кодировка переданного сообщения, если используется отличная от кодировки по
умолчанию windows-1251. Варианты: utf-8 и koi8-r.
|
|---|
| cost | Признак необходимости получения стоимости рассылки.
0 (по умолчанию) – обычная отправка.
1 –
добавить в ответ стоимость рассылки.
|
|---|
| fmt | Формат ответа сервера об успешной отправке.
0 – (по умолчанию) в виде строки (OK - 1 SMS, ID - 1234).
1 – вернуть ответ в виде чисел: ID и количество SMS через запятую (1234,1), при cost = 2 еще стоимость через
запятую (1234,1,1.40), при cost = 3 еще новый баланс Клиента (1234,1,1.40,100.50), при cost = 1 стоимость и количество
SMS через запятую (1.40,1).
2 – ответ в xml формате.
3 – ответ в json формате.
|
|---|
| list | Список номеров телефонов и соответствующих им сообщений, разделенных двоеточием или точкой с запятой и
представленный в виде:
phones1:mes1
phones2:mes2
...
Строки разделяются через символ новой строки (%0A). В качестве phones можно указать несколько номеров телефонов через
запятую. Если в сообщении mes требуется передать символ новой строки, то укажите его через \n. В случае невозможности корректировки текста мультистрокового сообщения возможно включение специального режима для передачи такого типа сообщений. Для этого необходимо дополнительно передавать в запросе параметр nl, равный 1.
В случае необходимости передачи разных имен отправителей (и, возможно, различных часовых поясов абонентов (работает только для запросов, в которых параметр time представлен в виде DDMMYYhhmm или DD.MM.YY hh:mm)) для разных сообщений можно использовать следующий формат передачи:
sender1,tz1|phones1:mes1
sender2,tz2|phones2:mes2
...
В данном случае параметр tz является необязательным.
Параметр list позволяет выполнять множественную рассылку с разными сообщениями на несколько телефонов одним
http-запросом. Сообщениям в запросе присваивается единый идентификатор. Весь параметр должен быть закодирован с
помощью функции urlencode.
|
|---|
| tpl | ID шаблона, который будет использован в качестве текста сообщения. Для использования шаблона необходимо,
чтобы параметр mes был пустым.
|
|---|
| valid | Срок "жизни" SMS-сообщения. Определяет время, в течение которого оператор будет пытаться доставить
сообщение абоненту. Диапазон от 1 до 24 часов. Также возможно передавать время в формате чч:мм в диапазоне от 00:01 до 24:00.
|
|---|
Обязательными параметрами являются login, psw, name, phones и mes или login, psw, name и list.
Описание параметров, передаваемых Серверу при удалении, отключении или получении списка рассылок:
| Параметр | Значение
|
|---|
| login | Логин Клиента.
|
|---|
| psw | Пароль Клиента (можно добавить или изменить на данной странице).
|
|---|
| id | Идентификатор рассылки. Возвращается Сервером после создания и используется для дальнейшей идентификации рассылки.
|
|---|
| Дополнительные параметры
|
|---|
| start | Дата, с которой требуется получить список рассылок. Если данный параметр не указан, возвращает список рассылок за последние 2 месяца, но не более 10. Применяется совместно с параметром get_all. Формат: 'дд.мм.гггг'.
|
|---|
| end | Дата, до которой требуется получить список рассылок. Если данный параметр не указан, то возвращается список рассылок до текущий даты, но не более 10. Применяется совместно с параметром get_all. Формат: 'дд.мм.гггг'.
|
|---|
Обязательными параметрами являются login, psw и id.
После принятия и обработки данных Сервер возвращает Клиенту подтверждение с указанием результата обработки.
Все параметры, которые содержат специальные символы (плюс, пробел и т.д.), должны быть закодированы
при помощи функции urlencode для передачи в HTTP-запросе.
Рассылки. Ответ сервера и коды ошибок
Сервер отправляет ответ в виде строки:
Если произошла ошибка, то ответ будет одним из следующих:
При fmt = 0:
- ERROR = N (описание) – для ошибок 1,2,3,4,5,9.
При fmt = 1:
- 0,-N – для ошибок 1,2,3,4,5,9.
При fmt = 2:
- Для ошибок 1,2,3,4,5,9:
<result>
<error>описание</error>
<error_code>N</error_code>
</result> |
При fmt = 3:
- Для ошибок 1,2,3,4,5,9:
{
"error": "описание",
"error_code": N
} |
N – номер ошибки, может принимать следующие значения:
| Значение | Описание
|
|---|
| 1 | Ошибка в параметрах.
|
|---|
| 2 | Неверный логин или пароль. Также возникает при попытке отправки сообщения с IP-адреса, не входящего в список разрешенных Клиентом (если такой список был настроен Клиентом ранее).
|
|---|
| 3 | Ошибка сохранения записи.
|
|---|
| 4 | IP-адрес временно заблокирован из-за частых ошибок в запросах. Подробнее
|
|---|
| 5 | Неверный формат даты.
|
|---|
| 9 | Отправка более одного одинакового запроса на действия с рассылками в течение минуты.
Данная ошибка возникает также при попытке отправки пятнадцати и более запросов одновременно с разных подключений под одним логином (too many concurrent requests).
|
|---|
В случае успешной обработки запроса возвращается строка следующего вида:
При создании рассылки:
- при cost = 0 и fmt = 0: OK, ID - <id>
- при cost = 1 и fmt = 0: OK, ID - <id>, COST - <cost>
- при cost = 0 и fmt = 1: <id>
- при cost = 1 и fmt = 1: <id>,<cost>
- при cost = 0 и fmt = 2:
<result>
<id>id</id>
</result> |
- при cost = 1 и fmt = 2:
<result>
<id>id</id>
<cost>cost</cost>
</result> |
- при cost = 0 и fmt = 3:
- при cost = 1 и fmt = 3:
{
"id": <id>,
"cost": "<cost>"
} |
При отключении или удалении рассылки:
- при fmt = 0,1: OK
- при fmt = 2:
- при fmt = 3:
При получении информации о конкретной рассылке (при mail=1 параметр "phones" заменяется на "emails"):
- при fmt = 0: <id>|<name>|<subject>|<repeat_send>|<repeat_cnt>|<created>|<changed>|<need_date>|<last_sent>|<phones>|<message>|<format>|<validity>|<period>|<frequency>|<status>|<sender_id>
- при fmt = 1: <id>;<name>;<subject>;<repeat_send>;<repeat_cnt>;<created>;<changed>;<need_date>;<last_sent>;<phones>;<message>;<format>;<validity>;<period>;<frequency>;<status>;<sender_id>
- при fmt = 2:
<job>
<id>id</id>
<name>name</name>
<subject>subject</subject>
<repeat_send>repeat_send</repeat_send>
<repeat_cnt>repeat_cnt</repeat_cnt>
<created>created</created>
<changed>changed</changed>
<need_date>need_date</need_date>
<last_sent>last_sent</last_sent>
<phones>phones</phones>
<message>message</message>
<format>format</format>
<validity>validity</validity>
<period>period</period>
<frequency>frequency</frequency>
<status>status</status>
<sender_id>sender_id</sender_id>
</job> |
- при fmt = 3:
[
{
"id": <id>,
"name": "<name>",
"subject": "<subject>",
"repeat_send": <repeat_send>,
"repeat_cnt": <repeat_cnt>,
"created": "<created>",
"changed": "<changed>",
"need_date": "<need_date>",
"last_sent": "<last_sent>",
"phones": "<phones>",
"message": "<message>",
"format": <format>,
"validity": <validity>,
"period": "<period>",
"frequency": <frequency>,
"status": <status>,
"cost": "<cost>",
"sms_sent": <sms_sent>,
"sms_ok": <sms_ok>,
"sender_id": "<sender_id>"
}
] |
При получении списка рассылок (при mail=1 параметр "phones" заменяется на "emails"):
- при fmt = 0: <id>|<name>|<changed>|<need_date>|<last_sent>|<phones>|<message>|<phones_cnt>|<cost>|<status>|<sender_id>|<format>
- при fmt = 1: <id>;<name>;<changed>;<need_date>;<last_sent>;<phones>;<message>;<phones_cnt>;<cost>;<status>;<sender_id>;<format>
- при fmt = 2:
<sms_jobs>
<job>
<id>id</id>
<name>name</name>
<changed>changed</changed>
<need_date>need_date</need_date>
<last_sent>last_sent</last_sent>
<phones>phones</phones>
<message>message</message>
<phones_cnt>phones_cnt</phones_cnt>
<cost>cost</cost>
<status>status</status>
<sender_id>sender_id</sender_id>
<format>format</format>
</job>
...
</sms_jobs>
|
- при fmt = 3:
[
{
"id": <id>,
"name": "<name>",
"changed": "<changed>",
"need_date": "<need_date>",
"last_sent": "<last_sent>",
"phones": "<phones>",
"message": "<message>",
"phones_cnt": <phones_cnt>,
"cost": "<cost>",
"status": <status>,
"sender_id": "<sender_id>",
"format": <format>,
"sms_sent": <sms_sent>,
"sms_ok": <sms_ok>
},
...
] |
Где:
<id> – идентификатор рассылки, переданный Клиентом или назначенный Сервером автоматически.
<name> – название рассылки.
<subject> – тема (для e-mail рассылок).
<repeat_send> – период повтора.
<repeat_cnt> – количество повторов рассылки.
<created> – дата создания рассылки.
<changed> – дата изменения рассылки.
<need_date> – назначенная дата отправки.
<last_sent> – дата последней отправки.
<phones> (<emails>) – список телефонов (e-mail адресов) получателей сообщений.
<message> – текст сообщения.
<format> – формат сообщения.
<validity> – "время жизни" сообщения.
<period> – интервал отправки сообщений.
<frequency> – частота отправки сообщений.
<status> – статус рассылки.
<sender_id> – имя отправителя.
<phones_cnt> – количество получателей.
<cost> – стоимость рассылки.
<sms_sent> – количество отправленных сообщений.
<sms_ok> – количество доставленных сообщений.Примеры операций с рассылкамиПримеры:
Создание SMS-рассылки:
https://smsc.ru/sys/jobs.php?add=1&login=alex&psw=123&phones=79999999999&name=Privet&mes=Hello!
Создание рассылки с голосовым сообщением:
https://smsc.ru/sys/jobs.php?add=1&login=alex&psw=1234567890&phones=79999999999&call=1&voice=w2&name=Privet&mes=Hello!
Создание рассылки с e-mail сообщением на адрес "alex@mysite.com" с темой "Hi" и текстом "Hello!" от отправителя "alex2@mysite2.com"
и названием рассылки "Privet":
https://smsc.ru/sys/jobs.php?add=1&login=alex&psw=123&phones=alex%40mysite.com&mail=1&name=Privet&mes=Hello!&subj=Hi&sender=alex2%40mysite2.com
Создание Viber-рассылки с макросами и автоповтором по SMS (текст SMS отличен от текста Viber-сообщения) на несколько номеров (тексты сообщений необходимо закодировать при помощи функции urlencode):
https://smsc.ru/sys/jobs.php?add=1&login=alex&psw=123&phones=79999999999,78888888888&name=rassilka1&mes={Имя}, это Viber-сообщение&mes2=Это SMS для {Имя}&sender=MyViber&fl[5]=1&viber=1
Удаление созданной рассылки с id равным 701:
https://smsc.ru/sys/jobs.php?del=1&login=alex&psw=123&id=701
Отключение отложенной рассылки с id равным 701:
https://smsc.ru/sys/jobs.php?cancel=1&login=alex&psw=123&id=701 |
УПРАВЛЕНИЕ РАССЫЛКАМИ
