matrix-spec-proposals/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.
swagger: '2.0'
info:
  title: "Matrix Client-Server Push API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
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:
        - accessToken: []
      responses:
        200:
          description: The pushers for this user.
          examples:
            application/json: {
              "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"
                  }
                }
              ]
            }
          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
                          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
      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`_
        for this user ID. The behaviour of this endpoint varies depending on the
        values in the JSON body.
      operationId: postPusher
      security:
        - accessToken: []
      parameters:
        - in: body
          name: pusher
          description: The pusher information.
          required: true
          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:
                type: string
                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.
              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: |-
                  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. If ``kind`` is ``http``, this should contain ``url``
                  which is the URL to use to send notifications to.
                title: PusherData
                properties:
                  url:
                    type: string
                    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`_. 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', 'app_display_name',
                'device_display_name', 'pushkey', 'lang', 'data']
      responses:
        200:
          description: The pusher was set.
          examples:
            application/json: {}
          schema:
            type: object
            description: An empty object.
        400:
          description: One or more of the pusher values were invalid.
          examples:
            application/json: {
              "error": "Missing parameters: lang, data",
              "errcode": "M_MISSING_PARAM"
            }
          schema:
            "$ref": "definitions/errors/error.yaml"
        429:
          description: This request was rate-limited.
          schema:
            "$ref": "definitions/errors/rate_limited.yaml"
      tags:
        - Push notifications