James Ronan

NAME

SMS::MessageBird - SMS sending module that uses the MessageBird gateway.

VERSION

Version 0.03

SYNOPSIS

This module is a Perl interface for interacting with the MessageBird SMS Gateway API.

    use SMS::MessageBird;

    my $messagebird = SMS::MessageBird->new(
        api_key    => 'test_abcdefghijklmnopqrstuvwxyz',
        originator => 'Me!', # Specify here, or use the originator() method.
    );

    # Optional. This can be updated at any time, but only needs to be set once.
    $messagebird->originator('Me!');

    my $result = $messagebird->sms->send(
        recipients => qw( 07123456789 ),
        message    => 'This is my SMS text', # synonym for 'body'
    );

DESCRIPTION

This module provides a simple Perl interface to the MessageBird JSON API. It deals with the JSON stuff allowing you to get back useful Perl data.

To use this module you'll need an account with MessageBird. Once you have that, you can create an API key on your account and feed it to this module which will authenticate with their API using that key.

The methods implmented acceept the paramteres as named in the MessageBird API documentation which can be found at the MessageBird Developer Documentation. If you're using this distribution you should be familiar with the API documentation.

API Modules

This distribution provides several modules which are used by the SMS::MessageBird object. Each module implements a section of the api.

Use of the functionality of a given module, is done via the accessor for that module, thus:

    my $result = $messagebird->sms->send(...);
    my $balance = $messagebird->balance->get();
    ...

Available Modules

sms

This is the accessor for the SMS::MessageBird::API::SMS module. Used for sending/receiving SMS messages.

voice

This is the accessor for the SMS::MessageBird::API::Voice module. Used for sending/receiving Text-to-Voice messages.

verify

This is the accessor for the SMS::MessageBird::API::Verify module. Used to implement the MessageBird number verification API.

hlr

This is the accessor for the SMS::MessageBird::API::HLR module. Used to send Network Queries to mobile numbers.

balance

This is the accessor for the SMS::MessageBird::API::Balance module. Used to retrieve your MessageBird account balance.

lookup

This is the accessor for the SMS::MessageBird::API::Lookup module. Used to validate phone numbers, and provide optional formats for that number.

METHODS

new (contructor)

 In: %params - Various parameters for the API interface.

Creates a new instance of SMS::MessageBird.

Parameters

Parmeters are passed to the contructor as a hash. Required / acceptable keys are as follows:

api_key

Required. The MessageBird account API key used for authentication with MessageBird's API.

originator

As per the MessageBird documentation, all sending functionality requires an originator. This can be set once on the SMS::MessageBird object and passed to all the module methods. This can be set later using the originator() mutator.

api_url

If for some reason you need to use some form of local HTTP proxy / forwarder this parameter can be used to specifiy the alternate address. If it is omittied the default is MessageBird's URL https://rest.messagebird.com.

originator

 In: $originator (optional) - New originator to set.
 Out: The currently set originator.

Mutator for the originator parameter. This parameter is the displayed "From" in the SMS. It can be a phone number (including country code) or an alphanumeric string of up to 11 characters.

This can be set for the lifetime of the object and used for all messages sent using the instance or passed individually to each call.

You can pass the originator param to the constructor rather than use this mutator, but it's here in case you want to send 2 batches of SMS from differing originiators using the same object.

api_url

 In: $api_url (optional) - New api_url to set.
 Out: The currently set api_url.

Mutator for the api_ul parameter. Should some form of network relay be required this can be used to override the default https://rest.messagebird.com.

AUTHOR

James Ronan, <james at ronanweb.co.uk>

BUGS

Please report any bugs or feature requests to bug-sms-messagebird at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SMS-MessageBird. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Alternatively you can raise an issue on the source code which is available on GitHub.

LICENSE AND COPYRIGHT

Copyright 2016 James Ronan.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.