matrix-spec/api/push-gateway/push_notifier.yaml

swagger: '2.0'
info:
  title: "Matrix Push Notification API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/push/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
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.
        *NB: 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.*
      parameters:
        - in: body
          name: notification
          description: Information about the push notification.
          required: true
          schema:
            type: object
            example: |-
              {
                "notification": {
                  "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", "counts", "devices"]
            properties:
              notification:
                type: object
                description: Information about the push notification
                required: ["id", "room_id", "type", "sender"]
                properties:
                  id:
                    type: string
                    description: |-
                      An identifier for this notification that may be used to
                      detect duplicate notification requests. This is not
                      necessarily the ID of the event that triggered the
                      notification.
                  room_id:
                    type: string
                    description: The ID of the room in which this event occurred.
                  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. If the
                      event had no content field, this field is omitted.
              counts:
                type: object
                description: |-
                  This is a dictionary of the current number of unacknowledged
                  communications for the recipient user. Counts whose value is
                  zero are 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
                  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
                      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.
      responses:
        200:
          description: A list of rejected push keys.
          examples:
            application/json: |-
              {
                "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
              }
          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.
                items:
                  type: string
                  description: A pushkey