push API methods
Subscribe to and receive push notifications when a server-side notification is received, via the Web Push API
About the Web Push API
Mastodon natively supports the Web Push API. You can utilize the same mechanisms for your native app. It requires running a proxy server that connects to Android鈥檚 and Apple鈥檚 proprietary notification gateways. However, the proxy server does not have access to the contents of the notifications. For a reference, see Mozilla鈥檚 web push server, or more practically, see:
Subscribe to push notifications
POST /api/v1/push/subscription HTTP/1.1
Add a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted.
Returns: WebPushSubscription
OAuth: User token + push
Version history:
2.4.0 - added
3.3.0 - added data[alerts][status]
3.4.0 - added data[policy]
3.5.0 - added data[alerts][update]
and data[alerts][admin.sign_up]
4.0.0 - added data[alerts][admin.report]
Request
Headers
- Authorization
- required Provide this header with
Bearer <user token>
to gain authorized access to this API method.
Form data parameters
- subscription[endpoint]
- required String. The endpoint URL that is called when a notification event occurs.
- subscription[keys][p256dh]
- required String. User agent public key. Base64 encoded string of a public key from a ECDH keypair using the
prime256v1
curve. - subscription[keys][auth]
- required String. Auth secret. Base64 encoded string of 16 bytes of random data.
- data[alerts][mention]
- Boolean. Receive mention notifications? Defaults to false.
- data[alerts][status]
- Boolean. Receive new subscribed account notifications? Defaults to false.
- data[alerts][reblog]
- Boolean. Receive reblog notifications? Defaults to false.
- data[alerts][follow]
- Boolean. Receive follow notifications? Defaults to false.
- data[alerts][follow_request]
- Boolean. Receive follow request notifications? Defaults to false.
- data[alerts][favourite]
- Boolean. Receive favourite notifications? Defaults to false.
- data[alerts][poll]
- Boolean. Receive poll notifications? Defaults to false.
- data[alerts][update]
- Boolean. Receive status edited notifications? Defaults to false.
- data[alerts][admin.sign_up]
- Boolean. Receive new user signup notifications? Defaults to false. Must have a role with the appropriate permissions.
- data[alerts][admin.report]
- Boolean. Receive new report notifications? Defaults to false. Must have a role with the appropriate permissions.
- data[policy]
- String. Specify whether to receive push notifications from
all
,followed
,follower
, ornone
users.
Response
200: OK
A new PushSubscription has been generated, which will send the requested alerts to your endpoint.
{
"id": 328183,
"endpoint": "https://yourdomain.example/listener",
"alerts": {
"follow": true,
"favourite": true,
"reblog": true,
"mention": true,
"poll": true
},
"server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}
401: Unauthorized
Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}
Get current subscription
GET /api/v1/push/subscription HTTP/1.1
View the PushSubscription currently associated with this access token.
Returns: WebPushSubscription
OAuth: User token + push
Version history:
2.4.0 - added
Request
Headers
- Authorization
- required Provide this header with
Bearer <user token>
to gain authorized access to this API method.
Response
200: OK
{
"id": 328183,
"endpoint": "https://yourdomain.example/listener",
"alerts": {
"follow": true,
"favourite": true,
"reblog": true,
"mention": true,
"poll": true
},
"server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}
401: Unauthorized
Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}
404: Not found
A PushSubscription does not exist for this token.
{
"error": "Record not found"
}
Change types of notifications
PUT /api/v1/push/subscription HTTP/1.1
Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.
Returns: WebPushSubscription
OAuth: User token + push
Version history:
2.4.0 - added
3.3.0 - added data[alerts][status]
3.4.0 - added policy
3.5.0 - added data[alerts][update]
and data[alerts][admin.sign_up]
4.0.0 - added data[alerts][admin.report]
Request
Headers
- Authorization
- required Provide this header with
Bearer <user token>
to gain authorized access to this API method.
Form data parameters
- data[alerts][mention]
- Boolean. Receive mention notifications? Defaults to false.
- data[alerts][status]
- Boolean. Receive new subscribed account notifications? Defaults to false.
- data[alerts][reblog]
- Boolean. Receive reblog notifications? Defaults to false.
- data[alerts][follow]
- Boolean. Receive follow notifications? Defaults to false.
- data[alerts][follow_request]
- Boolean. Receive follow request notifications? Defaults to false.
- data[alerts][favourite]
- Boolean. Receive favourite notifications? Defaults to false.
- data[alerts][poll]
- Boolean. Receive poll notifications? Defaults to false.
- data[alerts][update]
- Boolean. Receive status edited notifications? Defaults to false.
- data[alerts][admin.sign_up]
- Boolean. Receive new user signup notifications? Defaults to false. Must have a role with the appropriate permissions.
- data[alerts][admin.report]
- Boolean. Receive new report notifications? Defaults to false. Must have a role with the appropriate permissions.
- policy
- String. Specify whether to receive push notifications from
all
,followed
,follower
, ornone
users.
Response
200: OK
Updating a PushSubscription to only receive mention alerts
{
"id": 328183,
"endpoint": "https://yourdomain.example/listener",
"alerts": {
"follow": false,
"favourite": false,
"reblog": false,
"mention": true,
"poll": false
},
"server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}
401: Unauthorized
Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}
404: Not found
No existing PushSubscription for this token
{
"error": "Record not found"
}
Remove current subscription
DELETE /api/v1/push/subscription HTTP/1.1
Removes the current Web Push API subscription.
Returns: none
OAuth: User token + push
Version history:
2.4.0 - added
Request
Headers
- Authorization
- required Provide this header with
Bearer <user token>
to gain authorized access to this API method.
Response
200: OK
PushSubscription successfully deleted or did not exist previously
{}
401: Unauthorized
Invalid or missing Authorization header.
{
"error": "The access token is invalid"
}
See also
app/controllers/api/v1/push/subscriptions_controller.rbLast updated February 6, 2023 路 Improve this page