There is an ongoing outage on the primary CPAN mirror. It is possible to work around the issue by using MetaCPAN as a mirror.

 / 
SMS-API-VoIP-MS-SMS-API-VoIP-MS-0.01
/ SMS::API::VoIP::MS

NAME

SMS::API::VoIP::MS - VoIP.ms SMS client with MMS support.

VERSION

Version 0.01

SYNOPSIS

A simple module that attempts to implement the SMS/MMS portion of VoIP.ms's API.

use SMS::API::VoIP::MS;

my $sms = SMS::API::VoIP::MS->new(
    # Required
    username => 'john.doe@test.com',
    api_key  => 'abcd1234',

    # Optional; you can set it as a 'from' parameter when sending
    # messages.  Or it'll use the only one you have if you only have 1 DID
    # with SMS enabled.
    did      => '1231231234',

    # Optional.  Default is 0, which will split texts > 160 chars into
    # multiples.
    convert_long_sms_to_mms => 1,
);

$sms->send_sms(
    did => 1231231234,
    to  => '1231231235',
    'This is a message!',
);

$sms->send_mms(
    to         => '1231231235',
    attachment => $io,
    'This is also a message!',
);

SUBROUTINES/METHODS

new

Method that constructs your SMS object. This method will contact VoIP.ms and verify the DID provided is in fact available to perform messaging. Failures will die, so use try/catch if you want to fail gracefully.

BUILD

Gets the DIDs that have SMS enabled, verifies the one provided (if any) is available.

_sanitise_number

Just regexes to delete non digits, and leading 1s (yes, this makes it NA-centric. I'm sorry.)

_get_method

Wrapper for calling API methods with GET

_post_method

Wrapper for calling API methods with POST. We also specify form-data, because VOIP.ms doesn't seem to like www encoded data in POSTs.

_parse_result

Does error handling, decodes JSON.

_default_params

Just a quick utility to put the username, api_key, and method into every call.

_api_url

Pretty self-explanatory.

_get_uri

Assembles the URI for doing a GET call.

_populate_sms_dids

Parses out the available DIDs on this account with SMS enabled.

Dies if there aren't any because we can't really do much without one.

_get_sms_did

Gets an SMS DID by: verifying if you provided one that it has SMS enabled, or returning the default if you only have one phone number with SMS enabled.

Otherwise, dies.

_wrap_text

I ran into some issues with line breaks, and character encoding, and text message limits with voip.ms's systems because it looks like they may have some encoding/escaping bugs, so this may still get punched in the mouth, but the idea here is to do line breaks for messages that are too long in a sensible way and understand other character encodings in the process.

YMMV for obvious reasons.

send_sms =head2 send_mms =head2 _send_text

Sends an SMS message to a number. Expects a hash of parameters, and then the message.

Acceptable parameters are:

did

This is the DID to send the message from. If one isn't specified, we'll use the DID specified in ->new. If that wasn't specified, but you only have one SMS enabled DID in your VOIP account, we'll use that. If you have multiple, we'll die.

to

The number we're sending the message to.

media\d+

Any images being attached to the message. This will guarantee MMS instead of SMS.

get_sms

Just a goto to get_mms because get_mms can get SMSes too (and we tell it to).

get_mms

Gets MMS messages. You have to specify the did and the from date, but you can optionally specify any other parameter voip.ms supports.

We by default ask for received (type 1), sms *and* mms (all_messages 1), and (effectively) no limit. You can override these, though.

AUTHOR

Justin Wheeler, <cpan at datademons.com>

BUGS

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

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc SMS::API::VoIP::MS

You can also look for information at:

LICENSE AND COPYRIGHT

This software is Copyright (c) 2022 by Justin Wheeler.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)