258 lines
8.7 KiB
Markdown
258 lines
8.7 KiB
Markdown
---
|
||
title: push
|
||
description: >-
|
||
Subscribe to and receive push notifications when a server-side notification is
|
||
received, via the Web Push API
|
||
menu:
|
||
docs:
|
||
weight: 10
|
||
parent: methods-notifications
|
||
---
|
||
|
||
## Web Push API
|
||
|
||
Mastodon natively supports the [Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). You can utilize the same mechanisms for your native app. It requires running a proxy server that connects to Android’s and Apple’s proprietary notification gateways. However, the proxy server does not have access to the contents of the notifications. For a reference, see [Mozilla’s web push server](https://github.com/mozilla-services/autopush), or more practically, see:
|
||
|
||
* [toot-relay](https://github.com/DagAgren/toot-relay)
|
||
* [PushToFCM](https://github.com/tateisu/PushToFCM)
|
||
* [metatext-apns](https://github.com/metabolist/metatext-apns)
|
||
|
||
{{< api-method method="post" host="https://mastodon.example" path="/api/v1/push/subscription" title="Subscribe to push notifications" >}}
|
||
{{< api-method-description >}}
|
||
|
||
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:** PushSubscription\
|
||
**OAuth:** User token + `push`\
|
||
**Version history:**\
|
||
2.4.0 - added
|
||
|
||
{{< endapi-method-description >}}
|
||
{{< api-method-spec >}}
|
||
{{< api-method-request >}}
|
||
{{< api-method-headers >}}
|
||
{{< api-method-parameter name="Authorization" type="string" required=true >}}
|
||
Bearer <user token>
|
||
{{< endapi-method-parameter >}}
|
||
{{< endapi-method-headers >}}
|
||
{{< api-method-form-data-parameters >}}
|
||
{{< api-method-parameter name="subscription\[endpoint\]" type="string" required=true >}}
|
||
Endpoint URL that is called when a notification event occurs.
|
||
{{< endapi-method-parameter >}}
|
||
{{< api-method-parameter name="subscription\[keys\]\[p256dh\]" type="string" required=true >}}
|
||
User agent public key. Base64 encoded string of public key of ECDH key using `prime256v1` curve.
|
||
{{< endapi-method-parameter >}}
|
||
{{< api-method-parameter name="subscription\[keys\]\[auth\]" type="string" required=true >}}
|
||
Auth secret. Base64 encoded string of 16 bytes of random data.
|
||
{{< endapi-method-parameter >}}
|
||
{{< api-method-parameter name="data\[alerts\]\[follow\]" type="boolean" required=false >}}
|
||
Receive follow notifications?
|
||
{{< endapi-method-parameter >}}
|
||
{{< api-method-parameter name="data\[alerts\]\[favourite\]" type="boolean" required=false >}}
|
||
Receive favourite notifications?
|
||
{{< endapi-method-parameter >}}
|
||
{{< api-method-parameter name="data\[alerts\]\[reblog\]" type="boolean" required=false >}}
|
||
Receive reblog notifications?
|
||
{{< endapi-method-parameter >}}
|
||
{{< api-method-parameter name="data\[alerts\]\[mention\]" type="boolean" required=false >}}
|
||
Receive mention notifications?
|
||
{{< endapi-method-parameter >}}
|
||
{{< api-method-parameter name="data\[alerts\]\[poll\]" type="boolean" required=false >}}
|
||
Receive poll notifications?
|
||
{{< endapi-method-parameter >}}
|
||
{{< endapi-method-form-data-parameters >}}
|
||
{{< endapi-method-request >}}
|
||
{{< api-method-response >}}
|
||
{{< api-method-response-example httpCode=200 >}}
|
||
{{< api-method-response-example-description >}}
|
||
|
||
A new PushSubscription has been generated, which will send the requested alerts to your endpoint.
|
||
{{< endapi-method-response-example-description >}}
|
||
|
||
|
||
```javascript
|
||
{
|
||
"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="
|
||
}
|
||
```
|
||
{{< endapi-method-response-example >}}
|
||
{{< endapi-method-response >}}
|
||
{{< endapi-method-spec >}}
|
||
{{< endapi-method >}}
|
||
{{< api-method method="get" host="https://mastodon.example" path="/api/v1/push/subscription" title="Get current subscription" >}}
|
||
{{< api-method-description >}}
|
||
|
||
View the PushSubscription currently associated with this access token.
|
||
|
||
**Returns:** PushSubscription\
|
||
**OAuth:** User token + `push`\
|
||
**Version history:**\
|
||
2.4.0 - added
|
||
|
||
{{< endapi-method-description >}}
|
||
{{< api-method-spec >}}
|
||
{{< api-method-request >}}
|
||
{{< api-method-headers >}}
|
||
{{< api-method-parameter name="Authorization" type="string" required=true >}}
|
||
Bearer <user token>
|
||
{{< endapi-method-parameter >}}
|
||
{{< endapi-method-headers >}}
|
||
{{< endapi-method-request >}}
|
||
{{< api-method-response >}}
|
||
{{< api-method-response-example httpCode=200 >}}
|
||
{{< api-method-response-example-description >}}
|
||
{{< endapi-method-response-example-description >}}
|
||
|
||
|
||
```javascript
|
||
{
|
||
"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="
|
||
}
|
||
```
|
||
{{< endapi-method-response-example >}}
|
||
{{< api-method-response-example httpCode=404 >}}
|
||
{{< api-method-response-example-description >}}
|
||
|
||
A PushSubscription does not exist for this token.
|
||
{{< endapi-method-response-example-description >}}
|
||
|
||
|
||
```javascript
|
||
{
|
||
"error": "Record not found"
|
||
}
|
||
```
|
||
{{< endapi-method-response-example >}}
|
||
{{< endapi-method-response >}}
|
||
{{< endapi-method-spec >}}
|
||
{{< endapi-method >}}
|
||
{{< api-method method="put" host="https://mastodon.example" path="/api/v1/push/subscription" title="Change types of notifications" >}}
|
||
{{< api-method-description >}}
|
||
|
||
Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.
|
||
|
||
**Returns:** PushSubscription\
|
||
**OAuth:** User token + `push`\
|
||
**Version history:**\
|
||
2.4.0 - added
|
||
|
||
{{< endapi-method-description >}}
|
||
{{< api-method-spec >}}
|
||
{{< api-method-request >}}
|
||
{{< api-method-headers >}}
|
||
{{< api-method-parameter name="Authorization" type="string" required=true >}}
|
||
Bearer <user token>
|
||
{{< endapi-method-parameter >}}
|
||
{{< endapi-method-headers >}}
|
||
{{< api-method-form-data-parameters >}}
|
||
{{< api-method-parameter name="data\[alerts\]\[follow\]" type="boolean" required=false >}}
|
||
Receive follow notifications?
|
||
{{< endapi-method-parameter >}}
|
||
{{< api-method-parameter name="data\[alerts\]\[favourite\]" type="boolean" required=false >}}
|
||
Receive favourite notifications?
|
||
{{< endapi-method-parameter >}}
|
||
{{< api-method-parameter name="data\[alerts\]\[reblog\]" type="boolean" required=false >}}
|
||
Receive reblog notifications?
|
||
{{< endapi-method-parameter >}}
|
||
{{< api-method-parameter name="data\[alerts\]\[mention\]" type="boolean" required=false >}}
|
||
Receive mention notifications?
|
||
{{< endapi-method-parameter >}}
|
||
{{< api-method-parameter name="data\[alerts\]\[poll\]" type="boolean" required=false >}}
|
||
Receive poll notifications?
|
||
{{< endapi-method-parameter >}}
|
||
{{< endapi-method-form-data-parameters >}}
|
||
{{< endapi-method-request >}}
|
||
{{< api-method-response >}}
|
||
{{< api-method-response-example httpCode=200 >}}
|
||
{{< api-method-response-example-description >}}
|
||
|
||
Updating a PushSubscription to only receive mention alerts
|
||
{{< endapi-method-response-example-description >}}
|
||
|
||
|
||
```javascript
|
||
{
|
||
"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="
|
||
}
|
||
```
|
||
{{< endapi-method-response-example >}}
|
||
{{< api-method-response-example httpCode=404 >}}
|
||
{{< api-method-response-example-description >}}
|
||
|
||
No existing PushSubscription for this token
|
||
{{< endapi-method-response-example-description >}}
|
||
|
||
|
||
```javascript
|
||
{
|
||
"error": "Record not found"
|
||
}
|
||
```
|
||
{{< endapi-method-response-example >}}
|
||
{{< endapi-method-response >}}
|
||
{{< endapi-method-spec >}}
|
||
{{< endapi-method >}}
|
||
{{< api-method method="delete" host="https://mastodon.example" path="/api/v1/push/subscription" title="Remove current subscription" >}}
|
||
{{< api-method-description >}}
|
||
|
||
Removes the current Web Push API subscription.
|
||
|
||
**Returns:** none\
|
||
**OAuth:** User token + `push`\
|
||
**Version history:**\
|
||
2.4.0 - added
|
||
|
||
{{< endapi-method-description >}}
|
||
{{< api-method-spec >}}
|
||
{{< api-method-request >}}
|
||
{{< api-method-headers >}}
|
||
{{< api-method-parameter name="Authorization" type="string" required=true >}}
|
||
Bearer <user token>
|
||
{{< endapi-method-parameter >}}
|
||
{{< endapi-method-headers >}}
|
||
{{< endapi-method-request >}}
|
||
{{< api-method-response >}}
|
||
{{< api-method-response-example httpCode=200 >}}
|
||
{{< api-method-response-example-description >}}
|
||
|
||
PushSubscription successfully deleted or did not exist previously
|
||
{{< endapi-method-response-example-description >}}
|
||
|
||
|
||
```javascript
|
||
{}
|
||
```
|
||
{{< endapi-method-response-example >}}
|
||
{{< endapi-method-response >}}
|
||
{{< endapi-method-spec >}}
|
||
{{< endapi-method >}}
|
||
|
||
|