Тарифы  Услуги  API  Партнерам  О сервисе  Контакты 
8 (800) 080 7672
Бесплатно по Казахстану
 

Интеграция с сервисом (API)

API позволяет рассылать сообщения через ваши проекты и сервисы по протоколам HTTP/HTTPS, SMTP и SMPP. Готовые библиотеки на разных языках программирования подключаются к вашему проекту и помогают отправлять сообщения из любого места с помощью одной команды.


HTTP/HTTPS SMTP SMPP SOAP OMS SMS-команды Библиотеки и примеры кода

SMPP протокол

Подключение

Через наш SMS-шлюз возможно отправлять сообщения по протоколу SMPP версий 3.4 и 5.0.
Для получения доступа по SMPP-протоколу необходимо включить в настройках в группе "Настройки API" соответствующую опцию и добавить IP-адреса, с которых будете выполнять подключение, на этой странице.

Адрес SMPP-сервера: smpp.smsc.kz, порт: 3700.
Для шифрованного SSL-подключения используется порт 3443.

Адрес резервного SMPP-сервера: smpp2.smsc.kz.

Пример настроек для подключения (формат kannel): group = smsc
smsc = smpp
smsc-id = smsc
host = smpp.smsc.kz
port = 3700
smsc-username = <login>
smsc-password = <password>
system-type = ""
interface-version = 34
source-addr-autodetect = yes
source-addr-ton = 5
source-addr-npi = 1
dest-addr-ton = 1
dest-addr-npi = 1
validityperiod = 1440
transceiver-mode = true
receive-port = 0
enquire-link-interval = 60
wait-ack-expire = 0
max-pending-submits = 300
throughput = 30

Максимально возможный интервал бездействия составляет 2 минуты. В течение этого времени Клиенту необходимо отправить сообщение или выполнить пустую команду ENQUIRE_LINK, иначе соединение будет разорвано из-за не активности.


Пример дополнительных настроек для подключения по SSL-протоколу (kannel версии 1.4.4 и выше): ...
port = 3443
ssl-client-certkey-file = "/etc/kannel.pem"
use-ssl = 1
...

Сертификат можно сгенерировать командой (Linux CentOS): /etc/ssl/certs/make-dummy-cert kannel.pem

Логин используется от личного кабинета, пароль должен быть создан на странице Пароли для доступа. Логин и пароль не должны быть на русском языке.
Данный раздел содержит только краткое описание SMPP-протокола. Подробности смотрите в спецификации.

Скачать спецификацию протокола SMPP v3.4 smpp34.zip (500 Кб) smpp34rus.zip (1,1 Mб).

Скорость рассылок

Пропускная способность подключения или количество отправляемых каждую секунду SMS-сообщений зависит от размера окна передачи (smpp window size). В примере настроек данный параметр называется max-pending-submits. Для массовых рассылок лучше задавать большие значения (1000-2000). Также в примере параметр throughput задает ограничение на максимальное количество SMS-сообщений в секунду.

Вместе с массовыми рассылками через одно подключение можно отправлять и срочные одиночные SMS-уведомления. Система установит максимальный приоритет таким сообщениям и отправит их раньше любых массовых рассылок без ожидания в очереди.

При массовой отправке сообщений не стоит забывать о системе контроля скорости отправки сообщений в секунду, при превышении которой происходит генерация ошибки превышения скорости (throttling). В случае получения данной ошибки Клиенту по SMPP-стандарту необходимо повторить отправку, снизив общую скорость на своей стороне. По умолчанию скорость задана 30 SMS/cек для каждого аккаунта. Для изменения максимально разрешенной скорости необходимо отправить запрос в службу поддержки сервиса.

Множественные подключения

По умолчанию сервер обрабатывает одновременно с одного логина только одно подключение для более корректной отдачи статусов, поэтому при повторном подключении ранее подключенное соединение с таким же логином будет автоматически завершаться. Если же необходимо иметь несколько одновременных подключений для повышения скорости отправки, то можно в настройках всех подключений задать следующий параметр (multi connection):
system-type = "MCON2"
или
system-type = "MCON9"
Значение после MCON может быть от 1 до 9 и задает количество одновременных подключений.

Также возможны одновременные подключения с разными логинами, привязанными к одному личному кабинету и счету. Для этого необходимо создать в личном кабинете в разделе "Реселлер" дополнительные аккаунты с необходимым типом субаккаунта.

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

Отправка SMS-сообщения

Для отправки SMS-сообщения используйте команду SUBMIT_SM согласно спецификации.

Поддерживаются следующие кодировки:
  • 7-битная GSM для латинского текста с поддержкой европейских символов − (coding = 0);
  • 8-битная ISO-8859-1 (ASCII) для латинского текста или бинарных данных − (coding = 1);
  • UCS2 (UCS-2BE или UTF-16BE) для национальных алфавитов (например, русского) − (coding = 2).
Поле coding кодируется двумя битами в составном поле data_coding, поэтому data_coding = coding * 4.

Для использования кодировки ISO-8859-1 (ASCII) вместо GSM при подключении нужно указать:
system-type = "ISO"
В текст SMS-сообщения можно добавлять комментарии, предназначенные для просмотра отправителем истории сообщений в личном кабинете.

Команда SUBMIT_MULTI для множественной рассылки пока не реализована.

Сервер не принимает более одного одинакового запроса на отправку SMS-сообщений в течение минуты для защиты от ошибок и зацикливаний в программе на стороне Клиента для того, чтобы снизить нагрузку и не расходовать средства Клиента, а также не допустить многократной отправки сообщения одному абоненту.

Сервер также блокирует отправку более 50 сообщений одному абоненту, которые были отправлены с перерывом между сообщениями менее 30-ти секунд, для защиты от флуда и лишнего списания средств со счета Клиента, так как многие операторы не пропускают большое количество сообщений одному абоненту за короткий промежуток времени.

При отправке составного сообщения все SMS-части должны быть переданы на сервер в течение минуты. В противном случае оператор может отклонить сообщение, так как для проверки на фильтры и шаблоны все SMS-части предварительно необходимо склеить, и большинство операторов ожидает не более минуты.

Комментарии в SMS-сообщениях

При отправке SMS-сообщений можно добавлять в конец текста любой комментарий, уточняющий либо дополняющий SMS-сообщение для отправителя. Данный текст не будет отправляться абонентам и влиять на стоимость SMS и доступен для просмотра и фильтрации в списке отправленных сообщений в личном кабинете.

Для добавления комментария необходимо в конце текста SMS-сообщения, предназначенного для отправки, указать специальную комбинацию "\n~~~\n" (перевод строки, 3 символа тильды и снова перевод строки), и после этого любой текст, который будет считаться комментарием, не будет отправлен абоненту, но отобразится в истории.

Отправка MMS-сообщения

Для отправки MMS-сообщения используйте команду SUBMIT_SM с текстом "__MMS__: <message>\nsubj:<subject>" (текст "__MMS__", двоеточие, пробел, текст сообщения, перевод строки, текст "subj", двоеточие, тема MMS-сообщения).

Отправка e-mail сообщения

Для отправки e-mail сообщения используйте команду SUBMIT_SM с текстом "__MAIL__: <message>\nsubj:<subject>" (текст "__MAIL__", двоеточие, пробел, текст сообщения, перевод строки, слово "subj", двоеточие, тема e-mail сообщения).

Отправка голосового сообщения (звонок)

Для отправки голосового сообщения используйте команду SUBMIT_SM с текстом "__CALL__: <message>\nvoice:<voice>" (текст "__CALL__", двоеточие, пробел, текст сообщения, перевод строки, слово "voice", двоеточие, голос, используемый для озвучивания текста).

Возможные значения для используемого голоса:
  • m – мужской голос.
  • m2 – мужской голос 2.
  • m3 (по умолчанию) – мужской голос 3.
  • m4 – мужской голос 4.
  • w – женский голос.
  • w2 – женский голос 2.
  • w3 – женский голос 3.
  • w4 – женский голос 4.
При отправке сообщений также возможно указание языка озвучивания текста в виде: "m,en", "w,fr", "w,de" и т.п.

В процессе формирования сообщения в конце текста можно указать специальную комбинацию "\n~~~\n" (перевод строки, 3 символа тильды и снова перевод строки), после которой передать параметр param, определяющий некоторые характеристики звонка (более подробно можно посмотреть в описании).

Отправка viber-сообщения

Для отправки viber-сообщения используйте команду SUBMIT_SM с текстом "__VIBER__: <message>" (текст "__VIBER__", двоеточие, пробел, текст сообщения).

При формировании текста сообщения можно использовать специальные макросы для создания кнопки, при нажатии на которую будет происходить открытие браузера и переход по указанной в макросе ссылке, а также прикреплять файлы. Более подробно дополнительные возможности при отправке viber-сообщений описаны в документации к http-протоколу.

Отправка soc-сообщения

Для отправки soc-сообщения, отправляемого пользователям социальных сетей "Одноклассники", "ВКонтакте" или пользователям "Mail.Ru Агент", используйте команду SUBMIT_SM с текстом "__SOC__: <message>" (текст "__SOC__", двоеточие, пробел, текст сообщения).

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

Для отправки сообщения в чат-бот Telegram используйте команду SUBMIT_SM с текстом "__BOT__: <message>\nbot:@<bot_name>" (текст "__BOT__", двоеточие, пробел, текст сообщения, перевод строки, текст "bot", двоеточие, имя бота).

Отправка HLR-запроса

Для отправки HLR-запроса используйте команду SUBMIT_SM с текстом __HLR__. Результат запроса приходит в обычном статусе (Delivery Report), который можно получить как по SMPP-подключению, так и по HTTP на свой обработчик.

Формат статуса с результатом HLR-запроса, возвращаемого по SMPP: id:<id> stat:<status> err:<err> imsi:<imsi> msc:<msc> mcc:<mcc> mnc:<mnc> cn:<cn> net:<net> rcn:<rcn> rnet:<rnet>
Описание параметров:

ПараметрЗначение
idИдентификатор сообщения.
statusСтатус сообщения.
errКод ошибки, если абонент недоступен (список).
imsiУникальный код IMSI SIM-карты абонента.
mscНомер сервис-центра оператора, в сети которого находится абонент.
mccЧисловой код страны абонента.
mncЧисловой код оператора абонента.
cnНазвание страны регистрации абонента.
netНазвание оператора регистрации абонента.
rcnНазвание роуминговой страны абонента при нахождении в чужой сети.
rnetНазвание роумингового оператора абонента при нахождении в чужой сети.

Строковые данные, например, страна и оператор, закодированы через функцию urlencode.

Пример результата HLR-запроса: id:855469 stat:DELIVRD err:000 imsi:250023012345678 msc:79232510066 mcc:250 mnc:02 cn:Russian+Federation net:MegaFON+open+Joint+Stock+Company rcn: rnet:
Пример кода на PHP для разбора строки с результатом HLR-запроса:
$dlr = strtr($dlr, ": ", "=&"); // $dlr - строка статуса
parse_str($dlr, $m); // $m - массив параметров, $m["id"], $m["err"], $m["imsi"] и тд.

Пример разбора через регулярные выражения:
preg_match("/^id:(\d+) stat:(\w+) err:(\d+) imsi:(\d*) msc:(\d*) mcc:(\d*) mnc:(\d*) cn:([^ ]*) net:([^ ]*) rcn:([^ ]*) rnet:([^ ]*)/", $dlr, $m); // $dlr - строка статуса
for ($i = 6; $i <= 9; $i++)
   
$m[$i] = urldecode($m[$i]);
// $m - массив параметров, $m[1] = id, $m[2] = status, $m[3] = err и тд.

Для отправки Ping-SMS используйте команду SUBMIT_SM с текстом __PING__.

Проверка статуса

Получать статус доставки отправленного SMS-сообщения по SMPP-протоколу можно как в автоматическом режиме, получая от сервера ответную PDU-команду DELIVER_SM сразу после изменения статуса, так и по запросу отдельной командой QUERY_SM. Для автоматического получения статуса по SMPP-протоколу необходимо подключаться в режиме transceiver или receiver и при отправке SMS указывать флаг запроса статуса (registered_delivery). Если при отправке не указывать данный флаг, то статусы сообщений будут передаваться на HTTP-обработчик.

При автоматическом возврате статуса в команде DELIVER_SM передаются стандартные TLV-параметры receipted_message_id (<id>), message_state (числовой <status>) и network_error_code (<err>), а также дополнительные TLV-поля, описанные ниже:

Имя (код) поляРазмерТипОписание
8192 (0x2000)Var. max 6COctet StringСтоимость сообщения в формате "n.nnnn".
8193 (0x2001)2IntegerФлаг в виде 2-х байтового числа, содержащий различную информацию о сообщении. Возможны комбинации значений битов разных характеристик.

Биты 0-3 (тип сообщения):
0 (по умолчанию) – SMS.
1 – Flash-SMS.
2 – Бинарное SMS.
3 – Wap-push.
4 – HLR-запрос.
5 – Ping-SMS.
6 – MMS.
7 – Звонок.
8 – E-mail.
10 – Viber.
12 – Соцсети.


Бит 5 – оплата сообщения со второго баланса.
Бит 8 – признак шаблонного сообщения.

Биты 10,9 – тип шаблонного сообщения:
00 - сервисное.
01 - транзакционное.
10 - авторизационное.
11 - рекламное.
8194 (0x2002)2IntegerКоличество частей в сообщении.
8195 (0x2003)Var. max 5COctet Stringmccmnc код страны/оператора абонента.
8196 (0x2004)2IntegerДополнительный статус сообщения (2 – прочитано, 4 – нажата ссылка).

Также в команде DELIVER_SM передается текст статуса в следующем формате:
id:<id> sub:<sub> dlvrd:<dlvrd> submit date:<submit date> done date:<done date> stat:<status> err:<err>
Описание параметров:

ПараметрЗначение
idИдентификатор сообщения, назначенный сервером при отправке.
subКоличество SMS частей в отправленном сообщении.
dlvrdКоличество доставленных SMS.
submit dateДата отправки.
done dateДата изменения статуса.
statusСтатус сообщения в виде строки (DELIVRD, EXPIRED, UNDELIV).
errКод ошибки, если сообщение не может быть доставлено (список).

Пример результата строки статуса (Delivery Report): id:854019 sub:001 dlvrd:001 submit date:1108202241 done date:1108202241 stat:DELIVRD err:000

По умолчанию для длинных сообщений, разбиваемых на несколько SMS, сервер возвращает только один статус (DELIVER_SM) для всего склеенного сообщения и одинаковые ID в ответе SUBMIT_SM_RESP для всех SMS-частей данного сообщения. Для включения режима обработки и возврата статусов для каждой SMS-части отдельно установите следующий параметр в настройках подключения (либо в настройках личного кабинета): system-type = "SINGLE"
Если необходимо указать несколько параметров в поле system-type, то укажите их через запятую: system-type = "ISO,SINGLE"

Получение входящих сообщений

Для включения пересылки входящих SMS-сообщений по SMPP-подключению необходимо установить галочку "Передавать входящие SMS по SMPP-подключению" в настройках личного кабинета (раскрывающаяся вкладка "Настройки API") либо обратиться в службу поддержки. При этом передача входящих сообщений на обработчик Клиента должна быть отключена.

Входящие сообщения приходят в PDU-команде DELIVER_SM. Для получения необходимо подключаться к SMPP-серверу в режиме transceiver или receiver.

Коды ошибок в статусе

Возможные коды ошибок в статусе сообщений или HLR-запросов (значения <err>):

КодНазваниеОписание
0Нет ошибкиАбонент существует и доступен.
1Абонент не существуетУказанный номер телефона не существует.
6Абонент не в сетиТелефон абонента отключен или находится вне зоны действия сети.
11Не подключена услугаОзначает, что абонент не может принять SMS-сообщение. Например, услуга не подключена, или абонент находится в роуминге, где не активирован прием сообщений, или у оператора абонента не налажен обмен SMS с текущим роуминговым оператором. Также это может быть городской номер без приема сообщений.
12Ошибка в телефоне абонентаНе удается доставить сообщение абоненту из-за ошибки в телефонном аппарате или SIM-карте.
13Абонент заблокированВозникает, например, если на счету абонента нулевой или отрицательный баланс, и он находится в роуминге, или заблокирован оператором за продолжительную неуплату либо добровольно самим абонентом. Также данная ошибка может возвращаться при повреждении SIM-карты либо неправильном вводе PIN и PUK-кодов SIM-карты.
21Нет поддержки сервисаАппарат абонента не поддерживает работу с данной услугой (сервисом).
200Виртуальная отправкаДанное уведомление появляется под статусом сообщения в случае отправки сообщения в режиме тестирования (при установленной в настройках галочке "Режим тестирования (виртуальная отправка без оплаты)").
219Замена sim-картыОшибка отправки сообщения в связи с заменой абонентом sim-карты. После физической замены sim-карты абоненту заблокирован прием сообщений от буквенных имен отправителей на 24 часа. Блокировка может быть снята путем пополнения баланса на 100 рублей.
220Переполнена очередь у оператораУказанная ошибка может возникать в случае, когда абонент недоступен для приема SMS, но сообщения продолжают приходить оператору и происходит переполнение внутренней очереди сообщений для данного абонента. В редких случаях возможно появление ошибки в результате сбоя в сети самого оператора или переполнении общей очереди сообщений. Во всех подобных ситуациях система с определенными интервалами несколько раз пытается отправить указанные сообщения повторно.
224Недостаточно средствНа счете Клиента недостаточная сумма для отправки сообщения.
237Абонент не отвечаетВозникает, если в процессе попытки дозвона абонент не взял трубку.
238Нет шаблонаВозникает, если отправка сообщения возможна только по определенному шаблону, а отправляемое сообщение ему не удовлетворяет.
239Запрещенный ip-адресВозникает при попытке отправки сообщения с ip-адреса, не входящего в список ip-адресов, разрешенных Клиентом для отправки. Также может возникать при попытке отправки сообщения с ip-адреса, ранее не используемого для отправки сообщений и входов в личный кабинет.
240Абонент занятВозникает при передаче голосового сообщения абоненту, если линия занята или абонент отменил вызов.
241Ошибка конвертацииПри преобразовании текста или звукового файла в конечный формат для передачи абоненту голосового сообщения произошла ошибка конвертации звука. Также данная ошибка может возникать при передаче SMS-сообщения отдельными частями, когда оператору переданы не все части.
242Зафиксирован автоответчикОзначает, что во время отправки голосового сообщения на стороне абонента был зафиксирован автоответчик.
243Не заключен договорВозникает при попытке отправки рассылок рекламного или массового характера без заключенного договора.
244Рассылка запрещенаОзначает, что для данного Клиента запрещена отправка массовых и рекламных рассылок, либо в тексте сообщения встретилась запрещенная ссылка.
245Статус не полученВ течение суток статус доставки не был получен от оператора, в этом случае нельзя точно сказать, было сообщение доставлено или нет.
246Ограничение по времениЕсли в личном кабинете в пункте "Настройки" во вкладке "Лимиты и ограничения" установлено "Время отправки" и галочка "запретить отправку в другое время", то при попытке отправки SMS-сообщений в период времени, отличный от указанного в поле "Время отправки", отправка сообщений будет запрещаться с указанием данной ошибки.
247Превышен лимит сообщенийПревышен общий суточный лимит сообщений, указанный Клиентом в личном кабинете в пункте "Настройки".
248Нет маршрутаОзначает, что на данный номер отправка сообщений недоступна в нашем сервисе. Например, ввели несуществующий мобильный код, либо для указанного номера и текста нет рабочего SMS-шлюза.
249Неверный формат номераВозникает, когда мобильный код указанного номера и соответствующая этому коду длина номера неверны.
250Номер запрещен настройкамиНомер попал под ограничения, установленные Клиентом для мобильных номеров в личном кабинете в пункте "Настройки".
251Превышен лимит на один номерПревышен суточный лимит сообщений на один номер. Лимит устанавливается Клиентом в личном кабинете в пункте "Настройки". Также такая ошибка возможна при отправке более 50 сообщений одному абоненту, которые были отправлены с перерывом между сообщениями менее 30 секунд.
252Номер запрещенВозникает, например, при попытке указания Клиентом одного из наших федеральных номеров в качестве получателя SMS-сообщения.
253Запрещено спам-фильтромЕсли текст сообщения содержит нецензурные выражения и оскорбления, призывы отправить sms и некоторые другие запрещенные тексты, то отправка сообщения заблокируется. Также запрещено указывать в качестве отправителя короткие платные номера, номер получателя сообщений, названия операторов, чужих интернет-ресурсов, компаний и государственных организаций.
254Незарегистрированный sender idДанная ошибка возникает при попытке отправки сообщения от незарегистрированного имени отправителя.
255Отклонено операторомОператор отклонил сообщение без указания точного кода ошибки.
Такое бывает, например, когда номер не принадлежит ни одному мобильному оператору, т.е. с несуществующим кодом, либо по какой-то другой причине оператор не может доставить сообщение.

Возможные коды ошибок в статусе e-mail сообщений (значения <err>):

КодНазваниеОписание
0Нет ошибкиПолучатель существует и доступен.
1Адресат не существуетУказанный e-mail адрес не существует.
2Переполнен почтовый ящикПочтовый сервер получателя отклонил сообщение с указанным кодом ошибки.
3Сервер получателя не найденДомен, указанный в качестве почтового сервера, не найден.
4Почтовый ящик заблокированОт почтового сервера получателя вернулась ошибка о невозможности доставки сообщения по причине блокировки ящика.
239Запрещенный ip-адресВозникает при попытке отправки сообщения с ip-адреса, не входящего в список ip-адресов, разрешенных Клиентом для отправки. Также может возникать при попытке отправки сообщения с ip-адреса, ранее не используемого для отправки сообщений и входов в личный кабинет.
245Статус не полученВ течение суток статус доставки не был получен от почтового сервера получателя, в этом случае нельзя точно сказать, было сообщение доставлено или нет.
248Нет маршрутаОзначает, что на данный e-mail адрес отправка сообщений недоступна в нашем сервисе. Например, для указанного адреса и текста нет рабочего e-mail шлюза.
249Неверный формат адресаВозникает, когда ввели некорректный по формату e-mail адрес получателя.
252E-mail адрес запрещенВозникает, например, при нахождении указанного e-mail адреса в черном списке.
253Запрещено спам-фильтромЕсли текст сообщения содержит нецензурные выражения и оскорбления, призывы отправить sms или e-mail и некоторые другие запрещенные тексты, то отправка сообщения заблокируется. Также запрещено указывать в качестве отправителя e-mail адрес получателя сообщения, адреса чужих интернет-ресурсов, компаний и государственных организаций.
254Незарегистрированный отправительДанная ошибка возникает при попытке отправки сообщения от незарегистрированного e-mail адреса отправителя.
255Отклонено сервером получателяПочтовый сервер получателя отклонил сообщение без указания точного кода ошибки.
Такое бывает, например, при возникновении внутренней ошибки сервера, когда он не может обработать сообщение.



© 2003–2024 ТОО «СМС-центр»
Рег.номер 2207-1910-01-ТОО
support@smsc.kz
Контакты
Дизайн — Студия Артемия Лебедева
Информация о сайте
SMS-центр для Android Яндекс.Метрика