--- name: "NetSDS::Kannel" section: "3pm" platform: "linux" package: "libnetsds-kannel-perl" version: "1.300-7" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/NetSDS::Kannel" --- # NetSDS::Kannel(3pm) Kannel SMS gateway API ## NAME NetSDS::Kannel - Kannel SMS gateway API ## SYNOPSIS ``` #!/usr/bin/env perl use 5.8.0; use warnings; use strict; use NetSDS::Kannel; my $kannel = NetSDS::Kannel->new( sendsms_url => 'http://localhost:1234/sendsms', sendsms_user => 'sender', sendsms_passwd => 'secret', default_smsc => 'esme-megafon', ); $res = $kannel->send( from => '1234', to => '380672222111', text => 'Hallo there!', smsc => 'emse-mts', priority => 3, ); 1; ``` ## DESCRIPTION `"NetSDS::Kannel"` module provides API to Kannel SMS gateway. To decrease innecessary problems we use a lot of predefined parameters while sending and receiving messages via Kannel HTTP API. It's not so flexible as direct HTTP processing but less expensive in development time ;-) This modules uses LWP to send messages and CGI.pm to process messages from Kannel. ## CLASS API - **new(%params)** - class constructor Constructor creates Kannel API handler and set it's configuration. Most of these parameters may be overriden while object method calls. **Admin API parameters:** \* admin\_url - Kannel admin API URL \* admin\_passwd - password to admin API **Sending SMS API parameters:** \* sendsms\_url - URL of Kannel sendsms HTTP API \* sendsms\_user - user name for sending SMS \* sendsms\_passwd - password for sending SMS \* dlr\_url - base URL for DLR retrieving \* default\_smsc - default SMSC identifier for sending SMS \* default\_timeout - default sending TCP timeout ## OBJECT METHODS - **send(%parameters)** - send MT SM message to Kannel This method allows to send SMS message via Kannel SMS gateway. Parameters (mostly the same as in Kannel sendsms API): \* from - source address (overrides message) \* to - destination address (overrides message) \* text - message text (byte string) \* udh - user data header (byte string) \* charset - charset of text \* coding - 0 for GSM 03.38, 1 for binary, 2 for UCS2 \* smsc - target SMSC (overrides default one) \* mclass - message class if necessary (0 for flash sms) \* validity - TTL for MO SM in minutes \* deferred - timeout for delayed delivery Example: ``` use NetSDS::Kannel; use NetSDS::Util::Misc; my $kannel = NetSDS::Kannel->new(...); $kannel->send_sms( from => '1234', to => '380672206770', text => 'Wake up!!!', smsc => 'nokia_modem', msgid => make_uuid, ); ``` - **receive($cgi)** - receive MO or DLR from CGI object This method provides import message structure from CGI request . This method is just wrapper around `"receive_mo()"` and `"receive_dlr()"` methods. Message type (MO or DLR) recognized by `"type"` CGI parameter that may be `"mo"` or `"dlr"`. ``` my $cgi = CGI::Fast->new(); my %ret = $kannel->receive($cgi); ``` - **receive\_mo($cgi)** - import MO message from CGI object This method provides import message structure from CGI request . Imported MO message parameters returned as hash with the following keys: \* smsc - Kannel's SMSC Id \* smsid - SMSC message ID \* from - subscriber's MSISDN \* to - service address (short code) \* time - SMS receive time \* unixtime SMS receive time as UNIX timestamp \* text - MO SM text \* bin - MO SM as binary string \* udh - SMS UDH (User Data Headers) \* coding - SMS encoding (0 - 7 bit GSM 03.38; 2 - UCS2-BE) \* charset - charset of MO SM text while receiving from Kannel \* binfo - SMPP `"service_type"` parameter for billing puroses - **receive\_dlr($cgi)** - import message from CGI object This method provides import message structure from CGI request . `"receive_dlr"` method returns hash with the following keys: \* smsc - kannel SMSC id \* msgid - original MT SM message id for DLR identification \* smsid - SMSC message ID \* from - subscriber's MSISDN (phone number) \* to - service address (short code) \* time - delivery time \* unixtime - delivery time as UNIX timestamp \* dlr - DLR state \* dlrmsg - DLR message from SMSC Example: ``` my $cgi = CGI->new(); my %dlr = $kannel->receive_dlr($cgi); print "DLR received for MSISDN: " . $dlr{from}; ``` - **make\_dlr\_url(%params)** - prepare DLR URL This method creates URI escaped string with URL template for DLR notification. Paramters: hash (dlr\_url, msgid) Returns: URI escaped DLR URL - **make\_meta(%params)** - prepare SMPP optional TLV This method creates URI escaped string with optional SMPP tag-lenght-value (TLV) parameters to send them in `"meta-data"` CGI paramter of Kannel's `"sendsms"` HTTP API. Format of `"meta-data"` parameter value: ``` ?smpp?tag1=value1&tag2=value2&...tagN=valueN ``` Paramters: hash of TLV pairs Returns: URI escaped string Example: ``` my $meta = $self->make_meta( charging_id => '0', ); ``` This will return: `%3Fsmpp`%3Fcharging\_id%3D0 - **status()** - retrieve Kannel status - **store\_status()** - retrieve message queue status Not implemented yet. - **shutdown()** - bring down Kannel - **suspend()** - switch Kannel to 'suspended' state - **isolate()** - switch Kannel to 'isolated' state - **resume()** - resume Kannel to 'online' state - **restart()** - whole bearerbox restart - **flush\_dlr()** - flush queued DLR if Kannel in 'suspended' state - **reload\_lists()** - reload black/white lists - **log\_level($level)** - change Kannel log-level - **start\_smsc($smsc)** - switch on SMSC connection - **stop\_smsc($smsc)** - switch off SMSC connection - **add\_smsc($smsc)** - add new SMSC connection - **remove\_smsc($smsc)** - remove SMSC connection ## EXAMPLES See Nibelite kannel API ## SEE ALSO - • NetSDS::Class::Abstract - base NetSDS class - • \ - Kannel User Guide ## TODO 1\. Add PPG support. 2\. Add OTA support. ## AUTHOR Michael Bochkaryov \ ## LICENSE Copyright (C) 2008-2009 Net Style Ltd. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA