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

8.7 KiB
Raw Blame History

title description menu
push Subscribe to and receive push notifications when a server-side notification is received, via the Web Push API
docs
weight parent
10 methods-notifications

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’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, or more practically, see:

{{< 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 >}}

{
  "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 >}}

{
  "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 >}}

{
  "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 >}}

{
  "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 >}}

{
  "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 >}}

{}

{{< endapi-method-response-example >}} {{< endapi-method-response >}} {{< endapi-method-spec >}} {{< endapi-method >}}