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.
229 lines
9.9 KiB
YAML
229 lines
9.9 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.
|
|
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Push Notification API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/push/v1
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
paths:
|
|
"/notify":
|
|
post:
|
|
summary: Notify a push gateway about an event.
|
|
description: |-
|
|
This endpoint is invoked by HTTP pushers to notify a push gateway about
|
|
an event or update the number of unread notifications a user has.
|
|
In the former case it will contain selected information about the event.
|
|
In either case it may contain numeric counts of the number of unread
|
|
events of different types the user has. The counts may be sent along
|
|
with a notification about an event or by themselves.
|
|
|
|
Notifications about a particular event will normally cause the user to be
|
|
alerted in some way. It is therefore necessary to perform duplicate
|
|
suppression for such notifications using the ``event_id`` field to avoid
|
|
retries of this HTTP API causing duplicate alerts. The operation of
|
|
updating counts of unread notifications should be idempotent and
|
|
therefore do not require duplicate suppression.
|
|
|
|
Notifications are sent to the URL configured when the pusher is created.
|
|
This means that the HTTP path may be different depending on the push
|
|
gateway.
|
|
operationId: notify
|
|
parameters:
|
|
- in: body
|
|
name: notification
|
|
description: Information about the push notification.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
example: {
|
|
"notification": {
|
|
"event_id": "$3957tyerfgewrf384",
|
|
"room_id": "!slw48wfj34rtnrf:example.com",
|
|
"type": "m.room.message",
|
|
"sender": "@exampleuser:matrix.org",
|
|
"sender_display_name": "Major Tom",
|
|
"room_name": "Mission Control",
|
|
"room_alias": "#exampleroom:matrix.org",
|
|
"prio": "high",
|
|
"content": {
|
|
"msgtype": "m.text",
|
|
"body": "I'm floating in a most peculiar way."
|
|
},
|
|
"counts": {
|
|
"unread" : 2,
|
|
"missed_calls": 1
|
|
},
|
|
"devices": [
|
|
{
|
|
"app_id": "org.matrix.matrixConsole.ios",
|
|
"pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
|
|
"pushkey_ts": 12345678,
|
|
"data" : {},
|
|
"tweaks": {
|
|
"sound": "bing"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
required: ["notification"]
|
|
properties:
|
|
notification:
|
|
type: object
|
|
title: Notification
|
|
description: Information about the push notification
|
|
required: ["devices"]
|
|
properties:
|
|
event_id:
|
|
type: string
|
|
description: |-
|
|
The Matrix event ID of the event being notified about.
|
|
This is required if the notification is about a
|
|
particular Matrix event. It may be omitted for notifications
|
|
that only contain updated badge counts. This ID can and
|
|
should be used to detect duplicate notification requests.
|
|
room_id:
|
|
type: string
|
|
description: |-
|
|
The ID of the room in which this event occurred.
|
|
Required if the notification relates to a specific
|
|
Matrix event.
|
|
type:
|
|
type: string
|
|
description: |-
|
|
The type of the event as in the event's ``type`` field.
|
|
sender:
|
|
type: string
|
|
description: |-
|
|
The sender of the event as in the corresponding event field.
|
|
sender_display_name:
|
|
type: string
|
|
description: |-
|
|
The current display name of the sender in the room in which
|
|
the event occurred.
|
|
room_name:
|
|
type: string
|
|
description: The name of the room in which the event occurred.
|
|
room_alias:
|
|
type: string
|
|
description: An alias to display for the room in which the event occurred.
|
|
user_is_target:
|
|
type: boolean
|
|
description: |-
|
|
This is true if the user receiving the notification is the
|
|
subject of a member event (i.e. the ``state_key`` of the
|
|
member event is equal to the user's Matrix ID).
|
|
prio:
|
|
type: string
|
|
enum: ["high", "low"]
|
|
description: |-
|
|
The priority of the notification. If omitted, ``high`` is
|
|
assumed. This may be used by push gateways to deliver less
|
|
time-sensitive notifications in a way that will preserve
|
|
battery power on mobile devices.
|
|
content:
|
|
type: object
|
|
title: EventContent
|
|
description: |-
|
|
The ``content`` field from the event, if present. The pusher
|
|
may omit this if the event had no content or for any other
|
|
reason.
|
|
counts:
|
|
type: object
|
|
title: Counts
|
|
description: |-
|
|
This is a dictionary of the current number of unacknowledged
|
|
communications for the recipient user. Counts whose value is
|
|
zero should be omitted.
|
|
properties:
|
|
unread:
|
|
type: integer
|
|
description: |-
|
|
The number of unread messages a user has across all of the
|
|
rooms they are a member of.
|
|
missed_calls:
|
|
type: integer
|
|
description: |-
|
|
The number of unacknowledged missed calls a user has
|
|
across all rooms of which they are a member.
|
|
devices:
|
|
type: array
|
|
title: Devices
|
|
description: |-
|
|
This is an array of devices that the notification should be sent to.
|
|
items:
|
|
type: object
|
|
title: Device
|
|
properties:
|
|
app_id:
|
|
type: string
|
|
description: |-
|
|
The ``app_id`` given when the pusher was created.
|
|
pushkey:
|
|
type: string
|
|
description: The ``pushkey`` given when the pusher was created.
|
|
pushkey_ts:
|
|
type: integer
|
|
description: |-
|
|
The unix timestamp (in seconds) when the
|
|
pushkey was last updated.
|
|
data:
|
|
type: object
|
|
title: PusherData
|
|
description: |-
|
|
A dictionary of additional pusher-specific data. For
|
|
'http' pushers, this is the data dictionary passed in at
|
|
pusher creation minus the ``url`` key.
|
|
tweaks:
|
|
type: object
|
|
title: Tweaks
|
|
description: |-
|
|
A dictionary of customisations made to the way this
|
|
notification is to be presented. These are added by push rules.
|
|
required: ['app_id', 'pushkey']
|
|
responses:
|
|
200:
|
|
description: A list of rejected push keys.
|
|
examples:
|
|
application/json: {
|
|
"rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
|
|
}
|
|
schema:
|
|
type: object # empty json object
|
|
properties:
|
|
rejected:
|
|
type: array
|
|
description: |-
|
|
A list of all pushkeys given in the notification request that
|
|
are not valid. These could have been rejected by an upstream
|
|
gateway because they have expired or have never been valid.
|
|
Homeservers must cease sending notification requests for these
|
|
pushkeys and remove the associated pushers. It may not
|
|
necessarily be the notification in the request that failed:
|
|
it could be that a previous notification to the same pushkey
|
|
failed. May be empty.
|
|
items:
|
|
type: string
|
|
description: A pushkey that has been rejected.
|
|
required: ['rejected']
|