Отправка и приём 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 все не так гладко. Во первых, сообщения приходят в кодировке 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» (правда очень логично?). Во вторых, необходимо поменять пароль по умолчанию, пока этого не сделаешь, авторизация не проходит, об этом опять же ни слова в документации.

После этих манипуляций мы можем использовать запросы для 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' => '[phone]',
          'Smsc' => '[phone]',
          '--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' => '[phone]'
        };

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

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

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