Items Pushover
See original
This module allows MisterHouse to send notification messages to Pushover.net clients. See https://pushover.net/ for details of the service and API.
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:
#
CODE, require Pushover; #noloop
CODE, my $push = new Pushover(); #noloopA user code file overriding parameters normally specified in mh.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 });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.
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
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_"
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.
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.
George Clark
MODIFICATIONS 2016/04/29 Marc mhcoder@nowheremail.com Added html and device support on API call