NetSDS::Kannel(3pm)

📦
version 1.300 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute

💖 NetSDS::Kannel 💖

okay bestie, so this is NetSDS::Kannel(3pm) — a User Contributed Perl Documentation page, and it's literally the Kannel SMS gateway API. yes. SMS. in perl. we love to see it 🫶

✨ NAME ✨

NetSDS::Kannel — Kannel SMS gateway API

🌸 SYNOPSIS 🌸

like, here's the whole vibe in one go:

#!/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;
not me noticing emse-mts in there 💀 it's in the original, so it stays in the original, i don't make the rules, i just keep them exactly as they are, no cap.

🦋 DESCRIPTION 🦋

so NetSDS::Kannel is the module that gives you an API to the Kannel SMS gateway. that's the whole thing. it's giving "i speak fluent SMS so you don't have to" 💅

here's the tea: to keep you from drowning in unnecessary problems, this module comes with a lot of predefined parameters baked in for sending and receiving messages through the Kannel HTTP API. it's not as flexible as talking straight to HTTP yourself, but it's way less expensive in development time ;-) — pick your fighter.

and for the technical girlies: this module uses LWP to send messages, and CGI.pm to process messages coming back from Kannel. iconic combo honestly.

👑 CLASS API 👑

new(%params) — class constructor

the constructor makes your Kannel API handler and sets its configuration up. most of these params can be overridden later when you call object methods, so don't stress too hard.

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 is the one. this method lets you send an SMS message through the Kannel SMS gateway. main character energy fr fr ✨

Parameters (mostly the same as in the Kannel sendsms API, so iykyk):

  • 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 imports a message structure straight from a CGI request. lowkey it's just a wrapper around receive_mo() and receive_dlr() — it's the girl who introduces you to her two friends.

message type (MO or DLR) is recognized by the type CGI parameter, which 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 imports a message structure from a CGI request.

the imported MO message parameters come back as a hash with these 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 purposes

receive_dlr($cgi) — import message from CGI object

this method imports a message structure from a CGI request.

receive_dlr returns a hash with these 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 a URI escaped string with a URL template for DLR notification.

Parameters: hash (dlr_url, msgid)

Returns: URI escaped DLR URL

make_meta(%params) — prepare SMPP optional TLV

this method creates a URI escaped string with optional SMPP tag-length-value (TLV) parameters, so you can send them in the meta-data CGI parameter of Kannel's sendsms HTTP API. it's giving "packaging my little extras cute" 🎀

format of the meta-data parameter value:

?smpp?tag1=value1&tag2=value2&...tagN=valueN

Parameters: hash of TLV pairs

Returns: URI escaped string

Example:

my $meta = $self->make_meta(
    charging_id => '0',
);

this will return: %3Fsmpp%3Fcharging_id%3D0

the rest of the method roster 👯

  • status() — retrieve Kannel status
  • store_status() — retrieve message queue status
not implemented yet. bestie it's a promise, not a feature 😭
  • 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 ⭐

🧚 TODO 🧚

  1. add PPG support.
  2. add OTA support.

like, someday. we manifest 🌸

💜 AUTHOR 💜

Michael Bochkaryov <misha@rattler.kiev.ua>

📜 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

💀 yes, "WITHOUT ANY WARRANTY" is in all caps in the original too, and honestly? it deserves the drama. that's not a vibe, that's a legally binding mood. respect it.

and that's the whole page bestie!! 💖 this one's from perl v5.32.1, dated 2021-12-26, and it's NetSDS::Kannel(3pm) — go text somebody, responsibly 🎀✨🦋

📦 where this page comes from