@svobs/homebridge-messenger
Version:
Send HomeKit messages with HomeBridge (Pushover / IFTTT / Email). Forked to add support for Pushover custom sounds & TTL
199 lines (172 loc) • 9.71 kB
Markdown
<p align="center">
<img src="https://user-images.githubusercontent.com/1062160/79011991-45a1c680-7b33-11ea-9e34-ec5e9005f623.png" height="120"><br>
<img src="https://user-images.githubusercontent.com/1062160/79012099-7da90980-7b33-11ea-99a3-c69c322e875e.png" hspace="10px">
<img src="https://user-images.githubusercontent.com/1062160/80269083-a9230c80-867a-11ea-9bee-74dd68aa1bd0.png" hspace="10px" height="48px">
<img src="https://user-images.githubusercontent.com/1062160/79012203-c06ae180-7b33-11ea-81c3-ab43290011db.png" hspace="10px">
</p>
# homebridge-messenger
[](https://npmjs.com/package/homebridge-messenger)
[](https://npmjs.com/package/homebridge-messenger)
[](https://github.com/potrudeau/homebridge-messenger/issues)
[](https://github.com/potrudeau/homebridge-messenger/pulls)
[](LICENSE)
[](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
[Homebridge](http://homebridge.io) plugin which allow users to send messages from [HomeKit](https://developer.apple.com/homekit/). Forked from [Paul-Olivier Trudeau's original project](https://github.com/potrudeau/homebridge-messenger/security) to add support for Pushover custom sounds.
## Features
The plugin supports the following technologies:
* [Pushover](https://pushover.net/)
* [IFTTT](https://ifttt.com) ([Webhooks](https://ifttt.com/maker_webhooks) service)
* [SMTP email](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol)
## Installation
**Option 1: Install via Homebridge Config UI X:**
Search for "messenger" in [homebridge-config-ui-x](https://github.com/oznu/homebridge-config-ui-x) and install `homebridge-messenger`.
**Option 2: Manually Install:**
```
sudo npm install -g homebridge-messenger
```
## Configuration
The plugin adds to HomeKit a main switch and switches for each configured message.
The accessory **name** is used to specify the name of the main switch. If this main switch if turned OFF, no message will be sent by the plugin.
Message switches are stateless: they are turned OFF after being turned ON, once the message is sent.
There are two levels of configuration:
* **Service** level properties defines the parameters for a specific technology. All messages related to that technology will be using the same properties for all messages.
* Example: All emails will use the same SMTP configuration.
* **Message** level properties contains the configuration of each message.
* Example: Each message can have a different title and text.
All switches can be used in scenes and automation.
### Homebridge Config UI X
[Homebridge Config UI X](https://github.com/oznu/homebridge-config-ui-x) is the easiest way to configure this plugin :
* Every option is available through the UI
* Configuration validation
<img width="500" src="https://user-images.githubusercontent.com/1062160/80269563-e1c4e500-867e-11ea-86d7-eefdd5e31b90.png">
### Pushover
```
"accessories": [
{
"accessory": "HomebridgeMessenger",
"name": "Messenger",
"services": {
"pushover": {
"user": "your_user",
"token": "your_token"
}
},
"messages": [
{
"type": "pushover",
"name": "Pushover message",
"text": "This is a test",
"sound": "pushover",
"device" : "iphone",
"priority": 0,
"ttl": 600
},
{
"type": "pushover",
"name": "Critical message",
"text": "This is important",
"sound": "magic",
"priority": 2
}
]
}
]
```
* Service properties :
* user *(required)*: The user/group key of your user (or you).
* token *(required)*: Your application's API token.
* Message properties :
* type *(required)*: Must be `pushover`.
* name *(required)*: Name of the switch and title of your message.
* text *(required)*: Body of the message.
* sound *(facultative)*: Name of the sound that will notify the user. This can either be one of the built-in Pushover sounds, or the name of a custom sound you have uploaded to your application. If no value is provided, the default `pushover` sound will be used. For no sound, use `none`. The [Pushover API](https://pushover.net/api#sounds) contains the list of built-in sounds. To retrieve a dictionary of names & descriptions of all available sounds for your application including your custom sounds, send a GET request to `https://api.pushover.net/1/sounds.json?token=YourAppToken` after replacing `YourAppToken` with your application token.
* device *(facultative)*: The device name to send the message to. If not specified, the message will be send to all your devices. You can send to multiple devices by using a coma.
* ttl *(facultative)*: Time To Live = a number of seconds that the message will live, before being deleted automatically. Cannot be negative. If set to `0`, the message is effectively disabled. For infinite TTL, leave blank or remove key from config. This field will be ignored if the message's priority is `2`.
* priority *(required)*: Priority of the message. Accepted values are `-2`, `-1`, `0`, `1` or `2`. You may refer to the [Pushover API](https://pushover.net/api#priority) for more details. Critical messages (`2`), are sent with the following parameters :
* Retry : 60 seconds
* Expires: 3600 seconds
### IFTTT (Webhooks service)
```
"accessories": [
{
"accessory": "HomebridgeMessenger",
"name": "Messenger",
"services": {
"ifttt": {
"key": "your_key"
},
},
"messages": [
{
"type": "ifttt",
"name": "Test IFTTT",
"event": "my_webhook",
"value1": "hello world",
"value2": "foo bar",
"value3": "chewbacca"
}
]
}
]
```
* Service properties :
* key *(required)*: Your key. To obtain your key, log into your IFTTT account and click on the Documentation link in the [Webhooks service](https://ifttt.com/maker_webhooks).
* Message properties :
* type *(required)*: Must be `ifttt`.
* name *(required)*: Name of the switch. This will be **not** passed to IFTTT.
* event *(required)*: Name of your event configured in IFTTT (Webhooks service).
* value1 *(facultative)*: Value 1 to be passed to IFTTT.
* value2 *(facultative)*: Value 2 to be passed to IFTTT.
* value3 *(facultative)*: Value 3 to be passed to IFTTT.
### Email
```
"accessories": [
{
"accessory": "HomebridgeMessenger",
"name": "Messenger",
"services": {
"email": {
"recipient": "you_email@domain.com",
"smtpServer": "smtp.domain.com",
"smtpPort": 465,
"smtpSecure": true,
"smtpUsername": "your_username",
"smtpPassword": "your_password"
}
},
"messages": [
{
"type": "email",
"name": "Test email",
"text": "This is a test",
"recipients": "your_friend@domain.com, other_email@domain.com"
}
]
}
]
```
* Service properties :
* recipient *(required)*: Default email address of the recipient.
* smtpServer *(required)*: Address of the SMTP host.
* smtpPort *(facultative)*: Port to connect to. (Default value is `25`).
* smtpSecure *(facultative)*: Set to `true` if SMTP supports TLS. (Default value is `false`).
* smtpUsername *(facultative)*: Username for the SMTP server, if required.
* smtpPassword *(facultative)*: Password for the SMTP server, if required.
* Message properties :
* type *(required)*: Must be `email`.
* name *(required)*: Name of the switch and subject of your email.
* text *(required)*: Body of the email.
* recipients *(facultative)*: Address of the recipients for this email. Multiple emails can be used, divided by a comma. If empty, the default email address at the service level will be used.
### Advanced configuration
An example featuring **all technologies** is available [here](configuration-examples/advanced.example.json).
## Coming next
* Support for [Pushcut](https://www.pushcut.io/) ([#5](https://github.com/potrudeau/homebridge-messenger/issues/5))
* Support for [Pushbullet](https://www.pushbullet.com)
## Change Log
Available [here](CHANGELOG.md)
## Credits
* [qbit/node-pushover](https://github.com/qbit/node-pushover) - library to send Pushover messages
* [jeroentvb/IFTTT-webhooks-channel](https://github.com/jeroentvb/IFTTT-webhooks-channel) - library to send IFTTT messages
* [nodemailer](https://github.com/nodemailer/nodemailer) - library to send SMTP emails
## License
The [homebridge-messenger](https://github.com/potrudeau/homebridge-messenger) plugin is released under the [MIT license](LICENSE).