Отправка смс по протоколу http, api для разработчиков
Смс http, в свою очередь, – это вид сообщения, которое было перекодировано для отправки. Кроме того, задействовать протокол HTTP можно и для того, чтобы отправить или обработать сообщения автоматически. Для этого необходимо внедрить соответствующий код в программную часть вашего сайта или ПО.
В спектр возможностей по настройке протокола входит:
- получение статуса доставки сообщения;
- автоматизированная отправка одного сообщения по базе данных;
- обработка ошибок и т.д.
Узнать о технических тонкостях и помочь в настройке необходимых параметров помогут специалисты Smsorg.ru, предоставляющие услуги массовых рассылок. С нашими знаниями каждый клиент получит максимум эффекта и качества отправки смс http.
Протокол HTTP (SMS). Его применение для отправки / обработки сообщений.
Описание отсылки SMS сообщений через протокол HTTP.
Данный протокол используется в веб-разработке и представлен, как правило, определенным набором HTTP-запросов и HTTP-ответов.
Для работы класса требуется PHP 5
Входные параметры
- Тип авторизации: 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
- Максимальная длина сообщений : 480 символов.
1. Авторизация
Авторизация требуется при каждом подключении к серверу независимо от дальнейших действий.
Параметр | Значение | По умолчанию |
user
| Логин для входа в систему на сайте
| -
|
pass
| Пароль для входа в систему на сайте
| -
|
gzip
| none - не использовать Content-encoding: gzip | none
|
HTTP_ACCEPT_LANGUAGE
| Переменная клиента, предпочтение относительно
языка (необязательный параметр). | -
|
CLIENTADR | IP адрес клиента (необязательный параметр) | IP сервера
|
comment
| Описание подключения (необязательный параметр;
до 512 символов) | -
|
2. Отправка сообщения
SMS сообщение
Параметр | Значение | По умолчанию |
action | post_sms | -
|
message | текст сообщения | -
|
target
| Список адресатов через запятую. (Н-р: «+70010001212,
80009990000»). (Разрешается использование только или "target", или "phl_codename") | -
|
phl_codename
| Кодовое имя контакт-листа в системе http://lcab.smsorg.ru.
(Разрешается использование только или "target" или "phl_codename") | -
|
sender
Имя отправителя, зарегистрированного для Вас в системе http://lcab.smsorg.ru. | Имя
отправителя по умолчанию | |
post_id
| пользовательский ID рассылки, необязательный параметр,
возвращается обратно в неизменном виде. | -
|
period
| Время жизни сообщения в секундах. Необязательный
параметр. Максимальное время, в течение которого сообщение должно быть доставлено на телефон. Если в течение этого времени доставка не возможна (например, абонент не в зоне действия сети), сообщение не будет доставлено вовсе. Внимание, данная функция может не работает для некоторых направлений, например для CDMA телефонов. | -
|
sms_type
| Тип SMS:
| Пустое
значение |
wap_url
| HTTP ссылка с текста сообщения (http://.....).
Используется только для sms_type = W, то есть Wap push сообщения. | -
|
wap_expires
| Дата и время, когда истекает срок доставки Wap push
сообщения. (Формат: dd.mm.yyyy hh:ii:ss (дд.мм.гггг чч:ми:сс)) | -
|
3. Получение статусов сообщений асинхронно
Данный вариант позволяет получать статусы сообщений в реальном времени. Для настройки укажите в Личном кабинете > Услуги «URL скрипта для приёма статуса отправленных SMS».Как
только система получает статус сообщения, она немедленно пересылает вам его по HTTP протоколу с помощью POST запроса.
Формат данных:
Параметр | Значение
|
ORDID
| Номер сообщения (соответствует значению атрибута ID тэга SMS, возвращаемого
при отправке сообщения) |
CNRID | ID контрагента
|
RESCOUNT | Количество сообщений для тарификации.
|
STATUS
| Код статуса:
существует и т.д.) |
FINALTIME | время получения финального статуса в UTC
|
4. Получение данных и статусов сообщений
action = status
Три варианта получения статусов для сообщений:
Параметр | Значение
|
sms_id
| Номер сообщения (соответствует значению атрибута ID тэга SMS,
возращаемого при отправке сообщения) |
sms_group_id
| Номер рассылки (соответствует значению атрибута sms_group_id тэга result,
возращаемого при отправке сообщений) |
date_from,
date_to | Данные по всем сообщениям за период времени от date_from до date_to.
(Формат date_from, date_to: dd.mm.yyyy hh:ii:ss (дд.мм.гггг чч:ми:сс)) |
5. Получение текущего баланса
Параметр | Значение
|
action | balance
|
6. Получение входящих сообщений
Параметр | Значение
| По
умолчанию |
action | inbox | -
|
sib_num
| Номер входящего ящика
(Обязательный параметр, соответствует значению "ID ящика" в закладке "Настройки") | -
|
new_only
| Статус сообщений:
| 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-класса
<?phpInclude('QTSMS.class.php');
// Отправка SMS сообщения по списку адресатов
$sms_text='Привет';
$target='+79999999991, +79999999992, +7999999999999';
$sender='vasya';
$period=600;
$sms= new QTSMS('userX.Y','пароль','lcab.smsorg.ru');
$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','пароль','service.qtelecom.ru');
// данные о сообщении 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
)
[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>
<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','пароль','lcab.smsorg.ru');
// !!! Команда на кеширование запросов
$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-класса
<?phpInclude('QTSMS.class.php');
$sms= new QTSMS('XXXXX','пароль','lcab.smsorg.ru');
// получение баланса
$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-класса
<?phpInclude('QTSMS.class.php');
$sms= new QTSMS('XXXXX','пароль','lcab.smsorg.ru');
// получение только новых входящих смс для ящика 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:160 байт.
фраз.
течение небольшого промежутка времени. Обратитесь в поддержку, если хотите
отключить или уменьшить период.
поддержки.
Скачать примеры на PHP
Для работы класса требуется PHP 5__
Метки: http смс, http sms, протокол http отправка sms сообщений;