matrix-spec/data/api/client-server/pusher.yaml

# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
openapi: 3.1.0
info:
  title: Matrix Client-Server Push API
  version: 1.0.0
paths:
  /pushers:
    get:
      summary: Gets the current pushers for the authenticated user
      description: Gets all currently active pushers for the authenticated user.
      operationId: getPushers
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      responses:
        "200":
          description: The pushers for this user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pushers:
                    type: array
                    title: Pushers
                    description: An array containing the current pushers for the user
                    items:
                      type: object
                      title: Pusher
                      properties:
                        pushkey:
                          type: string
                          description: |-
                            This is a unique identifier for this pusher. See `/set` for
                            more detail.
                            Max length, 512 bytes.
                        kind:
                          type: string
                          description: |-
                            The kind of pusher. `"http"` is a pusher that
                            sends HTTP pokes.
                        app_id:
                          type: string
                          description: |-
                            This is a reverse-DNS style identifier for the application.
                            Max length, 64 chars.
                        app_display_name:
                          type: string
                          description: |-
                            A string that will allow the user to identify what application
                            owns this pusher.
                        device_display_name:
                          type: string
                          description: |-
                            A string that will allow the user to identify what device owns
                            this pusher.
                        profile_tag:
                          type: string
                          description: |-
                            This string determines which set of device specific rules this
                            pusher executes.
                        lang:
                          type: string
                          description: |-
                            The preferred language for receiving notifications (e.g. 'en'
                            or 'en-US')
                        data:
                          type: object
                          description: |-
                            A dictionary of information for the pusher implementation
                            itself.
                          title: PusherData
                          properties:
                            url:
                              type: string
                              format: uri
                              description: |-
                                Required if `kind` is `http`. The URL to use to send
                                notifications to.
                            format:
                              type: string
                              description: |-
                                The format to use when sending notifications to the Push
                                Gateway.
                      required:
                        - pushkey
                        - app_id
                        - kind
                        - app_display_name
                        - device_display_name
                        - lang
                        - data
              examples:
                response:
                  value: {
                    "pushers": [
                      {
                        "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
                        "kind": "http",
                        "app_id": "face.mcapp.appy.prod",
                        "app_display_name": "Appy McAppface",
                        "device_display_name": "Alice's Phone",
                        "profile_tag": "xyz",
                        "lang": "en-US",
                        "data": {
                          "url": "https://example.com/_matrix/push/v1/notify"
                        }
                      }
                    ]
                  }
      tags:
        - Push notifications
  /pushers/set:
    post:
      summary: Modify a pusher for this user on the homeserver.
      description: |-
        This endpoint allows the creation, modification and deletion of [pushers](/client-server-api/#push-notifications)
        for this user ID. The behaviour of this endpoint varies depending on the
        values in the JSON body.

        If `kind` is not `null`, the pusher with this `app_id` and `pushkey`
        for this user is updated, or it is created if it doesn't exist. If
        `kind` is `null`, the pusher with this `app_id` and `pushkey` for this
        user is deleted.
      operationId: postPusher
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {
                "lang": "en",
                "kind": "http",
                "app_display_name": "Mat Rix",
                "device_display_name": "iPhone 9",
                "profile_tag": "xxyyzz",
                "app_id": "com.example.app.ios",
                "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
                "data": {
                  "url": "https://push-gateway.location.here/_matrix/push/v1/notify",
                  "format": "event_id_only"
                },
                "append": false
              }
              properties:
                pushkey:
                  type: string
                  description: |-
                    This is a unique identifier for this pusher. The value you
                    should use for this is the routing or destination address
                    information for the notification, for example, the APNS token
                    for APNS or the Registration ID for GCM. If your notification
                    client has no such concept, use any unique identifier.
                    Max length, 512 bytes.

                    If the `kind` is `"email"`, this is the email address to
                    send notifications to.
                kind:
                  description: |-
                    The kind of pusher to configure. `"http"` makes a pusher that
                    sends HTTP pokes. `"email"` makes a pusher that emails the
                    user with unread notifications. `null` deletes the pusher.
                  type: ["string", "null"]
                app_id:
                  type: string
                  description: |-
                    This is a reverse-DNS style identifier for the application.
                    It is recommended that this end with the platform, such that
                    different platform versions get different app identifiers.
                    Max length, 64 chars.

                    If the `kind` is `"email"`, this is `"m.email"`.
                app_display_name:
                  type: string
                  description: |-
                    Required if `kind` is not `null`. A string that will allow the
                    user to identify what application owns this pusher.
                device_display_name:
                  type: string
                  description: |-
                    Required if `kind` is not `null`. A string that will allow the
                    user to identify what device owns this pusher.
                profile_tag:
                  type: string
                  description: |-
                    This string determines which set of device specific rules this
                    pusher executes.
                lang:
                  type: string
                  description: |-
                    Required if `kind` is not `null`. The preferred language for
                    receiving notifications (e.g. 'en' or 'en-US').
                data:
                  type: object
                  description: |-
                    Required if `kind` is not `null`. A dictionary of information
                    for the pusher implementation itself. If `kind` is `http`,
                    this should contain `url` which is the URL to use to send
                    notifications to.
                  title: PusherData
                  properties:
                    url:
                      type: string
                      format: uri
                      description: |-
                        Required if `kind` is `http`. The URL to use to send
                        notifications to. MUST be an HTTPS URL with a path of
                        `/_matrix/push/v1/notify`.
                      example: https://push-gateway.location.here/_matrix/push/v1/notify
                    format:
                      type: string
                      description: |-
                        The format to send notifications in to Push Gateways if the
                        `kind` is `http`. The details about what fields the
                        homeserver should send to the push gateway are defined in the
                        [Push Gateway Specification](/push-gateway-api/). Currently the only format
                        available is 'event_id_only'.
                append:
                  type: boolean
                  description: |-
                    If true, the homeserver should add another pusher with the
                    given pushkey and App ID in addition to any others with
                    different user IDs. Otherwise, the homeserver must remove any
                    other pushers with the same App ID and pushkey for different
                    users. The default is `false`.
              required:
                - kind
                - app_id
                - pushkey
        description: The pusher information.
        required: true
      responses:
        "200":
          description: The pusher was set.
          content:
            application/json:
              schema:
                type: object
                description: An empty object.
              examples:
                response:
                  value: {}
        "400":
          description: One or more of the pusher values were invalid.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "error": "Missing parameters: lang, data",
                    "errcode": "M_MISSING_PARAM"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - Push notifications
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3
components:
  securitySchemes:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer