matrix-spec/api/client-server/notifications.yaml

# Copyright 2016 OpenMarket 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 Notifications 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:
  "/notifications":
    get:
      summary: Gets a list of events that the user has been notified about
      description: |-
        This API is used to paginate through the list of events that the
        user has been, or would have been notified about.
      security:
        - accessToken: []
      parameters:
        - in: query
          type: string
          name: from
          description: Pagination token given to retrieve the next set of events.
          required: false
          x-example: "xxxxx"
        - in: query
          type: number
          name: limit
          description: Limit on the number of events to return in this request.
          required: false
          x-example: "20"
        - in: query
          name: only
          type: string
          description: |-
            Allows basic filtering of events returned. Supply ``highlight``
            to return only events where the notification had the highlight
            tweak set.
          required: false
          x-example: "highlight"
      responses:
        200:
          description: A batch of events is being returned
          examples:
            application/json: |-
              {
                "next_token": "abcdef",
                "notifications": [
                  {
                    "actions": [
                      "notify"
                    ],
                    "profile_tag": "hcbvkzxhcvb",
                    "read": true,
                    "room_id": "!abcdefg:example.com",
                    "ts": 1475508881945,
                    "event": {
                      "sender": "@alice:example.com",
                      "type": "m.room.message",
                      "age": 124524,
                      "txn_id": "1234",
                      "content": {
                        "body": "I am a fish",
                        "msgtype": "m.text"
                      },
                      "origin_server_ts": 1417731086797,
                      "event_id": "$74686972643033:example.com"
                    }
                  }
                ]
              }
          schema:
            type: object
            properties:
              next_token:
                type: string
                description: |-
                  The token to supply in the ``from`` param of the next
                  ``/notifications`` request in order to request more
                  events. If this is absent, there are no more results.
              notifications:
                type: array
                items:
                  type: object
                  title: Notification
                  properties:
                    actions:
                      type: array
                      description: |-
                        The action(s) to perform when the conditions for this rule are met.
                        See `Push Rules: API`_.
                      items:
                        type: string
                    event:
                      type: object
                      title: Event
                      description: The Event object for the event that triggered the notification.
                      allOf:
                        - "$ref": "definitions/event.yaml"
                    profile_tag:
                      type: string
                      description: The profile tag of the rule that matched this event.
                    read:
                      type: boolean
                      description: |-
                        Indicates whether the user has sent a read receipt indicating
                        that they have read this message.
                    room_id:
                      type: string
                      description: The ID of the room in which the event was posted.
                    ts:
                      type: integer
                      description: |-
                        The unix timestamp at which the event notification was sent,
                        in milliseconds.
                description: The list of events that triggered notifications.
      tags:
        - Push notifications