HTTP - протокол

1. Параметры вызова скрипта

Чтобы отправить абоненту SMS-сообщение, вызовите скрипт (POST или GET):

http://api.greensms.ru/mt.cgi (либо https:// - по вашему выбору)
http://api2.greensms.ru/mt.cgi (либо https:// - по вашему выбору)

В параметрах передаются следующие обязательные параметры:

ИмяТипПример значенияОписание
userstring (<= 64 знака)HirfmВаш логин
passstring (<= 64 знака)dHjsWakВаш пароль
toarray [0-9] (<=2400 зн.)79165550055 или 79031234567,79051111111Номер(а) телефона(ов) получателя(ей) в международном формате: только цифры, без знака «плюс», код страны, код оператора, телефон. Если несколько номеров, то они разделяются запятыми.
txtstring (<= 2048 зн.)Съешь ещё этих французских булок!Текст отправляемого sms-сообщения (по умолчанию - в кодировке Windows-1251)

Пример запроса к скрипту:

http(s)://api.greensms.ru/mt.cgi?user=hitfm&pass=dHjsWak&to=79031234567
&txt=Съешь+еще+этих+французских+булок%21

или

http(s)://api.greensms.ru/mt.cgi?user=hitfm&pass=dHjsWak&to=79031234567
&txt=%D1%FA%E5%F8%FC%20%E5%F9%E5%20%FD%F2%E8%F5%20%F4%F0%E0
%ED%F6%F3%E7%F1%EA%E8%F5%20%E1%F3%EB%EE%EA%21

Внимание! Если вы передаете параметр «txt», содержащий спецсимволы (в том числе, пробел), вам нужно закодировать URI при помощи функции urlencode() или аналогичной.

Все сообщения должны передаваться скрипту в кириллице (кодировка 1251). Одно длинное сообщение может разбиваться на несколько SMS, за каждое из которых снимается отдельная плата. Одно SMS может содержать 70 символов с нелатинскими буквами (например, на русском) или 160 символов только с латинскими буквами. Для передачи более длинного сообщения оно разбивается на несколько SMS, и в каждое SMS добавляется специальный заголовок (UDH), позволяющий телефону объединить полученные части в одно длинное сообщение, и максимальная длина каждой SMS в этом случае становится 67 символов для нелатинских и 153 для латинских букв. Если всё в порядке, ответ скрипта будет таким:

<?xml version="1.0" ?>
<reply>
    <result>OK</result>
    <code>0</code>
</reply>

Если произошла ошибка, то параметр code будет больше нуля. В этом случае поле result содержит текстовое описание ошибки. Пример:

<?xml version="1.0" ?>
<reply>
    <result>PARAM ERROR (to)</result>
    <code>4</code>
</reply>

1.1 Коды ошибок

Код ошибкиЗначениеОписание
0OKОшибки нет. Сообщение принято.
1SYNTAX ERRORСинтаксическая ошибка в параметрах
2AUTH ERRORОшибка авторизации
3SYSTEM ERRORСистемная ошибка
4PARAM ERRORНеверное значение параметра
5NO MORE CREDITSИсчерпан баланс sms-сообщений

При возникновении любой из ошибок дальнейшую передачу данного сообщения следует прекратить и связаться со службой поддержки "Green-SMS"

1.2 Примеры функций на PHP и PERL

Пример простейшей функции рассылок на PHP:

<?php
    $response = file_get_contents('http(s)://api.greensms.ru/mt.cgi?user=hitfm&pass=dHjsWak&to=79031234567&txt='.urlencode('Съешь еще этих французских булок') );
    echo "$response";
?>

Пример функции на PERL (Необходимы библиотеки LWP и HTTP на сервере):

#!/usr/bin/perl
use LWP;
use HTTP::Request;
$request = HTTP::Request->new(GET=>"http(s)://api.greensms.ru/mt.cgi?user=hitfm&pass=dHjsWak".“&to=79031234567&txt=Съешь+еще+этих+французских+булок");
$ua = LWP::UserAgent->new(timeout=>60);
$response = $ua->request($request);
if(!$response->is_success) { print("ERR FALIED Request ".$response->status_line."\n"); }
else{ print "Reply:\n".$response->content; }

Примечание: 1. По умолчанию установлено ограничение для SMS-рассылок: 10 SMS/секунду. Если вам требуется более высокая скорость, сообщите об этом. 2. Если длина параметра txt превышает 70 символов, то сообщение будет автоматически разбито на части и передано абоненту как составное («склеенное»). 3. В параметре to вы можете передавать (через запятую) до 200 номеров получателей за один HTTP-запрос.

2. Расширенные функции системы "SMS-рассылки"

2.1 Дополнительные параметры скрипта

Помимо основного набора параметров, указанных в разделе 1, скрипту системы «sms-рассылки» могут быть переданы дополнительные параметры.

Опциональными являются следующие параметры:

ПараметрТипПример значенияОписание
Tidstring (<= 64 зн.)1234-aasvs-3345.1332Уникальный код SMS-сообщения в вашей системе. Используется для сверок статистики.
fromint или string (<=11 зн.)«GREENSMS» или «Tez-Tour»Имя отправителя SMS-сообщения – число или латинский текст до 11 символов включительно.
Utfint (0/1)0Кодировка параметра txt:\0 (по умолчанию) – Windows-1251\1 – кодировка Unicode (UTF-8)
Dlrint (0/1)00 (по умолчанию) – без отчета о доставке сообщения\1 – запросить отчет о доставке sms-сообщения (см. п. 2.4)
delayint (<=86400)0Задержка (в секундах) с момента отправки ордера на рассылку до ее фактической отправки
datetimestring (yyyy-dd-mm HH:MM)2012-13-05 18:00Отложенная отправка. Установление даты и времени фактической отправки рассылки (действует в случае отсутствия поля delay)
Tzint (-12, +11)0Смещение времени отправки относительно московского часового пояса

2.2 Подстановка "отправителя" SMS-сообщения

В параметре «from» вы можете передать числовое или символьное значение (только латинские буквы, цифры, пробелы, спецсимволы), до 11 символов включительно. Телефонный аппарат абонента отобразит значение этого параметра в поле «От:» (зависит от модели). Примеры:

От: 79031234567
От: HitFm 107.4
От: =Green.SMS=

Примечание 1: :Не все модели телефонов поддерживают корректное отображение спецсимволов (',”,`,~,=,|,\,#,$,%,&,<,> и др.) в поле «от кого», поэтому от их использования лучше воздержаться. Примечание 2: :В целях безопасности доставка сообщений с произвольными параметрами from без согласования с менеджером «GREENSMS» производиться не будет. После тестирования вы должны сообщить выбранный вами параметр from (от кого) вашему менеджеру или через форму обратной связи для закрепления данного имени за вами.

ЗАПРЕЩАЕТСЯ указывать в качестве отправителя короткие платные номера, номер получателя сообщений, а также названия операторов, чужих интернет-ресурсов, компаний и государственных организаций.

2.3 Отложенная отправка рассылки

Используйте параметр delay для того, чтобы отсрочить момент фактической отправки рассылки на определенное время. Указывается в секундах [≤86400].Если delay = 0 (по умолчанию), рассылка отправляется немедленно.

Отправка в указанный день и время. [yyyy-dd-mm HH:MM] В случае необходимости указать точную дату и время фактической отправки рассылки, используйте параметр datetime. Если datetime = 0 (по умолчанию), то сообщение будет отправлено немедленно.

tz - Часовой пояс, в котором задается параметр datetime. Указывается относительно московского времени. Параметр tz может быть как положительным, так и отрицательным. Если tz равен 0, то будет использован московский часовой пояс (мировое время +4 GMT по Гринвичу), если же параметр tz не задан, то часовой пояс будет взят из настроек Клиента в Личном кабинете на сайте www.greensms.ru (по умолчанию московское время)

Примечание:
Статистика в Личном кабинете также привязывается и отображается в соответствии с установленным часовым поясом в настройках аккаунта. По умолчанию установлено московское время.

2.4 Запрос отчета о доставке sms-сообщения (DLR, delivery-reports)

Система поддерживает передачу информации о статусе доставки SMS-сообщения абоненту. Если в запросе на отправку сообщения указывается параметр dlr=1, то в ответном XML-сообщении, помимо статуса, будет выдан идентификатор отправленного sms-сообщения (sms-id). Идентификаторов будет больше одного в случае отправки sms для нескольких абонентов в одном запросе. По полученному sms-id отдельным http-запросом можно узнать статус сообщения. Пример вызова скрипта рассылки с запросом DLR (для двух получателей):

http(s)://api.greensms.ru/mt.cgi?user=hitfm&pass=dHjsWak&to=79031234567,79165557755
&txt=Съешь+еще+этих+французских+булок%21&dlr=1

Ответ скрипта:

<?xml version="1.0" ?>
<reply>
    <result>OK</result>
    <code>0</code>
    <sms-id phone="79031234567">10000011.7777.1</sms-id>
    <sms-id phone="79165557755">10000011.7777.2</sms-id>
</reply>

Примечания:

  1. Значение параметра sms-id – символьное (не числовое) поле. В нем могут присутствовать цифры, символы латинского алфавита, знаки препинания (точки, тире, подчеркивание, знак решетки и др.)
  2. Система исправления ошибок автоматически конвертирует «некорректные» номера телефонов. Например, если будет передан параметр phone=8-495-111-2233, то будет произведено преобразование, и в отчете о доставке оригинальный номер телефона отображается следующей строкой в XML-ответе:
<sms-id phone="79031112233" origphone="8-495-111-2233" >10000011.7777.1</sms-id>

Обратите внимание, что из номера не только удаляются «лишние» символы (+, -, # и проч.), но и производится преобразование «городских номеров» (например, код 495) в «федеральные» (соответствующий код сотового оператора).

2.5 Получение статуса доставки sms-сообщения (DLR, 8. delivery-reports)

Для получения статуса следует сделать запрос к скрипту:

http://api.greensms.ru/dlr.cgi (либо https:// - по вашему выбору)
http://api2.greensms.ru/dlr.cgi (либо https:// - по вашему выбору)

В параметрах передаются следующие обязательные параметры:

ПараметрТипПример значенияОписание
userstring (<= 64 знака)HirfmВаш логин
passstring (<= 64 знака)dHjsWakВаш пароль
sms-idstring (<= 64 знака)10000011.7777.2Идентификатор отправленного sms-сообщения (полученный от mt.cgi)

Пример запроса статуса доставки:

http(s)://api.greensms.ru/dlr.cgi?user=hitfm&pass=dHjsWak&sms-id=10000011.7777.2

Ответ скрипта о статусе доставки:

<?xml version="1.0" ?>
<reply>
    <result>OK</result>
    <dlr sms-id="10000011.7777.2">
        <code>0</code>
        <status>delivered</status>
    </dlr>
</reply>

Здесь параметр result содержит информацию о результате отработки скрипта (OK или описание ошибки), а в блоке <dlr> - код и расшифровка статуса sms-сообщения.

2.6 Таблица статусов доставки sms-сообщений

CodeStatusОписаниеТип
0deliveredСообщение доставлено абонентуокончательный
1bufferedСообщение в очереди на отправкупромежуточный
2absentАбонент вне зоны сети. Сообщение в очереди.промежуточный
3preparingСообщение в процессе подготовки к отправлениюпромежуточный
4unknownНеизвестный статус (ответ от оператора не получен)промежуточный
-1not deliveredСообщение не доставлено (ошибка доставки)окончательный
-2expiredПросрочено, удалено (абонент недоступен 24ч.)окончательный
-3rejectedОтказ в передаче сообщения (неверный номер телефона)окончательный

Все отправленные сообщения приобретают окончательный статус не более, чем через 24 часа с момента отправки.