| SMTP протокол (E-mail)Отправка сообщения
Для отправки SMS необходимо послать e-mail на адрес
send send.smsc.kz с текстом в формате:
<login>:<psw>:<id>:<time>,<tz>:<translit>,<format>,<sender>,<test>:<phones>:<mes>
либо:
<login>:<psw>:<id>:<time>,<tz>:<translit>,<format>,<sender>,<test>::<list>
Возможно использование нашего SMTP-сервера напрямую. Адрес: send.smsc.kz. Авторизация не требуется.
Письмо должно передаваться простым текстом с указанием кодировки, по умолчанию koi8-r. Кодировка задается в заголовке Content-Type
(Content-Type: text/plain; charset="CHARSET"). Максимальный размер письма составляет 100 Кб.
В случае отсутствия возможности передачи текста письма с "Content-Type: text/plain" необходимо заключить текст в специальные теги "[text]текст письма[/text]".
Описание параметров, передаваемых Серверу :
| Параметр | Значение
|
|---|
| login | Логин Клиента.
|
|---|
| psw | Пароль Клиента (можно добавить или изменить на данной странице).
При передаче в запросе пустого значения поля login данный параметр интерпретируется, как API ключ авторизации (apikey).
|
|---|
| phones | Номер или разделенный запятой или точкой с запятой список номеров мобильных телефонов в международном формате,
на которые отправляется сообщение. Номера могут передаваться без знака "+".
Если номер передан без знака "+", то он может быть исправлен автоматическим форматированием
и приведен к правильному международному формату. Таким образом, некоторые
ошибки при вводе номеров телефонов могут быть исправлены автоматически.
Для отключения автоисправления передайте номер со знаком "+".
Также можно отправлять сообщение на группу номеров, указав специальный код "G<номер группы>".
Сообщение будет отправлено на все номера, принадлежащие данной группе. Для e-mail сообщения передается список e-mail адресов
получателей. Для telegram в качестве получателя сообщения возможно указание ника абонента или его ID в виде #ID.
|
|---|
| mes | Текст отправляемого сообщения. Максимальный размер – 1000 символов. Сообщение при
необходимости будет разбито на несколько SMS, отправленных абоненту и оплаченных по отдельности. Размер одного
SMS – 160 символов в латинице или 70 символов в кириллице. При разбивке сообщения на несколько SMS в каждую часть
добавляется заголовок для объединения частей в одно сообщение на телефоне получателя, и максимальная длина становится
67 для кириллицы и 153 для латинских букв. В текст сообщения можно добавлять комментарии,
предназначенные для просмотра отправителем истории в личном кабинете.
|
|---|
| Дополнительные параметры
|
|---|
| id | Идентификатор сообщения. Назначается Клиентом. Служит для дальнейшей идентификации сообщения. Если не указывать, то будет назначен автоматически. Не обязательно уникален. Идентификатор представляет собой 32-битное число в диапазоне от 1 до 2147483647, либо строку длиной до 40 символов, состоящую из латинских букв, цифр и символов ".-_".
|
|---|
| sender | Имя отправителя, отображаемое в телефоне получателя.
Разрешены английские буквы, цифры, пробел и некоторые символы. Длина – 11 символов или 15 цифр.
Все имена регистрируются в личном кабинете на данной странице.
|
|---|
| translit | Признак того, что сообщение необходимо перевести в транслит.
0 (по умолчанию) – не переводить в транслит.
1 – перевести в транслит в виде "translit".
2 – перевести в транслит в виде "mpaHc/Ium".
|
|---|
| 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 или указано уже прошедшее время, то сообщение будет отправлено немедленно.
|
|---|
| tz | Часовой пояс, в котором задается параметр time. Указывается относительно московского времени.
Параметр tz может быть как положительным, так и отрицательным. Если tz равен 0, то будет использован московский часовой
пояс, если же параметр tz не задан, то часовой пояс будет взят из настроек Клиента.
|
|---|
| format | Определяет тип SMS-сообщения.
0 (по умолчанию) – обычное текстовое сообщение.
1 – flash-sms. Сообщение, отображаемое сразу на экране телефона.
2 – wap-push. Сообщение, содержащее ссылку на сайт, первая строка задает ссылку, вторая – название.
3 – hlr-запрос. Позволяет получить информацию о номере из базы оператора без отправки SMS.
4 – бинарное сообщение в двоичном виде.
5 – бинарное сообщение, представленное в виде шестнадцатеричной строки (hex).
6 – ping-sms. Проверка номера на доступность отправкой специального невидимого SMS.
7 – mms. Сообщение, позволяющее передавать текст (txt), изображения различных форматов (jpg, gif, png),
музыку (wav, amr, mp3, mid) и видео (mp4, 3gp).
8 – e-mail. Сообщение электронной почты. Тема письма указывается в конце текста сообщения через перевод строки в
виде "subj:Тема". Указание темы, текста и e-mail отправителя обязательно.
9 – голосовое сообщение (звонок). Голос, используемый для озвучки, указывается в конце текста сообщения через перевод строки в
виде "voice:Голос". Возможные типы голосов подробно описаны на данной странице.
10 – viber-сообщение, отправляемое пользователям мессенджера Viber.
11 – whatsapp-сообщение, отправляемое пользователям мессенджера WhatsApp.
12 – soc-сообщение, отправляемое пользователям социальных сетей "Одноклассники", "ВКонтакте" или пользователям "Mail.Ru Агент".
|
|---|
| test | Указывает на необходимость отправлять ответное письмо с результатом отправки SMS-сообщения.
Если 0 или не указано, то ответ посылается только при ошибке в параметрах, если 1, то ответ отправляется в любом случае.
Параметр используется для отладки при первоначальной настройке сервиса.
|
|---|
| list | Список номеров телефонов и соответствующих им сообщений, разделенных двоеточием или точкой с запятой и
представленный в виде:
phones1:mes1
phones2:mes2
...
В качестве phones можно указать несколько номеров телефонов через запятую. Если в сообщении mes требуется передать символ новой строки, то укажите его через \n. В случае невозможности корректировки текста мультистрокового сообщения возможно включение специального режима для передачи такого типа сообщений. Для этого необходимо в параметре test передать значение, равное 2.
Параметр list позволяет выполнять множественную рассылку с разными сообщениями на несколько телефонов одним
запросом. Сообщениям в запросе присваивается единый идентификатор. Некоторые параметры (например, subj, voice) передаются
в конце списка сообщений list через перевод строки.
|
|---|
Параметры должны идти строго в заданном порядке. Обязательными являются login, psw,
phones и mes. Если какой-то необязательный параметр отсутствует, то двоеточие должно оставаться.
Пример (<id>, поле <time>,<tz> и поле <translit>,<format>,<sender>,<test> не указаны):
alex:123::::79999999999:сообщение
В составном поле <translit>,<format>,<sender>,<test> любой параметр может отсутствовать,
сохраняя начальную запятую.
Примеры:
alex:psw:::1,1,Alex:79999999999:сообщение
alex:psw:::1:79999999999:сообщение
alex:psw:::,1:79999999999:сообщение
alex:psw:::,1,Alex:79999999999:сообщение
alex:psw:::,1,,1:79999999999:сообщение
Для отправки различных типов сообщений можно воспользоваться возможностью указания специальных префиксов в начале или вместо текста сообщения.
Поддерживаемые префиксы:
| Название | Описание
|
|---|
| __CALL__: сообщение | Отправка голосового сообщения (звонка). При отправке голосового сообщения в конце текста можно указать
специальную комбинацию "\n~~~\n" (перевод строки, 3 символа тильды и снова перевод строки), после которой передать параметр param,
определяющий некоторые характеристики звонка (более подробно можно посмотреть в описании).
| | __VIBER__: сообщение | Отправка сообщения пользователям мессенджера Viber.
| | __SOC__: сообщение | Отправка сообщения пользователям социальных сетей "Одноклассники", "ВКонтакте" или пользователям "Mail.Ru Агент".
| | __MAIL__: сообщение | Отправка E-mail сообщения.
| | __BOT__: сообщение | Отправка сообщения пользователям чат-бота Telegram.
| | __PING__ | Отправка специального SMS, не отображаемого в телефоне, для проверки номеров на доступность в реальном времени по статусу доставки.
| | __HLR__ | Признак HLR-запроса для получения информации о номере из базы оператора без отправки реального SMS.
|
Если была допущена ошибка в параметрах или произошла любая другая ошибка, и параметром test был запрошен
ответ, то он будет следующим:
- ERROR = N (описание) – для ошибок 1,2,4,5,9;
- ERROR = N (описание), ID - <id сообщения> – для ошибок 3,6,7,8.
N – номер ошибки, может принимать следующие значения:
| Значение | Описание
|
|---|
| 1 | Ошибка в параметрах.
|
|---|
| 2 | Неверный логин или пароль. Также возникает при попытке отправки сообщения с IP-адреса, не входящего в список разрешенных Клиентом (если такой список был настроен Клиентом ранее).
|
|---|
| 3 | Недостаточно средств на счету Клиента.
|
|---|
| 4 | IP-адрес временно заблокирован из-за частых ошибок в запросах. Подробнее
|
|---|
| 5 | Неверный формат даты.
|
|---|
| 6 | Сообщение запрещено (по тексту или по имени отправителя).
|
|---|
| 7 | Неверный формат номера телефона.
|
|---|
| 8 | Сообщение на указанный номер не может быть доставлено.
|
|---|
| 9 | Отправка более одного одинакового запроса на передачу SMS-сообщения в течение минуты.
|
|---|
В случае успешного принятия сообщения и запроса ответа параметром test возвращается строка следующего вида:
Где:
<n> – это количество отправленных SMS, вычисляемое как количество SMS в сообщении, умноженное на количество
получателей.
<id> – идентификатор сообщения, переданный Клиентом или назначенный Сервером автоматически.
Сервер не принимает более двух одинаковых запросов на отправку SMS-сообщений в течение
минуты для защиты от ошибок и зацикливаний в программе на стороне Клиента для того, чтобы снизить нагрузку и не расходовать
средства Клиента, а также не допустить многократной отправки сообщения одному абоненту.
Сервер также блокирует отправку более 50 сообщений одному абоненту, которые были отправлены с перерывом
между сообщениями менее 2-х минут, для защиты от флуда и лишнего списания средств со счета Клиента,
так как многие операторы не пропускают большое количество сообщений одному абоненту за короткий промежуток времени.
Отправка HLR-запроса
Для отправки HLR-запроса используйте команду обычной отправки SMS-сообщения, указывая format равным 3.
Параметр <mes> с текстом сообщения не используется и может быть пустым.
Результат запроса можно получить по HTTP-протоколу автоматическим вызовом обработчика или самостоятельно запросить статус
отправленного SMS-сообщения специальной командой. Так как HLR-запрос выполняется асинхронно, и результат может вернуться от оператора не сразу,
то при самостоятельном запросе статуса важно делать цикл из нескольких итераций с засыпанием (команда sleep).Функция E-mail2smsВ личном кабинете Клиента в "Настройках пользователя" имеется возможность указания списка номеров телефонов, на которые
будет происходить пересылка в виде SMS-сообщений текстов электронных писем, пришедших на адрес
ваш_логинsend.smsc.kz.
Данная функция может быть использована, например, для получения уведомлений на телефон о различных событиях из
программ или интернет-сервисов, в которых возможно указание только адреса E-mail. |
