matrix-spec-proposals/api/client-server/pushrules.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 Push Rules 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:
  "/pushrules/":
    get:
      summary: Retrieve all push rulesets.
      description: |-
        Retrieve all push rulesets for this user. Clients can "drill-down" on
        the rulesets by suffixing a ``scope`` to this path e.g.
        ``/pushrules/global/``. This will return a subset of this data under the
        specified key e.g. the ``global`` key.
      operationId: getPushRules
      security:
        - accessToken: []
      responses:
        200:
          description: All the push rulesets for this user.
          schema:
            type: object
            required: ["global"]
            properties:
              global:
                type: object
                description: The global ruleset.
                title: Ruleset
                allOf: [
                  "$ref": "definitions/push_ruleset.yaml"
                ]
          examples:
            application/json: {
                "global": {
                    "content": [
                        {
                            "actions": [
                                "notify",
                                {
                                    "set_tweak": "sound",
                                    "value": "default"
                                },
                                {
                                    "set_tweak": "highlight"
                                }
                            ],
                            "default": true,
                            "enabled": true,
                            "pattern": "alice",
                            "rule_id": ".m.rule.contains_user_name"
                        }
                    ],
                    "override": [
                        {
                            "actions": [
                                "dont_notify"
                            ],
                            "conditions": [],
                            "default": true,
                            "enabled": false,
                            "rule_id": ".m.rule.master"
                        },
                        {
                            "actions": [
                                "dont_notify"
                            ],
                            "conditions": [
                                {
                                    "key": "content.msgtype",
                                    "kind": "event_match",
                                    "pattern": "m.notice"
                                }
                            ],
                            "default": true,
                            "enabled": true,
                            "rule_id": ".m.rule.suppress_notices"
                        }
                    ],
                    "room": [],
                    "sender": [],
                    "underride": [
                        {
                            "actions": [
                                "notify",
                                {
                                    "set_tweak": "sound",
                                    "value": "ring"
                                },
                                {
                                    "set_tweak": "highlight",
                                    "value": false
                                }
                            ],
                            "conditions": [
                                {
                                    "key": "type",
                                    "kind": "event_match",
                                    "pattern": "m.call.invite"
                                }
                            ],
                            "default": true,
                            "enabled": true,
                            "rule_id": ".m.rule.call"
                        },
                        {
                            "actions": [
                                "notify",
                                {
                                    "set_tweak": "sound",
                                    "value": "default"
                                },
                                {
                                    "set_tweak": "highlight"
                                }
                            ],
                            "conditions": [
                                {
                                    "kind": "contains_display_name"
                                }
                            ],
                            "default": true,
                            "enabled": true,
                            "rule_id": ".m.rule.contains_display_name"
                        },
                        {
                            "actions": [
                                "notify",
                                {
                                    "set_tweak": "sound",
                                    "value": "default"
                                },
                                {
                                    "set_tweak": "highlight",
                                    "value": false
                                }
                            ],
                            "conditions": [
                                {
                                    "is": "2",
                                    "kind": "room_member_count"
                                }
                            ],
                            "default": true,
                            "enabled": true,
                            "rule_id": ".m.rule.room_one_to_one"
                        },
                        {
                            "actions": [
                                "notify",
                                {
                                    "set_tweak": "sound",
                                    "value": "default"
                                },
                                {
                                    "set_tweak": "highlight",
                                    "value": false
                                }
                            ],
                            "conditions": [
                                {
                                    "key": "type",
                                    "kind": "event_match",
                                    "pattern": "m.room.member"
                                },
                                {
                                    "key": "content.membership",
                                    "kind": "event_match",
                                    "pattern": "invite"
                                },
                                {
                                    "key": "state_key",
                                    "kind": "event_match",
                                    "pattern": "@alice:example.com"
                                }
                            ],
                            "default": true,
                            "enabled": true,
                            "rule_id": ".m.rule.invite_for_me"
                        },
                        {
                            "actions": [
                                "notify",
                                {
                                    "set_tweak": "highlight",
                                    "value": false
                                }
                            ],
                            "conditions": [
                                {
                                    "key": "type",
                                    "kind": "event_match",
                                    "pattern": "m.room.member"
                                }
                            ],
                            "default": true,
                            "enabled": true,
                            "rule_id": ".m.rule.member_event"
                        },
                        {
                            "actions": [
                                "notify",
                                {
                                    "set_tweak": "highlight",
                                    "value": false
                                }
                            ],
                            "conditions": [
                                {
                                    "key": "type",
                                    "kind": "event_match",
                                    "pattern": "m.room.message"
                                }
                            ],
                            "default": true,
                            "enabled": true,
                            "rule_id": ".m.rule.message"
                        }
                    ]
                }
              }
      tags:
        - Push notifications
  "/pushrules/{scope}/{kind}/{ruleId}":
    get:
      summary: Retrieve a push rule.
      description: |-
        Retrieve a single specified push rule.
      operationId: getPushRule
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: scope
          required: true
          x-example: "global"
          description: |-
            ``global`` to specify global rules.
        - in: path
          type: string
          name: kind
          required: true
          x-example: content
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
        - in: path
          type: string
          name: ruleId
          required: true
          x-example: "nocake"
          description: |
            The identifier for the rule.
      responses:
        200:
          description: |-
            The specific push rule. This will also include keys specific to the
            rule itself such as the rule's ``actions`` and ``conditions`` if set.
          examples:
            application/json: {
                "actions": [
                    "dont_notify"
                ],
                "pattern": "cake*lie",
                "rule_id": "nocake",
                "enabled": true,
                "default": false
              }
          schema:
            type: object
            description: The push rule.
            allOf: [
              "$ref": "definitions/push_rule.yaml"
            ]
      tags:
        - Push notifications
    delete:
      summary: Delete a push rule.
      description: |-
        This endpoint removes the push rule defined in the path.
      operationId: deletePushRule
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: scope
          required: true
          x-example: "global"
          description: |-
            ``global`` to specify global rules.
        - in: path
          type: string
          name: kind
          required: true
          x-example: content
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
        - in: path
          type: string
          name: ruleId
          required: true
          x-example: "nocake"
          description: |
            The identifier for the rule.
      responses:
        200:
          description: The push rule was deleted.
          examples:
            application/json: {
              }
          schema:
            type: object  # empty json object
      tags:
        - Push notifications
    put:
      summary: Add or change a push rule.
      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.

        When creating push rules, they MUST be enabled by default.
      operationId: setPushRule
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: scope
          required: true
          x-example: "global"
          description: |-
            ``global`` to specify global rules.
        - in: path
          type: string
          name: kind
          required: true
          x-example: content
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
        - in: path
          type: string
          name: ruleId
          required: true
          x-example: "nocake"
          description: |
            The identifier for the rule.
        - in: query
          type: string
          name: before
          required: false
          x-example: someRuleId
          description: |-
            Use 'before' with a ``rule_id`` as its value to make the new rule the
            next-most important rule with respect to the given user defined rule.
            It is not possible to add a rule relative to a predefined server rule.
        - in: query
          type: string
          name: after
          required: false
          x-example: anotherRuleId
          description: |-
            This makes the new rule the next-less important rule relative to the
            given user defined rule. It is not possible to add a rule relative
            to a predefined server rule.
        - in: body
          name: pushrule
          description: |-
            The push rule data. Additional top-level keys may be present depending
            on the parameters for the rule ``kind``.
          required: true
          schema:
            type: object
            example: {
                "pattern": "cake*lie",
                "actions": ["notify"]
              }
            properties:
              actions:
                type: array
                description: |-
                  The action(s) to perform when the conditions for this rule are met.
                items:
                  type: string
                  enum: ["notify", "dont_notify", "coalesce", "set_tweak"]
                  # TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/
              conditions:
                type: array
                description: |-
                  The conditions that must hold true for an event in order for a
                  rule to be applied to an event. A rule with no conditions
                  always matches. Only applicable to ``underride`` and ``override`` rules.
                items:
                  type: object
                  allOf: [ "$ref": "definitions/push_condition.yaml" ]
              pattern:
                type: string
                description: |-
                  Only applicable to ``content`` rules. The glob-style pattern to match against.
            required: ["actions"]
      responses:
        200:
          description: The push rule was created/updated.
          examples:
            application/json: {
              }
          schema:
            type: object  # empty json object
        400:
          description: There was a problem configuring this push rule.
          examples:
            application/json: {
                "error": "before/after rule not found: someRuleId",
                "errcode": "M_UNKNOWN"
              }
          schema:
            "$ref": "definitions/errors/error.yaml"
        429:
          description: This request was rate-limited.
          schema:
            "$ref": "definitions/errors/rate_limited.yaml"
      tags:
        - Push notifications
  "/pushrules/{scope}/{kind}/{ruleId}/enabled":
    get:
      summary: "Get whether a push rule is enabled"
      description:
        This endpoint gets whether the specified push rule is enabled.
      operationId: isPushRuleEnabled
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: scope
          required: true
          x-example: "global"
          description: |-
            Either ``global`` or ``device/<profile_tag>`` to specify global
            rules or device rules for the given ``profile_tag``.
        - in: path
          type: string
          name: kind
          required: true
          x-example: cake
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
        - in: path
          type: string
          name: ruleId
          required: true
          x-example: nocake
          description: |
            The identifier for the rule.
      responses:
        200:
          description: Whether the push rule is enabled.
          examples:
            application/json: {
                "enabled": true
              }
          schema:
            type: object
            properties:
              enabled:
                type: boolean
                description: Whether the push rule is enabled or not.
            required: ["enabled"]
    put:
      summary: "Enable or disable a push rule."
      description: |-
        This endpoint allows clients to enable or disable the specified push rule.
      operationId: setPushRuleEnabled
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: scope
          required: true
          x-example: "global"
          description: |-
            ``global`` to specify global rules.
        - in: path
          type: string
          name: kind
          required: true
          x-example: content
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
        - in: path
          type: string
          name: ruleId
          required: true
          x-example: "nocake"
          description: |
            The identifier for the rule.
        - in: body
          name: body
          description: |
            Whether the push rule is enabled or not.
          required: true
          schema:
            type: object
            properties:
              enabled:
                type: boolean
                description: Whether the push rule is enabled or not.
            required: ["enabled"]
            example: {
                "enabled": true
              }
      responses:
        200:
          description: The push rule was enabled or disabled.
          examples:
            application/json: {
              }
          schema:
            type: object
      tags:
        - Push notifications
  "/pushrules/{scope}/{kind}/{ruleId}/actions":
    get:
      summary: "The actions for a push rule"
      description:
        This endpoint get the actions for the specified push rule.
      operationId: getPushRuleActions
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: scope
          required: true
          x-example: "global"
          description: |-
            Either ``global`` or ``device/<profile_tag>`` to specify global
            rules or device rules for the given ``profile_tag``.
        - in: path
          type: string
          name: kind
          required: true
          x-example: content
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
        - in: path
          type: string
          name: ruleId
          required: true
          x-example: nocake
          description: |
            The identifier for the rule.
      responses:
        200:
          description: The actions for this push rule.
          examples:
            application/json: {
                "actions": ["notify"]
              }
          schema:
            type: object
            properties:
              actions:
                type: array
                description:  The action(s) to perform for this rule.
                items:
                  type: string
            required: ["actions"]
    put:
      summary: "Set the actions for a push rule."
      description: |-
        This endpoint allows clients to change the actions of a push rule.
        This can be used to change the actions of builtin rules.
      operationId: setPushRuleActions
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: scope
          required: true
          x-example: "global"
          description: |-
            ``global`` to specify global rules.
        - in: path
          type: string
          name: kind
          required: true
          x-example: room
          enum: ["override", "underride", "sender", "room", "content"]
          description: |
            The kind of rule
        - in: path
          type: string
          name: ruleId
          required: true
          x-example: "#spam:example.com"
          description: |
            The identifier for the rule.
        - in: body
          name: body
          description: |
            The action(s) to perform when the conditions for this rule are met.
          required: true
          schema:
            type: object
            properties:
              actions:
                type: array
                description: The action(s) to perform for this rule.
                items:
                  type: string
                  enum: ["notify", "dont_notify", "coalesce", "set_tweak"]
                  # TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/
            required: ["actions"]
            example: {
                "actions": ["notify"]
              }
      responses:
        200:
          description: The actions for the push rule were set.
          examples:
            application/json: {
              }
          schema:
            type: object
      tags:
        - Push notifications