Skip to content

arcanericky/pushover

Repository files navigation

Pushover

Go package for the Pushover API.

Build Status codecov GoDoc PRs Welcome

About

This package enables your Go application to send requests to the Pushover service through the Pushover REST API. Implementing a notification message in your Go code is as simple as pushover.Message(pushover.MessageRequest{User: "user", Token: "token", Message: "message"}). It's just a straightforward function call - no fancy methods attached to functions, just populate a structure and Go.

Note that Pushover has many APIs available, but currently this package only supports:

The Pushover service is a great way to send notifications to your device for any purpose. The device application is free for 7 days, after which you must purchase it for a one-time price of $4.99 per platform. It comes with a 7,500 message per month limit with the ability to pay for more messages.

Using the Package

Obtaining a Pushover account and adding an application for using this library are not covered in this README. Pushover API and user tokens are required.

To use this Pushover package (with Go 1.13+), just import it and make a single call to pushover.Message.

$ cat > main.go << EOF
package main

import (
  "fmt"
  "os"
  "github.com/arcanericky/pushover"
)

func main() {
  var r *pushover.MessageResponse
  var e error

  if r, e = pushover.Message(pushover.MessageRequest{Token: os.Args[1], User: os.Args[2], Message: os.Args[3]}); e != nil {
    fmt.Println(e)
    return
  }
  fmt.Println(r)
}
EOF
$ go mod init demo
$ go build
$ ./demo api-token user-token "Test Message"

Using the Utility

A simple application to demonstrate and test the Pushover package is included with this repository in Released executables and is useful on its own. While using Pushover via curl is simple enough, this utility makes it even easier.

$ pushover message --token token --user user --message message

For help, use the --help option.

$ pushover --help
Pushover CLI version 1.0.0

Submit various requests to the Pushover API. Currently only
message (notification) and validate are supported.

See the README at https://github.com/arcanericky/pushover for
more information. For details on Pushover, see
https://pushover.net/.

Usage:
  pushover [command]

Available Commands:
  help        Help about any command
  message     Submit a message request
  validate    Submit a validate request

Flags:
  -h, --help      help for pushover
      --version   version for pushover

Use "pushover [command] --help" for more information about a command.

And for help with the various subcommands, issue the subcommand followed by --help.

$ pushover message --help
Send a Pushover message to a user or group.

Required options are:
  --token
  --user
  --message

Usage:
  pushover message [flags]

Flags:
      --callback string      Optional callback URL
      --device string        Device name for message
      --expire int16         Message expiration length
  -h, --help                 help for message
      --html                 Enable HTML formatting
      --image string         Image attachment
  -m, --message string       Notification message
      --monospace            Enable monospace formatting
      --priority int8        Message priority
      --pushoverurl string   Pushover API URL
      --retry int16          Retry interval
      --sound string         Name of a sound to override user's default
      --timestamp string     Unix timestamp for message
      --title string         Message title (if empty, uses app name)
  -t, --token string         Application's API token
      --url string           Supplementary URL to show with the message
      --urltitle string      Title for the URL
  -u, --user string          User/Group key

Contributing

Contributions and corrections are welcome. If you're adding a feature, please submit an issue so it can be discussed and ensure the work isn't being duplicated. Unit test coverage is required for all pull requests.

Some features that are not implemented but would be welcome:

Inspiration

During my development workday I often find I need to monitor state of systems, programs, networks, etc. Eventually I concluded the Pushover service was best for me and I've been using it in some monitoring scripts using curl. One day I found a need to do this in one of my Go utilities and that's when this code was started.