API

Настрой под свои нужды
Интеграция с QUICKTEL по API: просто и быстро
Рассылка SMS по протоколам HTTP, SMTP, SMPP, SOAP, XML, JSON-протоколам. Интегрируйте возможности платформы QUICKTEL в свой проект.

Протокол HTTP

Описание отсылки сообщений через протокол HTTP в системе.

Скачать примеры на PHP

Для работы с классом требуется PHP5

Входные параметры

Адрес обращенияhttps://service.qtelecom.ru/public/http/
Тип авторизацииPLAIN (открытым текстом)
Формат входных данныхContent-Type: application/x-www-form-urlencoded; charset=UTF-8 (по умолчанию)
Другие кодировкиПри использовании другой кодировки, отличной от UTF-8, требуется указать её в заголовке Content-Type запроса.
Например: Content-Type: application/x-www-form-urlencoded; charset=windows-1251
Результат : Content-Type: text/xml (UTF-8); content-encoding: gzip
Login/passwordСовпадают с login/password на web-сайт
Максимальная длина сообщений480 символов

1. Авторизация

Авторизация требуется при каждом подключении к серверу независимо от дальнейших действий.

userЛогин для входа в систему на сайте go.qtelecom.ru
passПароль для входа в систему на сайте go.qtelecom.ru
gzip=noneНе использовать content-encoding: gzip
HTTP_ACCEPT_LANGUAGEпеременная клиента, предпочтение относительно языка (необязательный параметр)
CLIENTADRIP адрес клиента (необязательный параметр)
commentописание подключения (необязательный параметр; до 512 символов)

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

SMS сообщение

Для отправки SMS необходимо вызвать методом GET или POST адрес:

https://service.qtelecom.ru/public/http/?action=post_sms&user=<user>&pass=<password>&target=<phones>&message=<message>

Описание обязательных параметров, передаваемых Серверу:

ПараметрЗначение
actionpost_sms
userЛогин
passwordПароль
targetСписок адресатов через запятую. (Пример: «+70010001212, 80009990000»).(Разрешается использование только или “target”, или “phl_codename”)
phl_codenameКодовое имя контакт-листа в системе https://go.qtelecom.ru.
(Разрешается использование только или “target” или “phl_codename”)
Также можно использовать параметр gender – фильтр по полу получателя. Значение: M / F (мужской / женский)
messageтекст сообщения

Описание дополнительных параметров, передаваемых Серверу:

ПараметрЗначениеПо умолчанию
senderимя отправителя, зарегистрированного для вас, в системе (NULL – имя отправителя по умолчанию)имя по умолчанию
post_idпользовательский ID рассылки, необязательный параметр, возвращается обратно в неизменном виде.
periodВремя жизни сообщения в секундах. Необязательный параметр. Максимальное время, в течение которого сообщение должно быть доставлено на телефон. Если в течение этого времени доставка не возможна (например абонент не в зоне действия сети), сообщение не будет доставлено вовсе. Внимание, данная функция может не работает для некоторых направлений, например для CDMA телефонов.
time_periodПериод отправки сообщения в формате «HH:mm-HH:mm(час:мин-час:мин)», в течение которого сообщение должно быть доставлено получателям (например 10:00-21:00). Опция позволяет запретить доставку сообщений, например, в ночное время. Для указанного периода времени можно уточнить часовой пояс в time_local00:00-00:00
time_localВыбор часового пояса для опции time_period. 1 – по местному время получателя, 0 – по часовому поясу, выбранному в личном кабинете отправителя.0
autotrimtexton – обрезать все пробелы и переводы строк в начале и конце сообщения.off
sms_typeТип SMS.
Пустое значение: Простое SMS
W: Wap push сообщение
F: Flash SMS сообщение
Пустое значение
wap_urlHTTP ссылка с текста сообщения (https://…..).
Используется только для sms_type = W, то есть Wap push сообщения.
wap_expiresДата и время, когда истекает срок доставки Wap push сообщения.
(Формат: dd.mm.yyyy hh:ii:ss (дд.мм.гггг чч:ми:сс))

3. Получение статусов сообщений асинхронно

Данный вариант позволяет получать статусы сообщений в реальном времени. Для настройки укажите в Личном кабинете → Услуги «URL скрипта для приёма статуса отправленных SMS». Как только система получает статус сообщения, она немедленно пересылает вам его по HTTP протоколу с помощью POST запроса.

Формат данных:

ORDIDНомер сообщения (номер соответствует значению атрибута ID тэга SMS, возвращаемого при отправке сообщения)
CNRIDID контрагента
RESCOUNTКоличество для тарификации
STATUSКод статуса (расшифровка кодов ниже)
FINALTIMEВремя получения финального статуса в UTC

Коды статуса:

  • 2 – сообщение доставлено
  • 3 – время попыток доставить сообщение оператором истекло
  • 5 – сообщение не может быть доставлено (ошибка в номере, номер не существует и т.д.)
  • 8 – сообщение не принято оператором
  • 20 – отправка была отменена пользователей
  • 21 – ошибка при работе по сообщению
  • 22 – оператор не сообщил о состоянии сообщения за отведенное время.

4. Получение данных и статусов сообщений

  • action = status

Три варианта получения статусов для сообщений:

sms_idДанные по одному сообщению
sms_group_idДанные по всем сообщениям за одну отсылку
date_from, date_to, smstypeДанные по всем сообщениям за период времени от date_from до date_to по типу сообщений smstype. (Формат date_from, date_to: dd.mm.yyyy hh:ii:ss (дд.мм.гггг чч:ми:сс))

Возможные варианты:

  • queued – сообщение в очереди отправки
  • wait – передано оператору на отправку
  • accepted – сообщение принято оператором
  • delivered – сообщение доставлено
  • not_delivered – сообщение не доставлено
  • failed – ошибка при работе по сообщению

5. Получение текущего баланса

  • action = balance

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

  • action = inbox
sib_numНомер входящего ящика (Обязательный параметр, соответствует значению «ID ящика» в закладке «Настройки»)
new_onlyСтатус сообщений:
  • 1 – только новые, непрочитанные сообщения0 – все сообщения
date_from, date_toДанные по всем сообщениям за период времени от date_from до date_to (Формат date_from, date_to: dd.mm.yyyy hh:ii:ss (дд.мм.гггг чч:ми:сс))

Примеры использования протокола

Пример 1. Отправка одного сообщения по адресатам

Запрос

POST= (
    [user] => userX
    [pass] => ***
    [action] => post_sms
    [message] => Привет
    [target] => +79999999991, +79999999992, +7999999999999
    [post_id] => x124127456
    [period] => 600
    [CLIENTADR] => 127.0.0.1
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
)

Результат XML

<output>
     <result>
     <sms post_id="x124127456" id="99991" smstype="SENDSMS"  phone="+79999999991" sms_res_count="1"><![CDATA[Привет]]></sms>
     <sms post_id="x124127456" id="99992"  smstype="SENDSMS"  phone="+79999999992" sms_res_count="1"><![CDATA[Привет]]></sms>
     </result>
     <errors>
     <error code="-20117" post_id="x124127456">Неправильный номер телефона: +7999999999999</error>
     </errors>
</output>

Использование PHP-класса

<?php
 Include('QTSMS.class.php');
 // Отправка SMS сообщения по списку адресатов
 $sms_text='Привет';
 $target='+79990001212, 80009990000';
 $sender='vasya';
 $period=600;
 
 $sms= new QTSMS('userX.Y','пароль');
 $result=$sms->post_message($sms_text, $target, $sender, 'x124127456',$period);
 // результат XML
 echo $result;  
 // Отправка SMS по кодовому имени контакт листа
 $sms_text='Привет';
 $phl_codename='druzya';
 $result=$sms->post_message_phl($sms_text, $phl_codename, $sender, 'x124127456',$period);
 header("Content-Type: text/xml; charset=UTF-8");
 // результат XML
 echo $result; 
?>

Пример 2. Получение данных сообщения id=6666

Запрос
POST= (    
    [action] => status    
    [sms_id] => 6666    
    [user] => userX    
    [pass] => ***    
    [CLIENTADR] => 127.0.0.1    
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
)
Результат XML
<output>
     <MESSAGES>
     <MESSAGE SMS_ID="6666" SMSTYPE="SENDSMS">
     <CREATED>24.12.07 15:57:45</CREATED> 
     <AUL_USERNAME>userX.Y</AUL_USERNAME> 
     <AUL_CLIENT_ADR>127.0.0.1</AUL_CLIENT_ADR> 
     <SMS_SENDER>SenderName</SMS_SENDER> 
     <SMS_TARGET>89999991111</SMS_TARGET> 
     <SMS_RES_COUNT>1</SMS_RES_COUNT> 
       <SMS_TEXT>
       <![CDATA[ Привет ]]> 
     </SMS_TEXT>
     <SMSSTC_CODE>wait</SMSSTC_CODE> 
     <SMS_STATUS>Сообщение в процессе доставки</SMS_STATUS> 
     <SMS_CLOSED>0</SMS_CLOSED> 
     <SMS_SENT>0</SMS_SENT> 
     </MESSAGE>
     </MESSAGES>
</output>
Использование PHP-класса
<?php
 // Получение статуса SMS сообщений
 Include('QTSMS.class.php');
 $sms= new QTSMS('userX.Y','пароль');
 // данные о сообщении SMS_ID=6666
 $r_xml1=$sms->status_sms_id(6666);
 // данные о сообщениях отправки SMS_GROUP_ID=110
 $r_xml2=$sms->status_sms_group_id(110);
 // Получить данные сообщений отправленных с 18.12.2007 00:00:00 по 23.12.2007      23:00:00
 $r_xml3=$sms->status_sms_date('18.12.2007 00:00:00','23.12.2007 23:00:00');
 header("Content-Type: text/xml; charset=UTF-8");
 echo $r_xml1; // результат XML
 //echo $r_xml2;
 //echo $r_xml3;
?>

Пример 3. Отправка сообщений и получение статусов

Запрос
POST= (
    [data] => Array (
            [0] => Array  (
                    [action] => post_sms
                    [message] => Привет!
                    [sender] => 
                    [target] => +79999999999, +79999999992
                )
            [1] => Array  (
                    [action] => post_sms
                    [message] => С днём рождения!
                    [sender] => 
                    [target] => +79999999991
                    [post_id] => x425256
                )
            [2] => Array  (
                    [action] => status
                    [sms_id] => 6666
                )
        )

    [user] => userX
    [pass] => ***
    [CLIENTADR] => 127.0.0.1
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
)
Результат XML
<output>
     <result sms_group_id="996">
        <sms id="99991" smstype="SENDSMS" phone="+79999999991" sms_res_count="1"><![CDATA[Привет]]></sms>
        <sms id="99992" smstype="SENDSMS" phone="+79999999992" sms_res_count="38"><![CDATA[С днём рождения!]]></sms>
     </result>
     <errors>
        <error code="-20117" post_id="x425256">Неправильный номер телефона: +7999999999999</error>
     </errors>
     <MESSAGES>
        <MESSAGE SMS_ID="6666" SMSTYPE="SENDSMS">
           <CREATED>24.12.07 15:57:45</CREATED> 
           <AUL_USERNAME>userX.Y</AUL_USERNAME> 
           <AUL_CLIENT_ADR>127.0.0.1</AUL_CLIENT_ADR> 
           <SMS_SENDER>SenderName</SMS_SENDER> 
           <SMS_TARGET>89999991111</SMS_TARGET> 
           <SMS_RES_COUNT>1</SMS_RES_COUNT> 
                   <SMS_TEXT>
                      <![CDATA[ Привет ]]> 
                 </SMS_TEXT>
           <SMSSTC_CODE>wait</SMSSTC_CODE> 
           <SMS_STATUS>Сообщение в процессе доставки</SMS_STATUS> 
           <SMS_CLOSED>0</SMS_CLOSED> 
           <SMS_SENT>0</SMS_SENT> 
        </MESSAGE>
     </MESSAGES>
</output>

Данные по сообщению:

  • SMS_ID – ID сообщения
  • SMS_GROUP_ID – ID рассылки сообщений
  • SMSTYPE – тип сообщения
  • CREATED – дата и время создания сообщения
  • AUL_USERNAME – Имя пользователя, создавшего сообщение
  • AUL_CLIENT_ADR – IP адрес пользователя, создавшего сообщение
  • SMS_SENDER – Имя отправителя сообщения
  • SMS_TARGET – Телефон адресата
  • SMS_RES_COUNT – Кол-во единиц ресурсов на данное сообщение
  • SMS_TEXT – Текст сообщения
  • SMSSTC_CODE – Код статуса доставки сообщения
  • SMS_STATUS – Текстовое описание статуса доставки сообщения
  • SMS_CLOSED – [0,1] 0 – сообщения находится в процессинге, 1 = работа по отправке сообщения завершена
  • SMS_SENT – [0,1] 0 – сообщение не отослано, 1 = сообщение отослано успешно
  • SMS_CALL_DURATION – Время, в течение которого было установлено соединение для отправки сообщения.
  • SMS_DTMF_DIGITS – Что пользователь нажимал в сеансе разговора (для SENDVOICE (в разработке))
  • SMS_CLOSE_TIME – Время завершения работы по сообщению.
Использование PHP-класса
<?php
 // Единый запрос 
 Include('QTSMS.class.php');
 $sms= new QTSMS('userX.Y','пароль');
 // !!! Команда на кеширование запросов
 $sms->start_multipost();    
 // Отправка смс 
 $sms->post_message('Привет', '+79999999991,+79999999992', 'Vasya');    
 // Отправка смс 
 $sms->post_message_phl('С днём рождения!', 'druzya', 'Petya', 'x425256');                           
 // данные о сообщении SMS_ID=6666
 $sms->status_sms_id(6666);
 // данные о сообщениях с SMS_GROUP_ID=110
 $sms->status_sms_group_id(110) ; 
 // !!! отправить всё одним запросом и получить результат в XML
 $r_xml=$sms->process();   
 header("Content-Type: text/xml; charset=UTF-8");
 echo $r_xml; // результат XML
?>

Пример 4. Получение баланса

Запрос
POST= (
    [user] => userX
    [pass] => ***    
    [action] => balance    
    [CLIENTADR] => 127.0.0.1    
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
)
Результат XML
<output>
     <BALANCE>
     <AGT_BALANCE>1000</AGT_BALANCE>    [текущее состояние счёта]
     <OVERDRAFT>100</OVERDRAFT>         [максимальных уход в минус]
     </BALANCE>
</output>
Использование PHP-класса
<?php
 Include('QTSMS.class.php');
 $sms= new QTSMS('XXXXX','пароль');
 
 // получение баланса
 $r_xml=$sms->get_balance();
 // результат в XML
 header("Content-Type: text/xml; charset=UTF-8");
 echo $r_xml; // результат XML
?>

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

Запрос
POST= (
    [user] => userX
    [pass] => ***    
    [action] => inbox
    [sib_num] => 123
    [date_from] => 12.01.2010 00:00:00
    [date_to] => 15.01.2010 12:00:00
)
Результат XML
<output>
  <RECEIVER AGT_ID="10XXX" DATE_REPORT="08.02.2010 14:10:42"/>
  <inbox>
    <MESSAGE SMS_ID="10001234235782138" SMSTYPE="RECVSMS">
      <CREATED>13.01.2010 18:08:29</CREATED>
      <SMS_SENDER>79670413211</SMS_SENDER>
      <SMS_TARGET>79037672810</SMS_TARGET>
      <SMS_RES_COUNT>1</SMS_RES_COUNT>
      <SMS_TEXT>test 1111</SMS_TEXT>
      <SMS_STATUS>N</SMS_STATUS>
    </MESSAGE>
    <MESSAGE SMS_ID="1000123312382134" SMSTYPE="RECVSMS">
      <CREATED>14.01.2010 18:03:03</CREATED>
      <SMS_SENDER>79670413211</SMS_SENDER>
      <SMS_TARGET>79037672810</SMS_TARGET>
      <SMS_RES_COUNT>1</SMS_RES_COUNT>
      <SMS_TEXT>qwerty 22</SMS_TEXT>
      <SMS_STATUS>N</SMS_STATUS>
    </MESSAGE>
  </inbox>
</output>
Использование PHP-класса
<?php
 Include('QTSMS.class.php');
 $sms= new QTSMS('XXXXX','пароль');
 
 // получение только новых входящих смс для ящика 134 
 $r_xml=$sms->inbox_sms(1, 134);
 // получение только новых входящих смс 
 // для ящика 134 c 10.01.2010 00:00:00  до 15.01.2010 00:00:00 
 // $r_xml=$sms->inbox_sms(0,134,'10.01.2010 00:00:00','15.01.2010 00:00:00'); 
 
 // результат в XML
 header("Content-Type: text/xml; charset=UTF-8");
 echo $r_xml; // результат XML
?>

Обработка ошибок

Коды ошибок тэга error:

20117Неправильный номер телефона.
20170Слишком большой текст сообщения. Максимальная длина не должна превышать 160 байт.
20171Не пройдена проверка текста сообщения на наличие недопустимых слов и/или фраз.
20158Отправитель или получатель в черном списке.
20167Сработало ограничение по отправке одинакового текста на один и тот же номер в течение небольшого промежутка времени. Обратитесь в поддержку, если хотите отключить или уменьшить период.
20144Нет доступного тарифа для запрашиваемого направления.
20147Нет подходящего тарифа у вышестоящего контрагента.
20174Политика маршрутизации не найдена.
20154Ошибка транспорта. При возникновении этой ошибки обратитесь в службу поддержки.
20148Не поддерживаемое направление.

qtsms.class.zip

Для работы с классом требуется PHP5

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