Pushover

SYNOPSIS

This module allows MisterHouse to send notification messages to Pushover.net clients. See http://pushover.net/ for details of the service and API.

CONFIGURATION

Configure the required pushover settings in your mh.private.ini file:

  Pushover_token = <API token from Pushover.net registration> 
  Pushover_user =  <User or Group ID from Pushover.net registraton>
  Pushover_device = <Default device or device list to sedn notifications to. List is comma-separated>
  Pushover_priority = [-1 | 0 | 1 | 2]  Default message priority,  defaults to 0.
  Pushover_html = [ 0 | 1 ]  Support HTML messages, see https://pushover.net/api#html. Defaults to 0.
  Pushover_title = "MisterHouse" Default title for messages if none provided 
  Pushover_disable = 1  Disable notifications.  Messages will still be logged

Create a pushover instance in the .mht file, or in user code:

.mht file:

  CODE, require Pushover; #noloop 
  CODE, my $push = new Pushover(); #noloop

A user code file overriding parameters normally specified in mh.private.ini. All of the parameters are optional if properly configured in the ini file.

    use Pushover;
    my $push = new Pushover( {token => '1234qwer1234qewr1234qwer',
                              user =>  '2345wert2345wert2345qwer',
                              title => 'Home Notification',
                              priority => -1,
                             });

In user code send a message. The only required parameter is the first, the message text. Any of the parameters provided when initializing the Pushover instance may also be provided on the message send. They will be merged with and override the default values provided on initialization. See the method documentation for below more details.

  $push->notify( "Some important message", { title => 'Security Alert', priority => 2 });

Or with HTML formmatting $push->notify( "Some <b>important</b> message", { title => 'Security Alert', priority => 2, html => 1 });

DESCRIPTION

The Pushover instance establishes the defaults for messages and acts as a rudimentary rate limiter for notifications.

The rate limiting kicks in if an identical message is sent within a 60 second threshold. (Identical meaning the same user, message, priority and title.) Identical messages will be logged but not sent to the pushover service. This will minimize excessive use of message credits if a configuration error causes looping notifications.

It's important to exclude the Pushover initialization from the loop, so that rate limiting thresholds can be detected and pending acknowledgments are not lost.

INHERITS

NONE

DEPENDENCIES

  Data::Dumper:     Used for error reporting and debugging
  LWP::UserAgent:   Implements HTTPS for interaction with Pushover.net
  Digest::MD5:      Calculates hash for rate limiting duplicate messages
  JSON:             Decodes responses from Pushover.net

METHODS

new(p_self, p_parameter_hash)

Creates a new Pushover object. The parameter hash is optional. Defaults will be taken from the mh.private.ini file or are hardcoded.

This must be excluded from the primary misterhouse loop, or the acknowledgment checking and duplicate message rate limiting will be lost

  my $push = Pushover->new( {   priority  => 0,            # Set default Message priority,  -1, 0, 1, 2
        html      => 1,            # Support HTML formatting of message ...see https://pushover.net/api#html
                        retry     => 60,           # Set default retry priority 2 notification every 60 seconds
                                expire    => 3600,         # Set default expration of the retry timer 
                                title     => "Some title", # Set default title for messages
                                token     => "xxxx...",    # Set the API Token 
                                user      => "xxxx...",    # Set the target user or group id
                                device    => "droid4",     # Set the target device (leaving this unset goes to all devices)
                                url       => "http://x..", # Set the URL
                                url_title => "A url",      # Set the title for the URL
                                timestamp => "1331249662", # Set the timestamp
                                sound     => "incoming",   # Set the sound to be played
                                speak     => 1,            # Enable or disable speak of notifications and acknowledgment
                                server    => "...",        # Override the Pushover server URL.  Defaults to the public pushover server
                                       });

Any of these parameters may be specified in mh.private.ini by prefixing them with "Pushover_"

notify(p_self, p_message, p_paramater_hash)

This is the primary method of the Pushover object. The message text is the only mandatory parameter.

The optional parameter hash can be used to override defaults, or specify additional information for the notification. The list is not exclusive. Additional parameters will be passed in the POST to Pushover.net. This allows support of any API parameter as defined at https://pushover.net/api

  $push->notify("Some urgent message", {  priority => 2,            # Message priority,  -1, 0, 1, 2
            html     => 1,              # HTML formatting of message 0-off, 1-on ... see https://pushover.net/api#html
            retry    => 60,             # Retry priority 2 notification every 60 seconds
                                          expire   => 3600,           # Give up if not ack of priority 2 notify after 1 hour
                                          title    => "Some title",   # Override title of message
            device   => "nexus5,iphone" # Device or device-list 
                                          token    => "xxxx...",      # Override the API Token - probably not useful
                                          user     => "xxxx...",      # Override the target user/group
                                       });

Notify will record the last message sent along with a timestamp. If the duplicate message is sent within a 60 second window, the message will be logged and dropped. A duplicate message is one with identical user ID, message text, title and priority. Although this permits a message to be sent to multiple users using repeated notify commands, it is preferable to define a group ID on the Pushover.net site to minimize traffic.

_checkReceipt(p_self)

Private callback routine used by the Timer to check if any pending receipts have been acknowledged. Once acknowledged, the receipt is deleted from the queue, and the acknowledgement is logged.

AUTHOR

George Clark

MODIFICATIONS

2016/04/29 Marc mhcoder@nowheremail.com Added html and device support on API call

LICENSE

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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Pushover.pm