Pushover Delivery Groups API

Delivery Groups allow broadcasting the same Pushover message to a number of different users at once with just a single group token, used in place of a user token (or in place of specifying multiple user keys in every request). Subscriptions allow end users to subscribe and unsubscribe from receiving notifications from your application without any intervention on your part, which can include adding themselves to and removing themselves from a delivery group you associate with the subscription. For most cases, a subscription backed by a delivery group provides all of the automation needed to broadcast messages to a list of users.

For situations where subscriptions are not appropriate, or where automated manipulation of group members is required, such as changing an on-call notification group, or syncing with an external directory system, our Groups API is available.

All Groups API calls must include a token parameter of an application's API token, and the delivery group's key in the URL. If you do not already have an API token, you must register an application first. Note: any application can send messages to your group's key, but to use the Groups API, an application token belonging to the same account as the group must be supplied for authentication.

Response Format

All Groups API calls will respond with a format similar to our other APIs. If your POST or GET request to our API was valid, you will receive an HTTP 200 (OK) status, with a JSON object containing a status code of 1.

{"status":1,"request":"f51d971c-ca76-4646-8c53-f1e72cfb2212"}

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":"0b03d2fc-c223-4947-912a-d32244fc6c16",
"errors":[ "application token is invalid" ]}

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

Retrieving Information About a Group

To fetch a list of users in a group and see its name, submit a GET request to:

A JSON object will be returned containing the group's name along with a users array listing each member of the group as a JSON object containing user, device, memo, and disabled parameters. For Team-owned groups, Team members in the group will have their name and email returned as well.

{
"status":1,
"request":"4044780a-8b6d-4416-9c0f-f123bc1b6450",
"name":"My Delivery Group",
"users":[
{"user":"uoJCttEFQo8uoZ6REZHMGBjX2pmcdJ","device":null,"memo":"Jim","disabled":false},
{"user":"uZgLtMeFSRgdxLbpWbDDPM9v4wmEKu","device":"iphone","memo":"Mary","disabled":false},
]}

Adding a User to a Group

To add an existing Pushover user to your Delivery Group, you must obtain the user's Pushover user key and submit a POST request to:

Include the following parameters:

• token (required) - your application's API token (any application on the account owning the group will suffice)
• user (required) - the user's Pushover user key
• device (optional) a user's device name to restrict messages to that device, otherwise leave blank to send messages to all devices of that user
• memo (optional) a free-text memo used to associate data with the user such as their name or e-mail address, viewable through the API and the groups editor on our website (limited to 200 characters)

Removing a User From a Group

To remove an existing Pushover user to your Delivery Group, submit a POST request to:

Include the following parameters:

• token (required) - your application's API token (any application on the account owning the group will suffice)
• user (required) - the user's Pushover user key

Temporarily Disabling a User in a Group

To temporarily stop sending notifications to a particular user in a group, submit a POST request to:

Include the following parameters:

• token (required) - your application's API token (any application on the account owning the group will suffice)
• user (required) - the user's Pushover user key

Re-enabling a User in a Group

To resume sending notifications to a particular user in a group, submit a POST request to:

Include the following parameters:

• token (required) - your application's API token (any application on the account owning the group will suffice)
• user (required) - the user's Pushover user key

Renaming a Group

To change the name of a group (reflected in the API and in the group editor on our website), submit a POST request to:

Include the following parameters:

• token (required) - your application's API token (any application on the account owning the group will suffice)
• name (required) - the new name of the group

Note that only one group with a particular name may exist on an account.