Pushover Open Client API

Pushover now features a public client API for advanced users to write their own native clients to receive push notifications like our official mobile and desktop clients. While this API is in beta, there may be small changes to server responses or recommended behavior, but there will most likely not be any large backwards-incompatible changes.

Licensing for Open Clients is done as a desktop device, so a user must have or purchase a Pushover for Desktop license within 30 days of activation of an Open Client device to continue using it.

Before creating (and especially before distributing) your own client, please see our distribution guidelines.

TL;DR

1. Login with a Pushover account e-mail address and password, then securely store the session secret.
2. Register your device and store its uuid.
3. Download all outstanding messages and then delete them from our servers. In most cases you will not want to generate notifications for these old messages.
4. Establish a websocket connection to our servers and listen for notification of a new message.
5. When new messages are pending, download them, do some action with them such as generate a local notification, and then delete them from our servers.

User Login

All API actions that deal with device clients require a user session secret, which is a randomly generated token assigned at login time and is unique to each login. A session secret should not be re-used between devices.

If the user does not yet have a Pushover account, direct them to https://pushover.net/signup. Once the user has account, you can retrieve the user's Pushover key and a secret by submitting a POST request to our users/login endpoint:

Include the email and password parameters for the user you are logging in as. Both values are case-sensitive. If the login was successful, you will receive a JSON object with status set to 1 (as with all of our API functions), the user's Pushover user key (id), and the user's session secret. Store these values in a secure manner and discard the password.

$ curl \
--form-string "[email protected]" \
--form-string "password=hunter2" \
https://api.pushover.net/1/users/login.json

{"status":1,
"request":"7df577c3-da18-4fb3-898b-c1ab4985633b",
"id":"uQiRzpo4DXghDmr9QzzfQu27cmVRsG",
"secret":"SGx2Su5onMcXU2EVozWG41Fws42bHo0aOrmA3tQ3jjRMSu1HwMEmOWNWPD7J"}

If the response has an HTTP status 412 (the status in the JSON response will be 0), the user's account requires two-factor authentication to login. Prompt the user for their current two-factor authentication code and submit the login request again with the previous email and password parameters, in addition to the user's two-factor code as the twofa parameter.

Device Registration

Once you have the user's session secret, you can register a new Desktop device by submitting a POST request to our devices endpoint:

Include the user's secret, the short name of the device ([A-Za-z0-9_-], up to 25 characters long), and an os value of O (capital 'o', not zero) for Open Client. If the device creation was successful, you will receive a JSON object with the device's unique id. Store this value in a secure location.

$ curl \
--form-string "secret=SGx2Su5onMcXU2EVozWG41Fws42bHo0aOrmA3tQ3jjRMSu1HwMEmOWNWPD7J" \
--form-string "name=my_device" \
--form-string "os=O" \
https://api.pushover.net/1/devices.json

{"status":1,
"request":"5e400a78-127b-4078-85e7-8f63cc78c9b2",
"id":"zQie8WjzFTWkMz5CcGrUNK2t5rR9zGTsfYQ7HHGs"}

If registration of the device failed for any reason (such as the device name being invalid or in use already), you will get a status of 0 and an errors object detailing each problem.

{"status":0,
"request":"ffb7a544-befe-4f46-b901-e15c4e399e5f",
"errors":{"name":["has already been taken"]}}

Message Downloading

When your client starts up, it should download all existing messages waiting for the device. If your client has not been run in a while, these messages are probably old so you will most likely want to discard them rather than spamming the user with a bunch of notifications at startup.

To download all pending messages for a device, submit a GET request to our messages endpoint:

Include the user secret and device_id parameters in the GET request, and a JSON object will be returned with all of the device's messages.

$ curl "https://api.pushover.net/1/messages.json?secret=SGx2Su5onMcXU2EVozWG41Fws42bHo0aOrmA3tQ3jjRMSu1HwMEmOWNWPD7J&device_id=zQie8WjzFTWkMz5CcGrUNK2t5rR9zGTsfYQ7HHGs"

{"status":1,
"request":"36fddffb-9f62-444b-bd17-5e7c7febb258",
"messages":[
{"id":380698801670733826,"id_str":"380698801670733826","message":"This message confirms that you are now able to receive messages on this device (my_device).\n\nVisit https://pushover.net/apps to view apps, plugins, and services to use with Pushover.","app":"Pushover","aid":380698715771387905,"aid_str":"380698715771387905","icon":"HopmnR5uQ4cmXen","date":1409605784,"priority":0,"acked":0,"umid":380698801670733826,"umid_str":"380698801670733826","title":"Welcome to Pushover!"},
{"id":380698969174458372,"id_str":"380698969174458372","message":"test","app":"Pushover","aid":380698715771387905,"aid_str":"380698715771387905","icon":"default","date":1409605795,"priority":0,"acked":0,"umid":380699115203346437,"umid_str":"380699115203346437","title":""}
]}

A successful message download will have a status code of 1 and a messages array. Each object in the messages array will include at least the following fields, though others may be present which can be ignored:

Message Deleting

After you have successfully downloaded all outstanding messages from our server, stored them, processed them, and done whatever action you need to with them (such as generating a local notification), you should delete those messages from our server. This is done by submitting a POST request to update_highest_message with the device id in the URL:

In addition to the device id in the URL, the POST parameters must include the user's secret and the message POST parameter set to the highest message id value that you saw in the previous message download. Once this responds with a status of 1, all messages for that device up to and including the supplied message id will have been permanently deleted.

$ curl \
--form-string "secret=SGx2Su5onMcXU2EVozWG41Fws42bHo0aOrmA3tQ3jjRMSu1HwMEmOWNWPD7J" \
--form-string "message=2" \
https://api.pushover.net/1/devices/zQie8WjzFTWkMz5CcGrUNK2t5rR9zGTsfYQ7HHGs/update_highest_message.json

{"status":1,
"request":"040c63bc-e4b2-4496-b767-db37be2edb7b"}

Real-Time Message Notification

Now that your client has downloaded and deleted all outstanding messages, you can now connect to our WebSocket server and listen for real-time notification of new messages. WebSocket is a relatively new and complex protocol that "upgrades" an existing HTTPS connection to our web servers, enabling a full-duplex frame-based communication mode.

Please note that our web servers' primary compatibility will be for the major web browsers Firefox, Chrome, and Safari, to work with our own Desktop client. If your client is unable to establish or maintain a WebSocket connection to our web servers due to incompatibilities with your WebSocket implementation, we will most likely not be able to make any accommodations on our web servers.

To start listening for new messages, establish a secure WebSocket connection over HTTPS to our web server at:

Once your WebSocket connection has been established, you must login with the user's secret and the Open Client device's id. This is done by sending "login:", followed by the device's id, followed by a colon (:), followed by the user's secret, and then terminated by a newline character (ASCII 10).

login:zQie8WjzFTWkMz5CcGrUNK2t5rR9zGTsfYQ7HHGs:SGx2Su5onMcXU2EVozWG41Fws42bHo0aOrmA3tQ3jjRMSu1HwMEmOWNWPD7J\n

If your login was successful, your connection will remain open and you will begin receiving data. If your login failed, you will receive an error frame (detailed below) and your connection will be closed.

Our WebSocket data protocol is very compact, intended to save bandwidth while preventing overly aggressive firewalls from closing seemingly-idle connections. While you are connected to our WebSocket server, you will receive frames with one of the following single-byte characters:

When your WebSocket connection receives a ! frame indicating that new messages are available, your client should open a new, secondary HTTPS connection to our API to do a download and delete, as well as any other API calls such as fetching application icons, message sounds, etc.

Emergency-Priority Messages

As with our native device clients, we will send repeated notifications to Open Client connections for emergency-priority messages according to the message receipt's retry parameter until its expire parameter has been reached.

When your client downloads a message with a priority of 2 (or higher, for future compatibility) that does not have an acked value of 1, it should present the notification to the user in such a way that gets the user's attention, such as a modal dialog, until it is manually dismissed by the user. When the user acknowledges the notification by performing some action (such as clicking a button, not just when the notification times out), you must submit an API call to acknowledge the receipt and stop repeated notifications.

To acknowledge an emergency-priority message, submit a POST request to the following URL, including the message's receipt parameter in the URL:

Along with your POST request, include your user's secret parameter.

Being Friendly to our API

As with our Message API guidelines, the way our servers respond is critical in determining how your client should react. If our servers respond with a 200 HTTP code and a status of 1, you've done well. Any other response, such as a 4xx or 5xx HTTP code, or a status of 0 means something went wrong. When something goes wrong, don't retry the same query over and over without any delay.

If our WebSocket server drops your connection after a successful login, wait some time before reconnecting.

In all HTTP calls to our API, your application must send a User-Agent header that clearly shows the name (and other useful information such the version or OS) of your application. This will help us identify any potential problems with users of your application.

Distribution Guidelines

Pushover's Open Client API is intended for advanced users to write their own native clients to receive push notifications on platforms we do not support. Applications using the Pushover Open Client API must follow our Logos and Usage guidelines. In particular, your client may not use the Pushover logo as its main application icon, it may not use Pushover in its name (e.g., "Pushover for x"), it must clearly state that it is an unofficial Pushover Open Client, and that it is not released or supported by Pushover.

• You may not store Pushover account or device information in any location that the Pushover user does not have sole control over. You may not make a server-based client that users login to and then act on their behalf. All Open Client functionality must be done on the user's device/computer and be controlled by the user. This is to limit exposure of a user's e-mail address, password, and/or account secret.
• You may release your Open Client application in binary or source code form and you may charge money for it, but you cannot intervene in licensing the end-user's account (as a Pushover for Desktop license is required to use any Open Client applications).
• You may not do bulk purchases of Pushover for Desktop licenses and then resell them to your users.
• You must direct users to our website at https://pushover.net/ for account creation and licensing.
• Your client may not be used for delivering notifications to multiple users of a single Pushover account.

In general, don't be a jerk. Don't abuse our Open Client API to get around our licensing, don't try to hide that your client uses Pushover for its message delivery, and don't abuse our API and servers. We rely on users paying for licenses to be able to continue developing and supporting Pushover.

If you have any questions about whether your Open Client is complying with our guidelines, please contact us before developing or releasing it. We'll be happy to answer any questions.