О сервисе Тарифы Требования Операторы Демо





Документация по коротким номерам

1. Термины
2. Общая схема взаимодействия
3. Выбор префикса
4. Обработчик

5. Примечания

 

1. Термины

Термин Описание
МТ-сообщение (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:

<?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'];
if ($access_key !='2dsfs4DSfsd32DSfs0') die(); #Защита от стороннего вызова по ключу доступа. Не забудьте поменять на свой.
# прочие функции скрипта
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 часов корректный ответ не будет получен, то запрос удаляется из очереди.

Подняться к оглавлению ↑