/ 
Mojolicious-Plugin-Nexmo-0.91
/ Mojolicious::Plugin::Nexmo

NAME

Mojolicious::Plugin::Nexmo - Asynchronous (and synchronous) SMS and TTS (Text To Speech) sending with Nexmo provider.

VERSION

0.90

SYNOPSIS

plugin 'Nexmo' => {
    api_key    => 'n3xm0rocks',
    api_secret => '12ab34cd',
    from       => 'YourCompanyName',   # This options are global, you don't need
    lg         => 'de-de'              # to declare them in every request
};

Simple blocking example

use Mojolicious::Lite

plugin 'Nexmo' => {
    api_key    => 'n3xm0rocks',
    api_secret => '12ab34cd'
};

# /block ? mode=SMS & phone_number=447525856424 & message=Hello!
get '/block' => sub {
    my $self = shift;

    my $mod = $self->param('mode');
    my $tel = $self->param('phone_number');
    my $mes = $self->param('message');
    
    $self->render(text => "$tel : $mes");
    
    my ($err, $err_mes, $info) = $self->nexmo(
        mode => $mod,
        to   => $tel,
        text => $mes
    );
};

app->start;

Nonblocking example

use Mojolicious::Lite;

plugin 'Nexmo' => {
    api_key    => 'n3xm0rocks',
    api_secret => '12ab34cd'
};

# /nonblock ? mode=SMS & phone_number=447525856424 & message=Hello!
get '/nonblock' => sub {
    my $self = shift;
    
    my $mod = $self->param('mode');
    my $tel = $self->param('phone_number');
    my $mes = $self->param('message');
    
    $self->render(text => "$tel : $mes");
    
    $self->nexmo(
        mode => $mod,
        to   => $tel,
        text => $mes,
        sub {
            my ($self, $err, $err_mes, $info) = @_;
            # ...
        }
    );
};

app->start;

Nice example with Mojo::IOLoop

use Mojolicious::Lite;
use Mojo::IOLoo;

plugin 'Nexmo' => {
    api_key    => 'n3xm0rocks',
    api_secret => '12ab34cd'
};

# /delay ? mode=SMS & phone_number=447525856424 & message=Hello!
get '/delay' => sub {
    my $self = shift;
    
    my $mod = $self->param('mode');
    my $tel = $self->param('phone_number');
    my $mes = $self->param('message');
    
    Mojo::IOLoop->delay(
        sub {
            my $delay = shift;
            $self->nexmo(
                mode => $mod,
                to   => $tel,
                text => $mes,
                $delay->begin # CallBack
            );
            return $self->render(text => "$tel : $mes");
        },
        sub {
            my ($delay, $err, $err_mes, $info) = @_;
            # ...
        }
    );
};

app->start;

DESCRIPTION

This plugin provides an easy way to send SMS and TTS with Nexmo API.

OPTIONS

You can redefine global options:

plugin 'Nexmo' => {
    api_key    => 'n3xm0rocks',
    api_secret => '12ab34cd',
    from       => 'YourCompanyName'  # Global option
};

# ...
    
    $self->nexmo(
        mode => $mod,
        to   => $tel,
        text => $mes,
        from => 'NewCompanyName'  # 'NewCompanyName' will be used in this response
    );

# ...

Or you can disable global options by setting them in undef:

plugin 'Nexmo' => {
    api_key    => 'n3xm0rocks',
    api_secret => '12ab34cd',
    lg         => 'de-de'  # Global option
};

# ...
    
    $self->nexmo(
        mode => $mod,
        to   => $tel,
        text => $mes,
        lg   => undef   # lg will be missed in this response
    );

# ...

Mojolicious::Plugin::Nexmo supports the following options:

api_key
api_secret

Your Nexmo API key & API secret. This two options are required, you should always declare it globally:

plugin 'Nexmo' => {
    api_key    => '...',
    api_secret => '...'
    # ...
}
mode

Can be 'SMS' or 'TTS'. Depending on mode there are different options:

SMS options

See detailed description of SMS options at https://docs.nexmo.com/index.php/sms-api/send-message.

$self->nexmo(
    mode => 'SMS',
    # options
);
from
to
type
text
status-report-req
client-ref
network-code
vcard
vcal
ttl
message-class
body
udh

TTS options

See detailed description of TTS options at https://docs.nexmo.com/index.php/voice-api/text-to-speech.

$self->nexmo(
    mode => 'TTS',
    # options
);
to
from
text
lg
voice
repeat
machine_detection
machine_timeout
callback
callback_method

Asynchronous and synchronous modes

For asynchronous mode you should pass a callback as last parameter:

$self->nexmo(
    mode => 'SMS',
    # options
    sub {
        my ($self, $err, $err_mes, $info) = @_;
        # ...
    }
);

If a callback is missed, plugin works in synchronous mode:

my ($err, $err_mes, $info) = $self->nexmo(
    mode => 'SMS',
    # options
);

RETURN VALUES

Error code ($err)

Values:

0

Success.

-1

Network error.

1 - 99

Nexmo error response codes.

See detailed description of SMS response codes at https://docs.nexmo.com/index.php/sms-api/send-message#response_code.

See detailed description of TTS response codes at https://docs.nexmo.com/index.php/voice-api/text-to-speech#tts_response_code.

IT'S IMPORTANT: If you use 'SMS' mode, message can be divided into several parts. If all parts were sent succesfully, then 0 is returned. Otherwise $err will contain error code of first failed part. If you need error codes of all parts, use $info hash.

Error message ($err_mes)

Additional information ($info)

Hash that corresponds to the Nexmo JSON response.

DEBUG

Set MOJOLICIOUS_NEXMO_DEBUG environment variable to turn Nexmo debug on.

$ MOJOLICIOUS_NEXMO_DEBUG=1 morbo test

SEE ALSO

Mojolicious::Plugin::SMS

Nexmo::SMS

SMS::Send::Nexmo

AUTHOR

    Andrey Khozov, <avkhozov@googlemail.com>

CORE DEVELOPERS

    Georgiy Alexeew, <alexeew.georgiy@gmail.com>

    Alexey Stavrov, <logioniz@yandex.ru>

COPYRIGHT AND LICENSE

Copyright (C) 2014, Andrey Khozov

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.