Отправка и приём SMS сообщений с помощью VoIP шлюзов GoIP и Yeastar



    Так как мы занимаемся продажами VoIP оборудования, к нам часто обращаются с различными техническими вопросами. Иногда доходит до того, что клиенты просят примеры кода на конкретных языках программирования. Работа с SMS и интеграция их в бизнес процессы — как раз один из таких регулярных вопросов, поэтому и хочется остановится на нём и рассмотреть более подробно.


    Почему GoIP и Yeastar


    В действительности, я бы хотел рассказать еще и про OpenVox, но на хабре уже есть статья именно про их шлюзы, да и в наличии на момент написания этого материала их не было. Так же подобные шлюзы делает Dinstar, но обращений по этим шлюзам у нас так катастрофически мало, так что их я решил тоже не рассматривать.


    GoIP




    GSM шлюзы GoIP производятся в Китае под брендами нескольких компаний и относятся к низшей ценовой категории, отчасти поэтому они самые популярные. Всё нижеописанное мною применительно к GoIP 4 фирмы DBL, в теории оно же должно работать и на шлюзах Hybertone, но ручаться за это не буду, так как возможны отличия в прошивках.


    ▪ Web интерфейс


    Самый простой способ отправить SMS — это зайти на страничку шлюза, выбрать раздел Send SMS, указать линию, с которой необходимо отправить сообщение, номер получателя и непосредственно текст сообщения. Вариант простой, но годится разве что для теста, не более того. Однако есть возможность отправлять смски с помощью GET и POST запросов.


    → GET


    Для типа GET используем запрос вида:
    http://192.168.1.190/default/en_US/send.html?u=admin&p=admin&l=1&n=89991234567&m=test


    u=admin – имя пользователя
    p=admin – пароль
    l=1 – канал, с которого надо отправить сообщение
    n=89991234567 – номер получателя (надо указывать начиная с «8», при использовании «+7» или «7» получим ошибку)
    m=test – текст сообщения

    Если что то пошло не так, то в ответ мы получим сообщение вида: «ERROR, описание проблемы», в противном случае: «Sending, L1 Send SMS to 89991234567; ID:55c489da». Думаю, тут все и так ясно: статус, номер линии, номер получателя, и присвоенный индификатор, чтобы впоследствии можно было отследить статус отправления.


    → POST


    Отправка с помощью POST запроса — это тоже самое, что отправка через форму в web интерфейсе, отличается тем, что мы сами должны указывать индификатор SMS, в определенных случаях это может быть удобнее. Так же через POST мы можем отправить USSD запрос, что тоже может быть полезно.


    Простой пример на perl с использованием фреймворка Mojolicious:


    #!/usr/bin/perl -w
    
    use utf8;
    use Mojo::UserAgent;
    
    my $ua = Mojo::UserAgent->new;
    
    $ua->post('http://admin:admin@192.168.1.190/default/en_US/sms_info.html?type=sms' 
                        => {Accept => '*/*'}
                        => form => {
                                line    => '1',
                                smskey  => '57867a25',
                                action  => 'SMS',
                                telnum  => '89991234567',
                                smscontent => 'Привет!',
                                send    => 'Send'
                            });

    Для отправки USSD придется немного изменить запрос:


    $ua->post('http://admin:admin@192.168.1.190/default/en_US/sms_info.html?type=ussd' 
                    => {Accept => '*/*'}
                    => form => {
                            line1 => '1',
                            smskey => '57876006',
                            action => 'USSD',
                            telnum => '*100#',
                            send => 'Send'
                        });

    Для получения результата придется делать отдельный GET запрос статуса сообщений.


    → Статус сообщений


    Отслеживать статусы необходимо хотя бы потому, что мы можем попытаться отправить сообщение в момент, когда линия занята отправкой другого сообщения и, как результат, ничего не выйдет. Плюс к этому, разработчики GoIP не стали заморачиваться с созданием отдельного средства получения результатов USSD запросов, а просто пишут их в виде расшифровок ошибок.


    Статусы отправлений можно отслеживать по адресу:
    http://192.168.1.190/default/en_US/send_status.xml?u=admin&p=admin


    В ответ мы получим XML, в которой отображается статус одного последнего отправления на канал, у меня под рукой был GoIP 4, а у него единая прошивка с восьмым, поэтому в статусах 8 каналов, хотя физически их было 4:


    <?xml version="1.0" encoding="utf-8"?>
    <send-sms-status>
        <id1>57867a25</id1>
        <status1>DONE</status1>
        <error1></error1>
        <id2>57867277</id2>
        <status2>ERRORDONE</status2>
        <error2>send, but provider not reply.</error2>
        <id3>57876006</id3>
        <status3>DONE</status3>
        <error3>Ваш баланс: 57.2 р.</error3>
        <id4></id4>
        <status4>DONE</status4>
        <error4></error4>
        <id5></id5>
        <status5></status5>
        <error5></error5>
        <id6></id6>
        <status6></status6>
        <error6></error6>
        <id7></id7>
        <status7></status7>
        <error7></error7>
        <id8></id8>
        <status8></status8>
        <error8></error8>
    </send-sms-status>

    ▪ Протокол SMPP


    SMPP (Short message peer-to-peer protocol) – специальный протокол, используемый для передачи SMS и USSD сообщений между клиентом и сервером. Это, наверное, единственный «нормальный» способ получать сообщения. Да, в web интерфейсе отображаются последние пять сообщений для каждого канала, но вариант периодически лезть на него и проверять, не появилось ли что то новое, я не могу отнести к адекватным.


    Настройка SMPP



    Хотя и с SMPP все не так гладко. Во первых, сообщения приходят в кодировке UTF-16BE. Сначала мне об этом информация нигде не попадалась и пришлось изрядно попрыгать с бубном, чтобы понять, в какой же кодировке принимаются смски. Правда после этого нашёлся параметр (data_coding), который как раз и указывает на то, как закодировано сообщение.


    Во вторых, в качестве destination_addr всегда будет system_id, с которым мы подключаемся к GoIP-у, т. е. нет возможности понять, на какую именно симку пришло сообщение. Это можно обойти – необходимо подключаться с system_id + 0 + номер канала, тогда мы будем получать сообщения только для заданного канала, естественно минус такого решения в том, что необходимо держать несколько коннектов.


    Простейший пример получения сообщений с использованием библиотеки Net::SMPP:


    #!/usr/bin/perl -w 
    
    use utf8;
    use strict;
    use Net::SMPP;
    use Encode;
    use feature 'say';
    
    my $smpp = Net::SMPP->new_transceiver('192.168.1.190',
                    system_id => 'arttel', # Если хотим слушать только первый канал то – arttel01, второй – arttel02 и т.д.
                    password => 'arttel',
                    port => '7777',
                    smpp_version=> 0x34
    ) or die "Can't connect to SMSC: $!";
    
    while (1) {
        my $pdu = $smpp->read_pdu();
        # Меняем кодировку на системную
        my $short_message =  Encode::decode("UTF-16BE", $pdu->{short_message});
    
        say $short_message;
    }

    С отправкой такая же история, если необходимо отправить SMS с конкретной SIM карты, то подключаемся с id нужного канала:


    #!/usr/bin/perl -w 
    
    use utf8;
    use strict;
    use Net::SMPP;
    
    my $smpp = Net::SMPP->new_transceiver('192.168.4.107',
                    system_id => 'arttel01',
                    password => 'arttel',
                    port => '7777',
                    smpp_version=> 0x34
    ) or die "Can't connect to SMSC: $!";
    
    &send_message('89991234567', 'Привет!!!');
    
    sub send_message {
        my ($sm_dest_addr, $sm_message) = @_;
        my $result = eval {
    
            my $pru = $smpp->submit_sm(
                source_addr_ton => 0x05, # Тип номера отправителя
                source_addr_npi => 0x01, # Идентификатор плана нумерации отправителя
                source_addr => '',
                dest_addr_ton => 0x01, # Тип номера получателя
                dest_addr_npi => 0x01, # Идентификатор плана нумерации получателя
                destination_addr => $sm_dest_addr,
                data_coding => 0x01, # Определяет схему кодировки пользовательских данных короткого сообщения
                short_message => $sm_message
            ) or return 1;
    
            return 0;
        };
    
        if ($result == 1){
            print "Can't send message: $!";
        }
    }
    
    #Разрываем соединение с SMSC
    $smpp->unbind();

    Описание параметров отправки
    Параметр Описание Значения
    source_addr_ton Тип номера отправителя 0x00 — Неизвестный (Unknown)
    0x01 — Международный (International)
    0x02 — Государственный (National)
    0x03 — Сетевой Специальный (Network Specific)
    0x04 — Номер Абонента (Subscriber Number)
    0x05 — Алфавитно-цифровой (Alphanumeric)
    0x06 — Сокращенный (Abbreviated)
    source_addr_npi Идентификатор плана нумерации отправителя 0x00 — Unknown 0x01 — ISDN (E163/E164)
    0x02 — Data (X.121)
    0x03 — Telex (F.69)
    0x04 — Land Mobile (E.212)
    0x05 — National
    0x06 — Private
    0x07 — ERMES
    0x08 — Internet (IP)
    0x09 — WAP Client Id (его должен определять WAP Forum)
    dest_addr_ton Тип номера получателя 0x01 — Международный (International)
    dest_addr_npi Идентификатор плана нумерации получателя 0x01 — ISDN (E163/E164) (для номеров)
    0x02 — National (для остального)
    data_coding Определяет схему кодировки пользовательских данных короткого сообщения 0x01 — IA5(CCITT T.50)/ASCII (ANSI X3.4) латинский алфавит 7 бит на 1 символ максимальная длина одного сообщения 160 символов
    0x07 — Latin/Hebrew(ISO-8859-8) латинский алфавит 8 бит на 1 символ максимальная длина сообщения 140 символов
    0x08 — UCS2(ISO/IEC-10646) для национальных алфавитов (например, русского) максимальная длина сообщения 70 символов

    Yeastar




    Родина Yeastar, так же как и у GoIP – Китай, хотя, как мне кажется, в Yeastar стараются делать устройства с большей претензией на качество и удобство использования, чем их конкуренты. Это касается как физического, так и программного исполнения. Но и у них бывают огрехи. Так, например, документация не всегда поспевает за изменениями в новых прошивках, а в отдельных случаях в ней могут отсутствовать важные моменты.


    ▪ Web интерфейс


    Отправлять и принимать сообщения можно через web интерфейс, в общем то, это стандартный способ для подобных железок. В шлюзах Yeastar этот интерфейс чем то отдаленно напоминает простенькие почтовые web морды — «папочки» Inbox и Outbox с незатейливыми фильтрами и поиском. В любом случае, это на голову выше чем то, что есть в GoIP, а главное хранятся не последние пять входящих сообщений для каждого канала, а значительно больше. Только, к сожалению, не понятно сколько, опять же в datasheet про это нет ни слова.


    → GET


    Так же как и в большинстве подобных железок, отправить сообщение можно с помощью GET запроса, что в общем не удивительно, это один из самых простых способов интеграции. Естественно, у Yeastar своя реализация со своими особенностями.


    Для начала надо включить возможность отправлять SMS сообщения и USSD запросы. Для этого необходимо активировать «API Settings», если вы предпочитаете интерфейс на русском языке, то данный раздел будет называться «Настройки AMI» (правда очень логично?). Во вторых, необходимо поменять пароль по умолчанию, пока этого не сделаешь, авторизация не проходит, об этом опять же ни слова в документации.


    Настройка API Settings


    После этих манипуляций мы можем использовать запросы для SMS и USSD соответственно:


    http://192.168.5.150/cgi/WebCGI?1500101=account=arttel&password=arttel&port=1&destination=89991234567&content=test


    Response: Success
    Message: Commit successfully!

    http://192.168.5.150/cgi/WebCGI?1500102=account=arttel&password=arttel&port=1&content=%2A100%23


    Request: 1,*100#
    Response: Success
    Message: Ваш баланс:
    36.3 р.

    Коротко о параметрах:


    account=arttel – имя пользователя что мы указали в настройках API Settings
    password=arttel – пароль из API Settings
    port=1 – канал, с которого будет осуществлена отправка
    destination=89991234567 – номер получателя, используется только при отправке SMS
    content=test – текст сообщения или USSD запроса

    Главное отличие от GoIP: при отправке SMS с Yeastar нет необходимости контролировать занят канал или нет, наше сообщение ставится в очередь и как только канал освобождается оно будет отправлено. А с USSD запросами работа происходит синхронно, т. е. ответ мы получаем сразу и нет необходимости его где то потом искать. Минус только в том, что ответы нам приходят в виде plain text, а хотелось бы что то более подходящее: JSON или XML.


    ▪ Asterisk Managment Interface


    Вся линейка шлюзов Yeastar построена вокруг Asterisk (программный сервер IP-телефонии от компании Digium), поэтому поддержка такого специфического протокола как SMPP отсутствует. Зато есть родной для Asterisk'a протокол AMI, работать с которым достаточно просто.


    Для начала посмотрим как принимать сообщения:


    #!/usr/bin/perl -w
    
    use utf8;
    use strict;
    use warnings;
    use AnyEvent::Impl::Perl;
    use Asterisk::AMI;
    use Data::Dumper;
    use URI::Escape;
    use feature 'say';
    
    # Подключаемся к AMI
    my $astman = Asterisk::AMI->new(
                PeerAddr => '192.168.5.150', # Адрес шлюза
                Username => 'arttel', # Имя пользователя из API Settings
                Secret  => 'arttel', # Пароль из API Settings
                Events  => 'on',
                Handlers => { 
                    ReceivedSMS => \&received_sms # Подписываемся на приём сообщений
                },
                Keepalive => 60,
                on_error => sub { print "Error occured on socket\r\n"; exit; },
                on_timeout => sub { print "Connection to asterisk timed out\r\n"; exit; }
            );
    
    die "Unable to connect to asterisk" unless ($astman);
    
    sub received_sms {
        my ($asterisk, $event) = @_;
    
        say Dumper($event);
        # Приводим сообщение к читаемому виду
        say uri_unescape($event->{'Content'}) if ($event->{'Content'});
    
        return 1;
    }
    
    AnyEvent::Impl::Perl::loop;
    
    =result 
    $VAR1 = {
              'Total' => '1',
              'Recvtime' => '2016-07-15 17:49:55',
              'ID' => '',
              'Event' => 'ReceivedSMS',
              'Privilege' => 'all,smscommand',
              'Index' => '1',
              'GsmSpan' => '4',
              'Sender' => '+79991234567',
              'Smsc' => '+79997456321',
              '--END SMS EVENT--' => undef,
              'Content' => '%EF%BB%BF%D0%9A%D1%83-%D0%BA%D1%83'
            };
    
    Ку-ку
    =end

    Пример достаточно прост и мне кажется, что всё должно быть понятно. Единственное, на что хочу обратить внимание это «GsmSpan». Мы все привыкли, что индексация массивов начинается с 0, здесь же не 0 и не 1, а 2, последовательный номер канала отображается как номер + 1, поэтому минимальное значение GsmSpan это 2.


    Так же через AMI мы может отправлять SMS и USSD запросы:


    #!/usr/bin/perl -w
    
    use strict;
    use warnings;
    use Asterisk::AMI;
    use Data::Dumper;
    use URI::Escape;
    use Encode;
    use feature 'say';
    
    # Connect to asterisk
    my $astman = Asterisk::AMI->new(
                PeerAddr => '192.168.5.150',
                Username => 'arttel',
                Secret  => 'arttel',
                Timeout => 30, # Таймаут на выполнение команд, если используем USSD то ставим побольше
                Keepalive => 60,
                on_error => sub { print "Error occured on socket\r\n"; exit; },
                on_timeout => sub { print "Connection to asterisk timed out\r\n"; exit; }
            );
    
    die "Unable to connect to asterisk" unless ($astman);
    
    # Отправляем USSD запрос
    my %action = (
        Action => 'smscommand',
        Command => 'gsm send ussd 2 "*100#"'
    );
    my $actionid = $astman->send_action(\%action);
    my $response = $astman->get_response($actionid);
    
    my @cmd = @{$response->{CMD}};
    my $i = 0;
    while ($i <= $#cmd) {
        if ($cmd[$i] =~ /USSD Message: (.+)/) {
            # Ответ будет закодирован, поэтому потребуется не много магии
            my $decodedHex = pack('H*', $1);
            say decode("UCS-2BE", $decodedHex);
        }
    
        $i++;
    }
    
    # Отправляем SMS
    %action = (
        Action => 'smscommand',
        Command => 'gsm send sms 2 89991234567 "Привет" 11111'
    );
    $actionid = $astman->send_action(\%action);
    $response = $astman->get_response($actionid);

    По USSD думаю всё понятно, только не забываем, что каналы нумеруются с двойки. А по SMS есть небольшое уточнение: если нам судьба сообщения безразлична и статус отслеживать не надо, то после текста сообщения можно ничего не указывать. В противном случае, необходимо указать уникальный индификатор. Тогда, когда судьба смски станет известна, система отправит нам сообщение о её состоянии. Что-то такого вида:


    $VAR1 = {
              'ID' => '11111',
              'Event' => 'UpdateSMSSend',
              '--END SMS EVENT--' => undef,
              'Status' => '1',
              'Privilege' => 'all,smscommand',
              'Smsc' => '+79991234567'
            };

    Status = 1 говорит нам о том, что сообщение успешно доставлено, а в случае ошибки статус будет равен 0. Получать подобные сообщения можно, подписавшись на события UpdateSMSSend, делается это точно так же, как и при приеме SMS.


    В качестве заключения


    Лично мне было бы удобнее работать со шлюзом Yeastar TG400 через AMI. С другой стороны, я не вижу каких-то больших проблем и в случае использования GoIP. О чем я сознательно умолчал: у каждого из производителя есть бесплатный программный SMS сервер, в случае GoIP чтобы его использовать потребуется PHP, Apache и MySQL, а в случае Yeastar – Windows. Подобные продукты больше подходят для рассылки одинаковых сообщений по заранее подготовленным базам номеров, а не интеграции с какими-то приложениями. Это и есть причина, по которой я их пропустил. Если кому-то интересно, на сайтах производителей должны быть соответствующие описания.

    АртТел
    Компания

    Похожие публикации

    Реклама
    AdBlock похитил этот баннер, но баннеры не зубы — отрастут

    Подробнее

    Комментарии 8

      0
      А расскажите, как рассылая много смс не попадать под блокировку операторов связи?
      И даже действуя в рамках закона «О рекламе», безо всякого спама.
        0
        Тут такое дело:

        «Статья 44.1. Рассылка по сети подвижной радиотелефонной связи
        2. Рассылка по сети подвижной радиотелефонной связи по инициативе заказчика рассылки осуществляется на основании договора, заключенного с оператором подвижной радиотелефонной связи, абоненту которого предназначена рассылка. Предметом указанного договора являются услуги по осуществлению рассылки оператором связи.



        4) пункт 1 статьи 46 дополнить абзацем следующего содержания:

        прекратить оказание услуг по пропуску по своей сети трафика, содержащего осуществляемую с нарушением требований настоящего Федерального закона рассылку.»

        base.garant.ru/70700818
        0
        Для Yeastar можно использовать TG SMS API через терминал.
        support.yeastar.com/hc/en-us/articles/217392758-How-to-Use-TG-SMS-API

        Собственно, по неопытности этот метод и выбрал для написания небольшой программы смс-рассылки для нужд фирмы. После прочтения вашей статьи понял, что можно переделать по человечески. Спасибо.
          0

          Это и есть AMI, только они подают его в документации каким-то извращенным способом. Вместо того чтобы написать «Мы поддерживаем AMI и дополнили его такими-то командами для работы с SMS и USSD» они зачем-то предлагают нам подключаться простым сокетом и изобретать велосипед, хотя для AMI уже под все популярные языки есть нормальные библиотеки. Рад что кому-то мой креатив помог.

          0
          У GoIP с отправкой SMS на самом деле всё ещё хуже, во всяком случае так было ~2 месяца назад (когда общался с их поддержкой).
          Сейчас, возможно, что-то поменялось.
          Кстати, поддержка на удивление оперативная и адекватная, за это огромный плюс разработчикам.

          При массовой отправке обнаружились проблемы:
          Отправка по HTTP:
          — отправка склеенных SMS не поддерживается
          — проблематично узнать в какой момент закончилась отправка сообщения. если сообщение ушло, то можно получить его messageID, если возникла проблема отправки (к примеру, недостаточно денег на счету), то видна ошибка модема. отличить временную ошибку от постоянной (к примеру, пропало подключение к сети GSM, выдернули SIM'ку) можно только сделав ещё одну попытку отправки. Если попытка успешна, то проблема была временной
          — отчёты о доставке не поддерживаются

          Отправка по SMPP:
          — SUBMIT_SM_RESP приходит сразу после приёма на отправку, DELIVER_SM со статусом «доставлено» — после того,
          как модем отправил данный пакет. Отправка следующего SUBMIT_SM не дожидаясь подтверждения отправки (DELIVER_SM) приводит к ошибке, т.е. буфера на отправку нет.
          — отчёты о доставке не поддерживаются, вместо «доставки» мы получаем информацию об успешной отправке
          — если нужно управлять распределением трафика на модемы, то для каждого модема нужно держать свою SMPP сессию под каждый модем, в случае временного падения линка — теряем данные о полученных в это время SMS

          В качестве альтернативы для проекта, которому требуется 1-2 SIM карты (и не нужна смена IMEI !!!) собрали связку Raspberry + USB GSM модем + Kannel. Работает отлично. Единственная проблема — адекватной документации по Kannel'у найти так и не удалось, пришлось долго шаманить с настройками и собирать конкретную нужную версию из исходников (версия из репозитория raspbian не работает с нашими huawei модемами).
            0

            Сейчас всё тоже самое, в GoIP надо самому за всем следить иначе ничего не получится, что естественно не удобно.


            А не проще было вообще отказаться от использования железок и попробовать какой-нибудь сервис sms gate, благо их сейчас в сети предостаточно?

            0
            Если кому-то пригодится — в модемах Huawei с прошивками Hilink также есть возможность отправки и приема SMS по сети через REST API. Документации маловато, правда, и так почему-то на польском в большинстве случаев (здесь, например).
              0
              Через GET можно совершить тестовый звонок?

              Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

              Самое читаемое