Pushover Glances API

With Pushover's Glances API, you can push small bits of data directly to a constantly-updated screen, referred to as a widget, such as a complication on your smart watch or a widget on your phone's lock screen. This API is separate from our Message API since it does not generate push notification alerts or sounds, and messages are not stored in the Pushover clients.

Our Glances API is used for sending short pieces of text or numerical data, such as "Garage door open" in response to an alarm system, or just "30" representing the number of items sold in your store today. These pieces of data should be low-priority since they often cannot get updated in real-time or very frequently, and they must be concise because they are often viewed on small screens such as a watch face.

 

Widgets

Each screen showing glance data is referred to as a widget, and currently widgets must be attached to devices that run our iOS and Android clients. When performing a Glance API call for a user, the user must have a widget already registered on their device, which is done automatically when creating the widget or adding the Pushover complication to Apple Watch. You can see the status of your registered widget on your dashboard under Your Devices.

Note: at this time, the Apple Watch is the only supported widget. Android and iOS widgets will be supported in future versions of our apps.

Limitations

In addition to the per-field limits detailed below, there are platform-specific limitations that must be taken into account:

Apple Watch
Pushing data to the Apple Watch must be done infrequently, or WatchOS will stop processing updates due to battery concerns. Please note that Pushover does not do any throttling of your data updates, so it is up to you to throttle your Glances API calls. When sending data to the Apple Watch, we recommend at least 20 minutes between each call, and watchOS implements a limit of 50 updates per day. If you have pushed too much data and WatchOS stops processing updates, this resets overnight.

Remember, the data presented through our Glances API should be low-priority (something to be occasionally glanced at). If you need to send data that is delivered right away and presented to the user, use our Messages API.

Available Data Fields

Currently the following fields are available for updating. Each field is shown differently on different screens, so you may need to experiment with them to find out which field works for you given your screen and type of data. For example, each watch face on the Apple Watch uses a different sized complication, with different size specifications and types of data. Some are text strings, some are just numbers.

• title (100 characters) - a description of the data being shown, such as "Widgets Sold"
• text (100 characters) - the main line of data, used on most screens
• subtext (100 characters) - a second line of data
• count (integer, may be negative) - shown on smaller screens; useful for simple counts
• percent (integer 0 through 100, inclusive) - shown on some screens as a progress bar/circle

Updating Data

It's important to note that our Glances API stores the current state of all available fields for a given screen and only discards data when the field is overwritten by your API call. If your API call only updates one field of data, the other fields will retain the data from your previous calls. This is useful for using our API to aggregate data from multiple, independent sources and collecting it all on the destination screen.

All Glances API calls must include a token parameter of an application's API token, and the recipient user's user key in the parameters. If you do not already have an API token, you must register an application first. You can find your own user key on your dashboard.

To send an update to your widget, make a POST request to:

You must supply the following parameters as POST data:

• token (required) - your application's API token
• user (required) - the user's Pushover user key
• device (optional) a user's device name to restrict messages to the widget on that device, otherwise leave blank to send messages to all available widgets of that user

In addition to these required parameters, you must supply at least one of the data fields listed above, such as text.

To clear a previously-updated field, send the field with a blank (empty string) value.

Note: Due to the way glance data is delivered to widgets and their power constraints, it may take up to 10 minutes for your data to be reflected. Please be patient when testing.

Response Format

As with all of our API calls, you will receive a status parameter in your response, and a random request identifier that you can use when contacting us for support. When your API call was successful, status will be 1.

{"status":1,"request":"5135d73e-de3d-4458-b79c-b3b2a9ef6c40"}

If the API call failed for any reason, you will receive an HTTP 400 status with a JSON object containing a status of 0 and an errors array detailing each problem.

{"status":0,
"request":"7903bd1b-6aa2-43e6-9c1c-bb5ccea848f1",
"errors":[ "application token is invalid" ]}

Any non-200 or non-400 status should be interpreted as an error.