|
|
|
|
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
|
|
|
|
|
|
