openhab-addons/bundles/org.openhab.binding.pushover

Pushover Binding

This binding allows you to notify mobile devices using the Pushover REST API. To get started, first register (a free process) to get an API token. Initially, create an application, set its name, and optionally upload an icon to get the API token in return. Once you have the token, you need a user key (or group key) and optionally a device name for each user to whom you want to push notifications.

Supported Things

There is only one Thing available: pushover-account. You can create multiple instances of this Thing to broadcast to different users, groups, or devices.

openHAB is listed as a featured application on the Pushover homepage. It provides a clone function to directly add a prefilled application to your Pushover account and retrieve an API key. You can reach it via https://pushover.net/apps/clone/openHAB.

Thing Configuration

Configuration Parameter	Type	Description
apikey	text	Your API token / key (APP_TOKEN) to access the Pushover Message API. mandatory
user	text	Your user key or group key (USER_KEY) to which you want to push notifications. mandatory
title	text	The default title of a message (default: openHAB).
format	text	The default format (none, html or monospace) of a message (default: none).
sound	text	The notification sound on target device (default: default) (see supported notification sounds). This list will be populated dynamically during runtime with 21 different sounds plus user-defined custom sounds.
retry	integer	The retry parameter specifies how often (in seconds) the Pushover servers will send the same emergency-priority notification to the user (default: 300). advanced
expire	integer	The expire parameter specifies how long (in seconds) your emergency-priority notification will continue to be retried (default: 3600). advanced
timeout	integer	The timeout parameter specifies maximum number of seconds a request to Pushover can take. advanced
idleTimeout	integer	The idle-timeout parameter specifies maximum number of seconds a connection with Pushover can be idle (default: 300). advanced

Channels

Currently the binding does not support any Channels.

Thing Actions

All actions return a Boolean value to indicate if the message was sent successfully. If communication to Pushover servers fails, the binding does not try to send the message again. You must handle retries yourself if necessary. The parameter message is mandatory; the title parameter defaults to whatever value you defined in the title configuration parameter. Parameters declared as @Nullable are not optional—you must pass a null value if the parameter should be skipped or if the default value should be used.

• sendMessage(String message, @Nullable String title, @Nullable String sound, @Nullable String url, @Nullable String urlTitle, @Nullable String attachment, @Nullable String contentType, @Nullable Integer priority, @Nullable String device, @Nullable Duration ttl) - This method is used to send a plain text message providing all available parameters.

• sendMessage(String message) - This method is used to send a plain text message with default title.

• sendMessage(String message, @Nullable String title) - This method is used to send a plain text message.

• sendMessage(String message, @Nullable String title, @Nullable Duration ttl) - This method is used to send a plain text message with TTL.

• sendHtmlMessage(String message, @Nullable String title) - This method is used to send a HTML message.

• sendHtmlMessage(String message, @Nullable String title, @Nullable Duration ttl) - This method is used to send a HTML message with TTL.

• sendMonospaceMessage(String message, @Nullable String title) - This method is used to send a monospace message.

• sendMonospaceMessage(String message, @Nullable String title, @Nullable Duration ttl) - This method is used to send a monospace message with TTL.

• sendAttachmentMessage(String message, @Nullable String title, String attachment, @Nullable String contentType) - This method is used to send a message with an attachment. It takes a local path or URL to the attachment (parameter attachment mandatory). Additionally you can pass a data URI scheme to this parameter. The content of an Image-type item is also accepted (see demo.rules example). Optionally pass a contentType to define the content-type of the attachment (default: image/jpeg or guessed from image data).

• sendAttachmentMessage(String message, @Nullable String title, String attachment, @Nullable String contentType, @Nullable Duration ttl) - This method is used to send a message with an attachment and TTL. See previous method for details.

• sendURLMessage(String message, @Nullable String title, String url, @Nullable String urlTitle) - This method is used to send a message with an URL. A supplementary url to show with the message and a urlTitle for the URL, otherwise just the URL is shown.

• sendURLMessage(String message, @Nullable String title, String url, @Nullable String urlTitle, @Nullable Duration ttl) - This method is used to send a message with an URL and TTL. See previous method for details.

• sendMessageToDevice(String device, String message, @Nullable String title) - This method is used to send a message to a specific device. Parameter device mandatory is the name of a specific device (multiple devices may be separated by a comma).

• sendMessageToDevice(String device, String message, @Nullable String title, @Nullable Duration ttl) - This method is used to send a message to a specific device with TTL. See previous method for details.

• sendPriorityMessage(String message, @Nullable String title, @Nullable Integer priority) - This method is used to send a priority message. Parameter priority is the priority to be used (-2 = lowest priority, -1 = low priority, 0 = normal priority, 1 = high priority, 2 = emergency priority; default: 2). For priority 2 only, the action returns a String value (the receipt) if the message was sent successfully, otherwise null. For other priorities, the action always returns an empty String.

• cancelPriorityMessage(String receipt) - This method is used to cancel an emergency priority message. The action returns a Boolean value to indicate if the message was cancelled successfully or not.

Full Example

demo.things:

Thing pushover:pushover-account:account [ apikey="APP_TOKEN", user="USER_KEY" ]

demo.rules:

:::: tabs

::: tab DSL

val actions = getActions("pushover", "pushover:pushover-account:account")
// send HTML message
actions.sendHtmlMessage("Hello <font color='green'>World</font>!", "openHAB")

:::

::: tab JavaScript

var pushoverActions = actions.thingActions('pushover', 'pushover:pushover-account:account');
// send HTML message
pushoverActions.sendHtmlMessage("Hello <font color='green'>World</font>!", "openHAB");

:::

::::

:::: tabs

::: tab DSL

val actions = getActions("pushover", "pushover:pushover-account:account")
// send message with attachment
actions.sendAttachmentMessage("Hello World!", "openHAB", "/path/to/my-local-image.png", "image/png")
actions.sendAttachmentMessage("Hello World!", "openHAB", "https://www.openhab.org/openhab-logo-square.png", null)
actions.sendAttachmentMessage("Hello World!", "openHAB", "data:[<media type>][;base64],<data>", null)
// in case you want to send the content of an Image Item (RawType)
actions.sendAttachmentMessage("Hello World!", "openHAB", myImageItem.state.toFullString, null)

:::

::: tab JavaScript

var pushoverActions = actions.thingActions('pushover', 'pushover:pushover-account:account');
// send message with attachment
pushoverActions.sendAttachmentMessage("Hello World!", "openHAB", "/path/to/my-local-image.png", "image/png");
pushoverActions.sendAttachmentMessage("Hello World!", "openHAB", "https://www.openhab.org/openhab-logo-square.png", null);
pushoverActions.sendAttachmentMessage("Hello World!", "openHAB", "data:[<media type>][;base64],<data>", null);
// in case you want to send the content of an Image Item (RawType)
pushoverActions.sendAttachmentMessage("Hello World!", "openHAB", items.myImageItem.rawState.toFullString(), null);

:::

::::

:::: tabs

::: tab DSL

val actions = getActions("pushover", "pushover:pushover-account:account")
// send priority message
var receipt = actions.sendPriorityMessage("Emergency!!!", "openHAB", 2)

// wait for your cancel condition

if( receipt !== null ) {
    actions.cancelPriorityMessage(receipt)
    receipt = null
}

:::

::: tab JavaScript

var pushoverActions = actions.thingActions('pushover', 'pushover:pushover-account:account');
// send priority message
var receipt = pushoverActions.sendPriorityMessage("Emergency!!!", "openHAB", 2);

// wait for your cancel condition

if (receipt !== null ) {
    pushoverActions.cancelPriorityMessage(receipt);
    receipt = null;
}

:::

::::

:::: tabs

::: tab DSL

val actions = getActions("pushover", "pushover:pushover-account:account")
// send expiring message
actions.sendMessage("Boost has been activated", "Recuperator", Duration.ofHours(1))

:::

::: tab JavaScript

var pushoverActions = actions.thingActions('pushover', 'pushover:pushover-account:account');
// send expiring message
pushoverActions.sendMessage("Boost has been activated", "Recuperator", time.Duration.ofHours(1));

:::

::::