6c66bfc755
As a side effect, I got rid of all of the horrible symlinks and just put in all of the proper relative paths. Because the horrible symlinks were horrible.
192 lines
7.8 KiB
YAML
192 lines
7.8 KiB
YAML
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.
|
|
*NB: 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.*
|
|
parameters:
|
|
- in: body
|
|
name: notification
|
|
description: Information about the push notification.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
example: |-
|
|
{
|
|
"notification": {
|
|
"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", "counts", "devices"]
|
|
properties:
|
|
notification:
|
|
type: object
|
|
description: Information about the push notification
|
|
required: ["id", "room_id", "type", "sender"]
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: |-
|
|
An identifier for this notification that may be used to
|
|
detect duplicate notification requests. This is not
|
|
necessarily the ID of the event that triggered the
|
|
notification.
|
|
room_id:
|
|
type: string
|
|
description: The ID of the room in which this event occurred.
|
|
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. If the
|
|
event had no content field, this field is omitted.
|
|
counts:
|
|
type: object
|
|
description: |-
|
|
This is a dictionary of the current number of unacknowledged
|
|
communications for the recipient user. Counts whose value is
|
|
zero are 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
|
|
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.
|
|
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.
|
|
items:
|
|
type: string
|
|
description: A pushkey
|
|
|