matrix-spec/data/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.
openapi: 3.1.0
info:
  title: Matrix Client-Server Notifications API
  version: 1.0.0
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.
      operationId: getNotifications
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: query
          name: from
          description: |-
            Pagination token to continue from. This should be the `next_token`
            returned from an earlier call to this endpoint.
          required: false
          example: xxxxx
          schema:
            type: string
        - in: query
          name: limit
          description: Limit on the number of events to return in this request.
          required: false
          example: 20
          schema:
            type: integer
        - in: query
          name: only
          description: |-
            Allows basic filtering of events returned. Supply `highlight`
            to return only events where the notification had the highlight
            tweak set.
          required: false
          example: highlight
          schema:
            type: string
      responses:
        "200":
          description: A batch of events is being returned
          content:
            application/json:
              schema:
                type: object
                required:
                  - notifications
                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
                      required:
                        - actions
                        - event
                        - read
                        - room_id
                        - ts
                      title: Notification
                      properties:
                        actions:
                          type: array
                          description: |-
                            The action(s) to perform when the conditions for this rule are met.
                            See [Push Rules: API](/client-server-api/#push-rules-api).
                          items:
                            type: ["object", "string"]
                        event:
                          title: Event
                          description: The Event object for the event that triggered the notification.
                          allOf:
                            - $ref: definitions/client_event_without_room_id.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
                          format: int64
                          description: |-
                            The unix timestamp at which the event notification was sent,
                            in milliseconds.
                    description: The list of events that triggered notifications.
              examples:
                response:
                  value: {
                    "next_token": "abcdef",
                    "notifications": [
                      {
                        "actions": [
                          "notify"
                        ],
                        "profile_tag": "hcbvkzxhcvb",
                        "read": true,
                        "room_id": "!abcdefg:example.com",
                        "ts": 1475508881945,
                        "event": {
                          "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
                        }
                      }
                    ]
                  }
      tags:
        - Push notifications
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3
components:
  securitySchemes:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer