Messages¶

PyPushover mirrors Pushover’s API for sending messages. This means we follow the same process and have the same requirements in order to send messages. Mainly:

app_token - you registered applications token from Pushover
user_key or user_key - the user or group’s key to send the message to

For more information about how to register your application, please visit Pushover’s site (https://pushover.net/api#registration)

message.py - Message handling for the Pushover API¶

This module defines functions and classes used for handling messages sent to the Pushover servers. Messages can be sent using either the MessageManager class or calling the functions directly. Using the MessageManager class reduces the need to send the app_token and group/user key for each sending of a message.

Sending messages can be done using the send_message method of the MessageManager class or the send_message function found within this module. There are API restrictions that are required by Pushover but are NOT handled by py_pushover. It is intended that the user will maintain all of these requirements.

Sending Basic Messages¶

Sending a basic message requires the following:

an application token
a group or user key
the message text

Examples using the MessageManager class and the push_message function are as follows:

Using the `MessageManager` class:¶

Create an object of the MessageManager class

Call the send_message method

>>> import pypushover as pypo
>>> pm = pypo.message.MessageManager('<app_token>', '<group/user key>')
>>> pm.push_message('Message Body')

Using the function call:¶

>>> pypo.message.push_message('<app_token>', '<group/user key>', 'Message Body')

Sending Emergency Priority Messages¶

Emergency Priority messages are messages that are intended to be read by the user immediately and require an acknowledgement for dismissal. When passing in a priority of Emergency (pypushover.PRIORITIES.EMERGENCY), two additional parameters are required:

retry - how often (in seconds) the Pushover servers will retry the notification to the user
expire - how many seconds your notification will continue to be retried

Below is an example:

>>> res = pm.send_message('Emergency Message!', priority=pypo.PRIORITIES.EMERGENCY, retry=30, expire=3600)
>>> res = pypo.message.push_message(
...     '<app_token>',
...     '<group/user key>',
...     'Emergency Message!',
...     priority=pypo.PRIORITES.EMERGENCY,
...     retry=30,
...     expire=3600
... )

After an emergency message is sent, it’s status can be queried using check_receipt. The parameter passed in, is the emergency messages response receipt parameter.

>>> pm.check_receipt(res['receipt'])
>>> pypo.message.check_receipt('app_token', res['receipt'])

If you decide to cancel Pushover’s repeated tries to send an Emergency Priority message, use the cancel_retries with the receipt parameter passed in.

>>> pm.cancel_retries(res['receipt'])
>>> pypo.message.cancel_retries('app_token', res['receipt'])

Other Supported Parameters¶

user (string): user or group id to send the message to
title (string): your message’s title, otherwise your app’s name is used
device (string): your user’s device name to send the message directly to that device
device (list of strings): your user’s devices names to send the message directly to that device
url (string): a supplementary URL to show with your message
url_title (string): a title for your supplementary URL, otherwise just the URL is shown
priority (string): message priority (Use the Priorities constants to select)
timestamp (string): a Unix timestamp of your message’s date and time to display to the user
sound (string): the name of the sound to override the user’s default sound choice (Use the Sounds constants to

select)

class message.MessageManager(app_token, receiver_key=None)[source]¶

Manager class used to send messages and check receipts. Stores the given app_token for future use. Also stores the latest response from the API.

cancel_retries(receipt=None)[source]¶

Cancel an emergency-priority notification early.

Parameters:	receipt (string) – the notification receipt to cancel (if none given, the most recent response is used)

check_receipt(receipt=None)[source]¶

Gets the receipt status of the selected notification. Returns a dictionary of the results

Parameters:	receipt (string) – the notification receipt to check (if none given, the most recent response is used)
Return dict:

push_message(message, **kwargs)[source]¶

Send message to selected user/group/device.

Parameters:

token (str) – application token
user (str) – user or group id to send the message to
message (str) – your message
title (str) – your message’s title, otherwise your app’s name is used
device (list) – your user’s device name to send the message directly to that device
device – your user’s devices names to send the message directly to that device
url (str) – a supplementary URL to show with your message
url_title (str) – a title for your supplementary URL, otherwise just the URL is shown
priority (int) – message priority (Use the Priority class to select)
retry (int) – how often (in seconds) the Pushover servers will retry the notification to the user (required only with priority level of Emergency)
expire (int) – how many seconds your notification will continue to be retried (required only with priority level of Emergency)
timestamp (datetime) – a datetime object repr the timestamp of your message’s date and time to display to the user
sound (str) – the name of the sound to override the user’s default sound choice (Use the Sounds consts to select)
html (bool) – Enable rendering message on user device using HTML

message.cancel_retries(token, receipt)[source]¶

Ceases retrying to notify the user of an Emergency Priority notification.

Cancel an emergency-priority notification early. :param str token: application token :param str receipt: receipt of the message

message.check_receipt(token, receipt)[source]¶

Check to see if an Emergency Priority notification has been acknowledged.

Parameters:	token (str) – the application token receipt (str) – the message receipt
Returns:

message.push_message(token, user, message, **kwargs)[source]¶