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.

cpanm Mojolicious::Plugin::Nexmo

perl -MCPAN -e shell
install Mojolicious::Plugin::Nexmo