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.
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.
To fetch a list of users in a group and see its name, submit a GET request to:
https://api.pushover.net/1/groups/YOUR_GROUP_KEY.json?token=YOUR_APP_TOKEN
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}, ]}
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:
https://api.pushover.net/1/groups/YOUR_GROUP_KEY/add_user.json?token=YOUR_APP_TOKEN
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)
To remove an existing Pushover user to your Delivery Group, submit a POST request to:
https://api.pushover.net/1/groups/YOUR_GROUP_KEY/delete_user.json?token=YOUR_APP_TOKEN
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
To temporarily stop sending notifications to a particular user in a group, submit a POST request to:
https://api.pushover.net/1/groups/YOUR_GROUP_KEY/disable_user.json?token=YOUR_APP_TOKEN
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
To resume sending notifications to a particular user in a group, submit a POST request to:
https://api.pushover.net/1/groups/YOUR_GROUP_KEY/enable_user.json?token=YOUR_APP_TOKEN
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
To change the name of a group (reflected in the API and in the group editor on our website), submit a POST request to:
https://api.pushover.net/1/groups/YOUR_GROUP_KEY/rename.json?token=YOUR_APP_TOKEN
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.