homebridge-messenger

Homebridge plugin which allow users to send messages from HomeKit. Forked from Paul-Olivier Trudeau's original project to add support for Pushover custom sounds.

Features

The plugin supports the following technologies:

• Pushover
• IFTTT (Webhooks service)
• SMTP email

Installation

Option 1: Install via Homebridge Config UI X:

Search for "messenger" in 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 is the easiest way to configure this plugin :

• Every option is available through the UI
• Configuration validation

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 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 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.
• 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.

Coming next

• Support for Pushcut (#5)
• Support for Pushbullet

Change Log

Available here

Credits

• qbit/node-pushover - library to send Pushover messages
• jeroentvb/IFTTT-webhooks-channel - library to send IFTTT messages
• nodemailer - library to send SMTP emails

License

The homebridge-messenger plugin is released under the MIT license.