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 Pushoveruser_key
oruser_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
classCall 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 userexpire
- 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 totitle
(string): your message’s title, otherwise your app’s name is useddevice
(string): your user’s device name to send the message directly to that devicedevice
(list of strings): your user’s devices names to send the message directly to that deviceurl
(string): a supplementary URL to show with your messageurl_title
(string): a title for your supplementary URL, otherwise just the URL is shownpriority
(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 usersound
(string): the name of the sound to override the user’s default sound choice (Use theSounds
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
see also https://pushover.net/api#receipt
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]¶ 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