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

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:
  accessToken:
    type: apiKey
    description: The user_id or application service access_token
    name: access_token
    in: query
paths:
  "/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.
      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",
                "app_id": "com.example.app.ios",
                "profile_tag": "4bea66906d0111e59d70feff819cdc9f",
                "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
                "data": {
                  "url": "https://push-gateway.location.here"
                },
                "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.
              kind:
                type: string
                enum: ["http", null]
                description: |-
                  The kind of pusher to configure. ``"http"`` makes a pusher that
                  sends HTTP pokes. ``null`` deletes the pusher.
              profile_tag:
                type: string
                description: |-
                  This is a string that determines what set of device rules will
                  be matched when evaluating push rules for this pusher. It is
                  an arbitrary string. Multiple devices may use the same
                  ``profile_tag``. It is advised that when an app's data is
                  copied or restored to a different device, this value remain
                  the same. Client apps should offer ways to change the
                  ``profile_tag``, optionally copying rules from the old
                  profile tag. Max length, 32 bytes.
              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.
              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.
              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.
                properties:
                  url:
                    type: string
                    description: |-
                      Required if ``kind`` is ``http``. The URL to use to send
                      notifications to.
              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: ['profile_tag', '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  # empty json 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:
            type: object
        429:
          description: This request was rate-limited.
          schema:
            "$ref": "definitions/error.yaml"