README
¶
Pushover
Go package for the Pushover API.
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:
- Implement other Pushover APIs
- Use of environment variables for API token in the CLI
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.
Documentation
¶
Overview ¶
Package pushover implements access to the Pushover API
This documentation can be considered a supplement to the official Pushover API documentation at https://pushover.net/api. Refer to that official documentation for the details on how to us these library functions.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ErrInvalidRequest ¶
type ErrInvalidRequest struct{}
ErrInvalidRequest indicates invalid request data was sent to a library function
func (*ErrInvalidRequest) Error ¶ added in v1.0.6
func (ir *ErrInvalidRequest) Error() string
type ErrInvalidResponse ¶
type ErrInvalidResponse struct{}
ErrInvalidResponse indicates an invalid response body was received from the Pushover API
func (*ErrInvalidResponse) Error ¶ added in v1.0.6
func (ir *ErrInvalidResponse) Error() string
type MessageRequest ¶
type MessageRequest struct {
// The URL for the Pushover REST API POST.
//
// Leave this empty unless you wish to override the URL.
PushoverURL string
// Pushover API token
Token string
// The user's token for message delivery
User string
// The message sent to the user
Message string
// Message title
Title string
// Embedded URL
URL string
// The displayed text for the URL
//
// If the field URL is missing, the title will be
// displayed as normal text
URLTitle string
// Enable HTML formatting of the message
//
// See the Pushover REST API documentation for allowed tags
HTML string
// Enable monospace formatting of the message
Monospace string
// Sound name for the sound on the user's device
//
// See the Pushover REST API documentation for valid
// values. Invalid sound names will not be rejected by
//Pushover
Sound string
// The device to send the message to rather than all the
// user's devices.
//
// Devices not registered will not be rejected by Pushover
// and will therefore fail silently.
Device string
// Priority number for the message
//
// See the Pushover REST API documentation for values and
// what they mean
//
// Invalid priority numbers will be rejected by Pushover
Priority string
// How often in seconds the Pushover servers will send
// the same notification to the user
//
// Must be set when Priority is set to "2" and must
// have a value of at least 30 seconds between retries
Retry string
// How many seconds your notification will continue to
// be retried for (every retry seconds)
//
// Must be set when Priority is set to "2" and must
// have a maximum value of at most 10800 seconds
// (3 hours)
Expire string
// Callback url for the message
//
// Optional be set when Priority is set to "2"
Callback string
// Unix timestamp for the message rather than the time
// the message was received by the Pushover REST API
//
// Invalid timestamps will not be rejected by Pushover
Timestamp string
// Reader for image (attachment) data
ImageReader io.Reader
// Optional image name
//
// Leave blank to default to image.jpg
ImageName string
}
MessageRequest is the data for the POST to the Pushover REST API. Some fields in this request should contain numbers but the Pushover API parameters are strings. There is no validation performed for these fields. If invalid data is submitted to the Pushover API, it will be rejected with an appropriate error.
See the Pushover API documentation for more information on these parameters.
type MessageResponse ¶
type MessageResponse struct {
// Original response body from POST
ResponseBody string
// HTTP Status string
HTTPStatus string
// HTTP Status Code
HTTPStatusCode int
// The status as returned by the Pushover API.
//
// Value of 1 indicates 200 response received.
// Any other value indicates an error with the
// input.
APIStatus int
// ID assigned to the request by Pushover
Request string
// Receipt
//
// When a priority of 2 is given, a receipt field
// is returned
Receipt string
// List of errors returned
//
// Empty if no errors
Errors []string
// Map of parameters and corresponding errors
//
// Empty if no errors
ErrorParameters map[string]string
}
MessageResponse is the response from this API. It is read from the body of the Pushover REST API response and translated to this response structure.
For access to the original, untranslated response, access the ResponseBody field.
func Message ¶
func Message(request MessageRequest) (*MessageResponse, error)
Message will submit a request to the Pushover Message API. This function will send a message, triggering a notification on a user's device or a group's devices.
resp, err := pushover.Message(pushover.MessageRequest{
Token: token,
User: user,
Message: message,
})
func MessageContext ¶
func MessageContext(ctx context.Context, request MessageRequest) (*MessageResponse, error)
MessageContext will submit a request to the Pushover Message API. This function will send a message, triggering a notification on a user's device or a group's devices.
resp, err := pushover.MessageContext(context.Background(),
pushover.MessageRequest{
Token: token,
User: user,
Message: message,
})
type ValidateRequest ¶
type ValidateRequest struct {
// The URL for the Pushover REST API POST.
//
// Leave this empty unless you wish to override the URL.
PushoverURL string
// Pushover API token
Token string
// The user's token to validate
User string
// User device to validate (optional)
Device string
}
ValidateRequest is the data to POST to the Pushover REST API. See the Pushover Validate API documentation for more information on these parameters.
type ValidateResponse ¶
type ValidateResponse struct {
// Original response body from POST
ResponseBody string
// HTTP Status string
HTTPStatus string
// HTTP Status Code
HTTPStatusCode int
// The status as returned by the Pushover API.
//
// Value of 1 indicates 200 response received.
// Any other value indicates an error with the
// input.
APIStatus int
// This field is returned but not documented
// by the Pushover Validate API
Group int
// ID assigned to the request by Pushover
Request string
// List of registered devices
Devices []string
// List of licensed platforms
Licenses []string
// List of errors returned
//
// Empty if no errors
Errors []string
// Map of parameters and corresponding errors
//
// Empty if no errors
ErrorParameters map[string]string
}
ValidateResponse is the response from this API. It is read from the body of the Pushover REST API response and translated to this response structure.
For access to the original, untranslated response, access the ResponseBody field.
func Validate ¶
func Validate(request ValidateRequest) (*ValidateResponse, error)
Validate will submit a POST request to the Pushover Validate API This function will check a user or group token to determine if it is valid.
resp, err := pushover.Validate(pushover.ValidateRequest{
Token: token,
User: user,
})
func ValidateContext ¶
func ValidateContext(ctx context.Context, request ValidateRequest) (*ValidateResponse, error)
ValidateContext will submit a POST request to the Pushover Validate API. This function will check a user or group token to determine if it is valid.
resp, err := pushover.ValidateContext(context.Background(),
pushover.ValidateRequest{
Token: token,
User: user,
})
Source Files
Directories