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/pusher.yaml

297 lines
12 KiB
YAML

# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector 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 API
version: 1.0.0
paths:
/pushers:
get:
summary: Gets the current pushers for the authenticated user
description: Gets all currently active pushers for the authenticated user.
operationId: getPushers
security:
- accessTokenQuery: []
- accessTokenBearer: []
responses:
"200":
description: The pushers for this user.
content:
application/json:
schema:
type: object
properties:
pushers:
type: array
title: Pushers
description: An array containing the current pushers for the user
items:
type: object
title: Pusher
properties:
pushkey:
type: string
description: |-
This is a unique identifier for this pusher. See `/set` for
more detail.
Max length, 512 bytes.
kind:
type: string
description: |-
The kind of pusher. `"http"` is a pusher that
sends HTTP pokes.
app_id:
type: string
description: |-
This is a reverse-DNS style identifier for the application.
Max length, 64 chars.
app_display_name:
type: string
description: |-
A string that will allow the user to identify what application
owns this pusher.
device_display_name:
type: string
description: |-
A string that will allow the user to identify what device owns
this pusher.
profile_tag:
type: string
description: |-
This string determines which set of device specific rules this
pusher executes.
lang:
type: string
description: |-
The preferred language for receiving notifications (e.g. 'en'
or 'en-US')
data:
type: object
description: |-
A dictionary of information for the pusher implementation
itself.
title: PusherData
properties:
url:
type: string
format: uri
description: |-
Required if `kind` is `http`. The URL to use to send
notifications to.
format:
type: string
description: |-
The format to use when sending notifications to the Push
Gateway.
required:
- pushkey
- app_id
- kind
- app_display_name
- device_display_name
- lang
- data
examples:
response:
value: {
"pushers": [
{
"pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
"kind": "http",
"app_id": "face.mcapp.appy.prod",
"app_display_name": "Appy McAppface",
"device_display_name": "Alice's Phone",
"profile_tag": "xyz",
"lang": "en-US",
"data": {
"url": "https://example.com/_matrix/push/v1/notify"
}
}
]
}
tags:
- Push notifications
/pushers/set:
post:
summary: Modify a pusher for this user on the homeserver.
description: |-
This endpoint allows the creation, modification and deletion of [pushers](/client-server-api/#push-notifications)
for this user ID. The behaviour of this endpoint varies depending on the
values in the JSON body.
If `kind` is not `null`, the pusher with this `app_id` and `pushkey`
for this user is updated, or it is created if it doesn't exist. If
`kind` is `null`, the pusher with this `app_id` and `pushkey` for this
user is deleted.
operationId: postPusher
security:
- accessTokenQuery: []
- accessTokenBearer: []
requestBody:
content:
application/json:
schema:
type: object
example: {
"lang": "en",
"kind": "http",
"app_display_name": "Mat Rix",
"device_display_name": "iPhone 9",
"profile_tag": "xxyyzz",
"app_id": "com.example.app.ios",
"pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
"data": {
"url": "https://push-gateway.location.here/_matrix/push/v1/notify",
"format": "event_id_only"
},
"append": false
}
properties:
pushkey:
type: string
description: |-
This is a unique identifier for this pusher. The value you
should use for this is the routing or destination address
information for the notification, for example, the APNS token
for APNS or the Registration ID for GCM. If your notification
client has no such concept, use any unique identifier.
Max length, 512 bytes.
If the `kind` is `"email"`, this is the email address to
send notifications to.
kind:
description: |-
The kind of pusher to configure. `"http"` makes a pusher that
sends HTTP pokes. `"email"` makes a pusher that emails the
user with unread notifications. `null` deletes the pusher.
type: ["string", "null"]
app_id:
type: string
description: |-
This is a reverse-DNS style identifier for the application.
It is recommended that this end with the platform, such that
different platform versions get different app identifiers.
Max length, 64 chars.
If the `kind` is `"email"`, this is `"m.email"`.
app_display_name:
type: string
description: |-
Required if `kind` is not `null`. A string that will allow the
user to identify what application owns this pusher.
device_display_name:
type: string
description: |-
Required if `kind` is not `null`. A string that will allow the
user to identify what device owns this pusher.
profile_tag:
type: string
description: |-
This string determines which set of device specific rules this
pusher executes.
lang:
type: string
description: |-
Required if `kind` is not `null`. The preferred language for
receiving notifications (e.g. 'en' or 'en-US').
data:
type: object
description: |-
Required if `kind` is not `null`. A dictionary of information
for the pusher implementation itself. If `kind` is `http`,
this should contain `url` which is the URL to use to send
notifications to.
title: PusherData
properties:
url:
type: string
format: uri
description: |-
Required if `kind` is `http`. The URL to use to send
notifications to. MUST be an HTTPS URL with a path of
`/_matrix/push/v1/notify`.
example: https://push-gateway.location.here/_matrix/push/v1/notify
format:
type: string
description: |-
The format to send notifications in to Push Gateways if the
`kind` is `http`. The details about what fields the
homeserver should send to the push gateway are defined in the
[Push Gateway Specification](/push-gateway-api/). Currently the only format
available is 'event_id_only'.
append:
type: boolean
description: |-
If true, the homeserver should add another pusher with the
given pushkey and App ID in addition to any others with
different user IDs. Otherwise, the homeserver must remove any
other pushers with the same App ID and pushkey for different
users. The default is `false`.
required:
- kind
- app_id
- pushkey
description: The pusher information.
required: true
responses:
"200":
description: The pusher was set.
content:
application/json:
schema:
type: object
description: An empty object.
examples:
response:
value: {}
"400":
description: One or more of the pusher values were invalid.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"error": "Missing parameters: lang, data",
"errcode": "M_MISSING_PARAM"
}
"429":
description: This request was rate-limited.
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.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