You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/data/api/client-server/pushrules.yaml

853 lines
27 KiB
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 Push Rules API
version: 1.0.0
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.
content:
application/json:
schema:
type: object
required:
- global
properties:
global:
type: object
description: The global ruleset.
title: Ruleset
allOf:
- $ref: definitions/push_ruleset.yaml
examples:
response:
value: {
"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": [],
"conditions": [],
"default": true,
"enabled": false,
"rule_id": ".m.rule.master"
},
{
"actions": [],
"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": [
{
"kind": "room_member_count",
"is": "2"
},
{
"kind": "event_match",
"key": "type",
"pattern": "m.room.message"
}
],
"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
name: scope
required: true
description: "`global` to specify global rules."
example: global
schema:
type: string
- in: path
name: kind
required: true
description: |
The kind of rule
example: content
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
description: |
The identifier for the rule.
example: nocake
schema:
type: string
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.
content:
application/json:
schema:
type: object
description: The push rule.
allOf:
- $ref: definitions/push_rule.yaml
examples:
response:
value: {
"actions": [],
"pattern": "cake*lie",
"rule_id": "nocake",
"enabled": true,
"default": false
}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
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
name: scope
required: true
description: "`global` to specify global rules."
example: global
schema:
type: string
- in: path
name: kind
required: true
description: |
The kind of rule
example: content
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
description: |
The identifier for the rule.
example: nocake
schema:
type: string
responses:
"200":
description: The push rule was deleted.
content:
application/json:
schema:
type: object # empty json object
examples:
response:
value: {}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
tags:
- Push notifications
put:
summary: Add or change a push rule.
description: |-
This endpoint allows the creation and modification of user defined push
rules.
If a rule with the same `rule_id` already exists among rules of the same
kind, it is updated with the new parameters, otherwise a new rule is
created.
If both `after` and `before` are provided, the new or updated rule must
be the next most important rule with respect to the rule identified by
`before`.
If neither `after` nor `before` are provided and the rule is created, it
should be added as the most important user defined rule among rules of
the same kind.
When creating push rules, they MUST be enabled by default.
operationId: setPushRule
security:
- accessToken: []
parameters:
- in: path
name: scope
required: true
description: "`global` to specify global rules."
example: global
schema:
type: string
- in: path
name: kind
required: true
description: |
The kind of rule
example: content
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
description: |
The identifier for the rule. If the string starts with a dot ("."),
the request MUST be rejected as this is reserved for server-default
rules. Slashes ("/") and backslashes ("\\") are also not allowed.
example: nocake
schema:
type: string
- in: query
name: before
required: false
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.
example: someRuleId
schema:
type: string
- in: query
name: after
required: false
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.
example: anotherRuleId
schema:
type: string
requestBody:
content:
application/json:
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", "object"]
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
description: |-
The push rule data. Additional top-level keys may be present depending
on the parameters for the rule `kind`.
required: true
responses:
"200":
description: The push rule was created/updated.
content:
application/json:
schema:
type: object # empty json object
examples:
response:
value: {}
"400":
description: There was a problem configuring this push rule.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"error": "before/after rule not found: someRuleId",
"errcode": "M_UNKNOWN"
}
"404":
description: The push rule does not exist (when updating a push rule).
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
"429":
description: This request was rate-limited.
content:
application/json:
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
name: scope
required: true
description: |-
Either `global` or `device/<profile_tag>` to specify global
rules or device rules for the given `profile_tag`.
example: global
schema:
type: string
- in: path
name: kind
required: true
description: |
The kind of rule
example: content
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
description: |
The identifier for the rule.
example: nocake
schema:
type: string
responses:
"200":
description: Whether the push rule is enabled.
content:
application/json:
schema:
type: object
properties:
enabled:
type: boolean
description: Whether the push rule is enabled or not.
required:
- enabled
examples:
response:
value: {
"enabled": true
}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
tags:
- Push notifications
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
name: scope
required: true
description: "`global` to specify global rules."
example: global
schema:
type: string
- in: path
name: kind
required: true
description: |
The kind of rule
example: content
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
description: |
The identifier for the rule.
example: nocake
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
enabled:
type: boolean
description: Whether the push rule is enabled or not.
required:
- enabled
example: {
"enabled": true
}
description: |
Whether the push rule is enabled or not.
required: true
responses:
"200":
description: The push rule was enabled or disabled.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
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
name: scope
required: true
description: |-
Either `global` or `device/<profile_tag>` to specify global
rules or device rules for the given `profile_tag`.
example: global
schema:
type: string
- in: path
name: kind
required: true
description: |
The kind of rule
example: content
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
description: |
The identifier for the rule.
example: nocake
schema:
type: string
responses:
"200":
description: The actions for this push rule.
content:
application/json:
schema:
type: object
properties:
actions:
type: array
description: The action(s) to perform for this rule.
items:
type: ["string", "object"]
required:
- actions
examples:
response:
value: {
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "bing"
}
]
}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
tags:
- Push notifications
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
name: scope
required: true
description: "`global` to specify global rules."
example: global
schema:
type: string
- in: path
name: kind
required: true
description: |
The kind of rule
example: room
schema:
type: string
enum:
- override
- underride
- sender
- room
- content
- in: path
name: ruleId
required: true
description: |
The identifier for the rule.
example: "#spam:example.com"
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
actions:
type: array
description: The action(s) to perform for this rule.
items:
type: ["string", "object"]
required:
- actions
example: {
"actions": [
"notify",
{
"set_tweak": "highlight"
}
]
}
description: |
The action(s) to perform when the conditions for this rule are met.
required: true
responses:
"200":
description: The actions for the push rule were set.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"404":
description: The push rule does not exist.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The push rule was not found."
}
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:
$ref: definitions/security.yaml