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 key, used in place of a user key (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 where appropriate. 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.

Creating a Group

To create a new group, submit a POST request to:

Include the following POST parameters:

• token (required) - your application's API token (any application on the account or team will suffice)
• name (required) - the group's name

A JSON object will be returned containing a group of the new group's key.

{
"status":1,
"request":"253b083d-6a40-4948-9173-563d14d22463",
"group":"go4abk17j3itsva6thz99mdudgq2gm"
}

Retrieving Groups

To fetch a list of groups, submit a GET request to:

A JSON object will be returned containing a groups array listing each group with its group key and name.

{
"status":1,
"request":"253b083d-6a40-4948-9173-563d14d22463",
"groups":[
{"group":"go4abk17j3itsva6thz99mdudgq2gm","name":"my group"}
]}

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 POST 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 POST 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) - the device name to match for the user's group membership; if left blank, all users with the matching user key will be removed

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 POST 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) - the device name to match for the user's group membership; if left blank, all users with the matching user key will be disabled

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
• device (optional) - the device name to match for the user's group membership; if left blank, all users with the matching user key will be re-enabled

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 POST 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.