mirror of
https://github.com/openhab/openhab-addons.git
synced 2025-01-10 23:22:02 +01:00
79 lines
5.1 KiB
Markdown
79 lines
5.1 KiB
Markdown
# Pushover Binding
|
|
|
|
The Pushover binding allows you to notify mobile devices of a message using the [Pushover REST API](https://pushover.net/api).
|
|
To get started you first need to register (a free process) to get an API token.
|
|
Initially you have to create an application, set its name and optionally upload an icon, and 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 which you want to push notifications.
|
|
|
|
## Supported Things
|
|
|
|
There is only one Thing available - the `pushover-account`.
|
|
You are able to create multiple instances of this Thing to broadcast to different users, groups or devices.
|
|
|
|
## 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 default notification sound on target device (default: `default`) (see [supported notification sounds](https://pushover.net/api#sounds)). |
|
|
| `retry` | integer | The retry parameter specifies how often (in seconds) the Pushover servers will send the same notification to the user (default: `300`). **advanced** |
|
|
| `expire` | integer | The expire parameter specifies how long (in seconds) your notification will continue to be retried (default: `3600`). **advanced** |
|
|
|
|
The `retry` and `expire` parameters are only used for emergency-priority notifications.
|
|
|
|
## Channels
|
|
|
|
Currently the binding does not support any Channels.
|
|
|
|
## Thing Actions
|
|
|
|
All actions return a `Boolean` value to indicate if the message - parameter `message` **mandatory** - was sent successfully or not.
|
|
The `title` parameter defaults to whatever value you defined in the `title` related configuration parameter.
|
|
|
|
`sendMessage(String message, @Nullable String title)` - This method is used to send a plain text message.
|
|
`sendHtmlMessage(String message, @Nullable String title)` - This method is used to send a HTML message.
|
|
`sendMonospaceMessage(String message, @Nullable String title)` - This method is used to send a monospace message.
|
|
`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 (`attachment` **mandatory**) to the attachment and an optional parameter `contentType` to define the content-type of the attachment (default: `image/jpeg`).
|
|
`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.
|
|
`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).
|
|
|
|
The `sendPriorityMessage` action returns a `String` value (the `receipt`) if the message was sent successfully, otherwise `null`.
|
|
|
|
`sendPriorityMessage(String message, @Nullable String title, @Nullable Integer priority)` - This method is used to send a priority message. Parameter `priority` is the priority (`-2`, `-1`, `0`, `1`, `2`) to be used (default: `2`).
|
|
|
|
`cancelPriorityMessage` returns a `Boolean` value to indicate if the message was cancelled successfully or not.
|
|
|
|
`cancelPriorityMessage(String receipt)` - This method is used to cancel a priority message.
|
|
|
|
## Full Example
|
|
|
|
demo.things:
|
|
|
|
```java
|
|
Thing pushover:pushover-account:account [ apikey="APP_TOKEN", user="USER_KEY" ]
|
|
```
|
|
|
|
demo.rules:
|
|
|
|
```java
|
|
val actions = getActions("pushover", "pushover:pushover-account:account")
|
|
// send HTML message
|
|
actions.sendHtmlMessage("Hello <font color='green'>World</font>!", "openHAB")
|
|
```
|
|
|
|
```java
|
|
val actions = getActions("pushover", "pushover:pushover-account:account")
|
|
// send priority message
|
|
var receipt = actions.sendPriorityMessage("Hello <font color='green'>World</font>!", "openHAB", 3)
|
|
|
|
// wait for your cancel condition
|
|
|
|
if( receipt !== null ) {
|
|
actions.cancelPriorityMessage(receipt)
|
|
receipt = null
|
|
}
|
|
```
|