matrix-spec/data/api/push-gateway/push_notifier.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 Push Notification API
  version: 1.0.0
paths:
  /notify:
    post:
      summary: Notify a push gateway about an event.
      description: |-
        This endpoint is invoked by HTTP pushers to notify a push gateway about
        an event or update the number of unread notifications a user has.
        In the former case it will contain selected information about the event.
        In either case it may contain numeric counts of the number of unread
        events of different types the user has. The counts may be sent along
        with a notification about an event or by themselves.

        Notifications about a particular event will normally cause the user to be
        alerted in some way. It is therefore necessary to perform duplicate
        suppression for such notifications using the `event_id` field to avoid
        retries of this HTTP API causing duplicate alerts. The operation of
        updating counts of unread notifications should be idempotent and
        therefore do not require duplicate suppression.

        Notifications are sent to the URL configured when the pusher is created.
        This means that the HTTP path may be different depending on the push
        gateway.
      operationId: notify
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {
                "notification": {
                  "event_id": "$3957tyerfgewrf384",
                  "room_id": "!slw48wfj34rtnrf:example.com",
                  "type": "m.room.message",
                  "sender": "@exampleuser:matrix.org",
                  "sender_display_name": "Major Tom",
                  "room_name": "Mission Control",
                  "room_alias": "#exampleroom:matrix.org",
                  "prio": "high",
                  "content": {
                    "msgtype": "m.text",
                    "body": "I'm floating in a most peculiar way."
                  },
                  "counts": {
                    "unread": 2,
                    "missed_calls": 1
                  },
                  "devices": [
                    {
                      "app_id": "org.matrix.matrixConsole.ios",
                      "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
                      "pushkey_ts": 12345678,
                      "data": {},
                      "tweaks": {
                        "sound": "bing"
                      }
                    }
                  ]
                }
              }
              required:
                - notification
              properties:
                notification:
                  type: object
                  title: Notification
                  description: Information about the push notification
                  required:
                    - devices
                  properties:
                    event_id:
                      type: string
                      description: |-
                        The Matrix event ID of the event being notified about.
                        This is required if the notification is about a
                        particular Matrix event. It may be omitted for notifications
                        that only contain updated badge counts. This ID can and
                        should be used to detect duplicate notification requests.
                    room_id:
                      type: string
                      description: |-
                        The ID of the room in which this event occurred.
                        Required if the notification relates to a specific
                        Matrix event.
                    type:
                      type: string
                      description: The type of the event as in the event's `type` field.
                    sender:
                      type: string
                      description: The sender of the event as in the corresponding event field.
                    sender_display_name:
                      type: string
                      description: |-
                        The current display name of the sender in the room in which
                        the event occurred.
                    room_name:
                      type: string
                      description: The name of the room in which the event occurred.
                    room_alias:
                      type: string
                      description: An alias to display for the room in which the event occurred.
                    user_is_target:
                      type: boolean
                      description: |-
                        This is true if the user receiving the notification is the
                        subject of a member event (i.e. the `state_key` of the
                        member event is equal to the user's Matrix ID).
                    prio:
                      type: string
                      enum:
                        - high
                        - low
                      description: |-
                        The priority of the notification. If omitted, `high` is
                        assumed. This may be used by push gateways to deliver less
                        time-sensitive notifications in a way that will preserve
                        battery power on mobile devices.
                    content:
                      type: object
                      title: EventContent
                      description: |-
                        The `content` field from the event, if present. The pusher
                        may omit this if the event had no content or for any other
                        reason.
                    counts:
                      type: object
                      title: Counts
                      description: |-
                        This is a dictionary of the current number of unacknowledged
                        communications for the recipient user. Counts whose value is
                        zero should be omitted.
                      properties:
                        unread:
                          type: integer
                          description: |-
                            The number of unread messages a user has across all of the
                            rooms they are a member of.
                        missed_calls:
                          type: integer
                          description: |-
                            The number of unacknowledged missed calls a user has
                            across all rooms of which they are a member.
                    devices:
                      type: array
                      title: Devices
                      description: This is an array of devices that the notification should be sent
                        to.
                      items:
                        type: object
                        title: Device
                        properties:
                          app_id:
                            type: string
                            description: The `app_id` given when the pusher was created.
                          pushkey:
                            type: string
                            description: The `pushkey` given when the pusher was created.
                          pushkey_ts:
                            type: integer
                            format: int64
                            description: |-
                              The unix timestamp (in seconds) when the
                              pushkey was last updated.
                          data:
                            type: object
                            title: PusherData
                            description: |-
                              A dictionary of additional pusher-specific data. For
                              'http' pushers, this is the data dictionary passed in at
                              pusher creation minus the `url` key.
                          tweaks:
                            type: object
                            title: Tweaks
                            description: |-
                              A dictionary of customisations made to the way this
                              notification is to be presented. These are added by push rules.
                        required:
                          - app_id
                          - pushkey
        description: Information about the push notification.
        required: true
      responses:
        "200":
          description: A list of rejected push keys.
          content:
            application/json:
              schema:
                type: object  # empty json object
                properties:
                  rejected:
                    type: array
                    description: |-
                      A list of all pushkeys given in the notification request that
                      are not valid. These could have been rejected by an upstream
                      gateway because they have expired or have never been valid.
                      Homeservers must cease sending notification requests for these
                      pushkeys and remove the associated pushers. It may not
                      necessarily be the notification in the request that failed:
                      it could be that a previous notification to the same pushkey
                      failed. May be empty.
                    items:
                      type: string
                      description: A pushkey that has been rejected.
                required:
                  - rejected
              examples:
                response:
                  value: {
                    "rejected": [
                      "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/"
                    ]
                  }
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/push/v1