Документация по коротким номерам
1. Термины
2. Общая схема взаимодействия
3. Выбор префикса
4. Обработчик
| Термин | Описание |
|---|---|
| МТ-сообщение (Mobile Terminated) | sms-сообщение от сервера в сторону абонента. |
| МO-сообщение (Mobile Originated) | sms-сообщение от абонента в сторону сервера. |
| Короткое сообщение (short message) | sms-сообщение до 70 символов включительно. |
| Составное сообщение (long message) | sms-сообщение длиной свыше 71 символа. |
| Фродовое сообщение | sms-сообщение не оплаченное оператором. |
2. Общая схема взаимодействия
Схема работы sms-сервисов: в момент прихода SMS-сообщения от пользователя сервер вызывает ваш скрипт (PERL, PHP и пр.), и передает ему текст SMS и прочие параметры. То, что ваш скрипт выдаст в ответ (текст), будет отправлено пользователю в ответной SMS (MT).
Для того чтобы запрос был передан именно вашему обработчику, SMS-сообщение абонента должно начинаться с определенного префикса (ключевого слова). После префикса пользователь может написать любой текст или числовой код – он будет также передан Вашему скрипту в качестве одного из параметров.
Фродовые SMS не оплачиваются оператором. Причиной этому может служить отрицательный баланс абонента на конец месяца или превышение фрод-лимита - установленной частоты приема SMS.
Текущий фрод-лимит на всех коротких номерах - 2 SMS в 5 минут.
3. Выбор префикса
Префикс может содержать любые русские (А-Я), латинские (A-Z) символы, цифры
(0-9), знаки '+', '-', ‘#’, ‘@’ и пр. Минимальная длина префикса:
- 3 символа, если количество запросов в месяц по нему составляет не менее 1000 шт.
- 4 символа – без ограничений по числу запросов в месяц
В случае использования прямых префиксов длины 4 и более символов, пробел после префикса не обязателен. Регистр букв не важен в любом случае.
При обработке префикса в системе «AvisoSMS» автоматически проверяется как его русское, так и латинское (транслитерированное) написание. Например, при подключении префикса с русскими буквами «а» и «о» в тексте SMS будут распознаваться также и идентичные им английские «a» и «o».
4. Обработчик (скрипт)
До начала тестирования сервиса вам следует установить на своем сайте скрипт, который будет принимать адресованные вам sms-сообщения и корректно их обрабатывать. Метод вызова – POST или GET по вашему выбору (По умолчанию – GET). В параметрах скрипту передаются следующие обязательные параметры:
| Пример сообщения |
|---|
|
Пример: Абонент (Россия, «Билайн») отправляет сообщение на номер 8385 с текстом: ХитФМ Передайте Привет Мне! |
Ваш скрипт получит данные, которые можно описать следующей таблицей:
| Имя переменной | Тип | Пример | Описание |
|---|---|---|---|
| pref | string | hitfm | Ключевое слово (префикс) в латинице, нижний регистр |
| txt | string | Передайте Привет Мне! | Текст сообщения после ключевого слова (в кодировке 1251). Может быть пустым, если абонент отправит в SMS только префикс. |
| tid | string | 1234-aasvs-3345.1332 | Уникальный код транзакции (transaction id) |
| cn | string | ru | Двухбуквенный код страны (в нижнем регистре) |
| op | string | beeline | Оператор связи |
| phone | array [int] |
79991234567 | Номер телефона абонента (Только цифры, без знака «плюс» в начале. Для зарубежных абонентов номер может начинаться с «нуля») |
| sn | array [int] |
2420 | Короткий номер, на который было отправлено SMS-сообщение (в РФ – 4 цифры, в зарубежных странах может быть первый символ «0») |
| access_key | string | 2dsfs4DSfsd32DSfs0 | Ключ доступа, который задается в личном кабинете. Чем сложнее этот набор символов, тем труднее вызвать ваш скрипт обработки входящих сообщений напрямую злоумышленником. |
| cost | decimal |
0.72 | Отчисление за SMS в рублях. |
4.1. Примеры запросов к скриптам:
| Пример запроса |
|---|
|
Запрос 1: http://www.yoursite.ru/dir/script.php?pref=hitfm&txt=Передайте+Привет+Мне! &tid=1234-aasvs-3345.1332&cn=ru&op=beeline&phone=79031234567&sn=8385&cost=0.72 |
|
Запрос 2: http://www.your-site.com/script.cgi?pref=crossword&txt=&tid=173232001239.123&cn=uk &op=uk_orange&phone= 00447732701234&sn=81303&cost=0.72 |
Внимание! В ответе скрипт должен выдавать одну строчку: sms=и далее текст ответной sms
Обратите особое внимание на то, что первые 4 символа ответного сообщения sms= должны быть в любом случае, даже при выводе ошибок.
Ответ скрипта должен идти в plaintext, без HTML-кода, в одну строку, на русском языке, в кодировке Windows-1251 или UTF-8.
Примечание 1: если ответ скрипта будет в латинице (что крайне нежелательно), то он будет автоматически перекодирован в кириллицу для всех абонентов РФ.
Если длина текста ответа составит до 70 символов включительно (без учета четырех символов ‘sms='), то будет тарифицировано одно MT-сообщение. Если длина ответа 71 и более символов, то количество сообщений будет 2 и более (длинные сообщения делятся на части по 67 символов).
Пример простейшего скрипта-обработчика на PHP (метод вызова GET):
Желательно ограничить вызов Вашего скрипта при помощи ключа удалённого доступа (по ссылке откроется личный кабинет).
4.2. Пример простейшего скрипта обработчика на PHP:
$pref=$_GET['pref']; $txt=$_GET['txt']; $tid=$_GET['tid']; $cn=$_GET['cn']; $op=$_GET['op'];
$phone=$_GET['phone']; $sn=$_GET['sn']; $access_key=$_GET['access_key']; $cost=$_GET['cost'];
# прочие функции скрипта
echo "sms=Ваше сообщение получено";
?>
при формировании ответного сообщения sms= указывается без пробела и является обязательным параметром.
ключ доступа изменяется в личном кабинете в разделе "Настройки"
5. Примечания
1. Символ перевода строки после ‘sms=' и/или текста сообщения не допускается. Если требуется передать символ новой строки в SMS, то его следует заменить на тэг <br>. Пример:
echo "sms=Расписание сеансов:<br>Зал1 10:30 Матрица<br>Зал2 11:00 Матрица2";
2. Если требуется в ответе пользователю передать несколько отдельных sms-сообщений, то это можно сделать, разделив их символом табуляции (в языках PHP и Perl – служебная последовательность «\t»). Пример:
echo "sms=Текст первой sms\tТекст второй sms\tТекст третьего sms-сообщения";
3. Запрос к скрипту производится сразу после получения сервером sms-сообщения от абонента. Таймаут запроса 90 секунд. Если в течение этого времени корректный ответ не был получен, то sms складываются в очередь и производятся повторные запросы.
Последующие пять запросов (в случае недоступности скрипта) будут с интервалом в 30 секунд, следующие десять – с интервалом 3 минуты, затем – раз в 15 минут. Если в течение 24 часов корректный ответ не будет получен, то запрос удаляется из очереди.
© 2009—2012 Все права принадлежат компании ООО «Авизосмс»
С помощью AvisoSMS разработать и внедрить SMS-уведомления в свои продукты и услуги очень просто, благодаря большому количеству готовых решений и понятной документации.
Лицензия на телематические услуги связи №86998