zelo72
/
documentation
mirror of https://github.com/mastodon/documentation
1
0
Fork 0
Code Issues 6 Releases Wiki Activity
documentation/content/en/methods/notifications/push.md

258 lines
8.7 KiB
Markdown
Raw Normal View History

Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
---
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)
Add metatext-apns to list of push relay services (#864)
2021-03-18 05:48:58 +01:00
* [metatext-apns](https://github.com/metabolist/metatext-apns)
Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
{{< 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`\
3.3.0rc2 (#834) * add identifier for troubleshooting pages * mention mutes can be temporary now * bell for notifications * convert images to jpg and rename them * suspensions now reversible * unread notifications * suspended: true * mutes expiry * replies_policy, type of notification * notify * featuredTags AP representation * new env vars * accounts merge * maintenance cli * list replies * suspended flag * follower sync * minor formatting * add note about idempotency of follow action * account featured tags, min_id and max_id, plus normalization * follow marcin and nightpool's suggestion * bearcaps * replies_policy update * featuredtags now have a url
2020-12-27 07:03:55 +01:00
**Version history:**\
2.4.0 - added
Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
{{< endapi-method-description >}}
{{< api-method-spec >}}
{{< api-method-request >}}
{{< api-method-headers >}}
{{< api-method-parameter name="Authorization" type="string" required=true >}}
Bearer &lt;user token&gt;
{{< 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`\
3.3.0rc2 (#834) * add identifier for troubleshooting pages * mention mutes can be temporary now * bell for notifications * convert images to jpg and rename them * suspensions now reversible * unread notifications * suspended: true * mutes expiry * replies_policy, type of notification * notify * featuredTags AP representation * new env vars * accounts merge * maintenance cli * list replies * suspended flag * follower sync * minor formatting * add note about idempotency of follow action * account featured tags, min_id and max_id, plus normalization * follow marcin and nightpool's suggestion * bearcaps * replies_policy update * featuredtags now have a url
2020-12-27 07:03:55 +01:00
**Version history:**\
2.4.0 - added
Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
{{< endapi-method-description >}}
{{< api-method-spec >}}
{{< api-method-request >}}
{{< api-method-headers >}}
{{< api-method-parameter name="Authorization" type="string" required=true >}}
Bearer &lt;user token&gt;
{{< 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`\
3.3.0rc2 (#834) * add identifier for troubleshooting pages * mention mutes can be temporary now * bell for notifications * convert images to jpg and rename them * suspensions now reversible * unread notifications * suspended: true * mutes expiry * replies_policy, type of notification * notify * featuredTags AP representation * new env vars * accounts merge * maintenance cli * list replies * suspended flag * follower sync * minor formatting * add note about idempotency of follow action * account featured tags, min_id and max_id, plus normalization * follow marcin and nightpool's suggestion * bearcaps * replies_policy update * featuredtags now have a url
2020-12-27 07:03:55 +01:00
**Version history:**\
2.4.0 - added
Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
{{< endapi-method-description >}}
{{< api-method-spec >}}
{{< api-method-request >}}
{{< api-method-headers >}}
{{< api-method-parameter name="Authorization" type="string" required=true >}}
Bearer &lt;user token&gt;
{{< 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`\
3.3.0rc2 (#834) * add identifier for troubleshooting pages * mention mutes can be temporary now * bell for notifications * convert images to jpg and rename them * suspensions now reversible * unread notifications * suspended: true * mutes expiry * replies_policy, type of notification * notify * featuredTags AP representation * new env vars * accounts merge * maintenance cli * list replies * suspended flag * follower sync * minor formatting * add note about idempotency of follow action * account featured tags, min_id and max_id, plus normalization * follow marcin and nightpool's suggestion * bearcaps * replies_policy update * featuredtags now have a url
2020-12-27 07:03:55 +01:00
**Version history:**\
2.4.0 - added
Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
{{< endapi-method-description >}}
{{< api-method-spec >}}
{{< api-method-request >}}
{{< api-method-headers >}}
{{< api-method-parameter name="Authorization" type="string" required=true >}}
Bearer &lt;user token&gt;
{{< 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 >}}