wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #306 from matrix-org/dbkr/add_push_change_event_id

Browse source 
Change `id` -> `event_id` and include push section
This commit is contained in:
David Baker 2016-04-06 20:58:11 +01:00
commit 0411cf54da
5 changed files with 109 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

180
api/push-gateway/push_notifier.yaml
View file

@ -17,10 +17,23 @@ paths:
summary: Notify a push gateway about an event. summary: Notify a push gateway about an event.
description: |- description: |-
This endpoint is invoked by HTTP pushers to notify a push gateway about This endpoint is invoked by HTTP pushers to notify a push gateway about
an event. an event or update the number of unread notifications a user has.
*NB: Notifications are sent to the URL configured when the pusher is 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 created. This means that the HTTP path may be different depending on the
push gateway.* push gateway.
parameters: parameters:
- in: body - in: body
name: notification name: notification
@ -42,47 +55,58 @@ paths:
"content": { "content": {
"msgtype": "m.text", "msgtype": "m.text",
"body": "I'm floating in a most peculiar way." "body": "I'm floating in a most peculiar way."
} },
}, "counts": {
"counts": { "unread" : 2,
"unread" : 2, "missed_calls": 1
"missed_calls": 1 },
}, "devices": [
"devices": [ {
{ "app_id": "org.matrix.matrixConsole.ios",
"app_id": "org.matrix.matrixConsole.ios", "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
"pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", "pushkey_ts": 12345678,
"pushkey_ts": 12345678, "data" : {},
"data" : {}, "tweaks": {
"tweaks": { "sound": "bing"
"sound": "bing" }
} }
} ]
] }
} }
required: ["notification", "counts", "devices"] required: ["notification"]
properties: properties:
notification: notification:
type: object type: object
title: Notification
description: Information about the push notification description: Information about the push notification
required: ["id", "room_id", "type", "sender"] required: ["devices"]
properties: properties:
id: event_id:
type: string type: string
description: |- description: |-
An identifier for this notification that may be used to The Matrix event ID of the event being notified about.
detect duplicate notification requests. This is not This is required if the notification is about a
necessarily the ID of the event that triggered the particular Matrix event. It may be omitted for notifications
notification. that only contain updated badge counts. This ID can and
should be used to detect duplicate notification requests.
room_id: room_id:
type: string type: string
description: The ID of the room in which this event occurred. description: |-
The ID of the room in which this event occurred.
Required if the notification relates to a specific
Matrix event.
type: type:
type: string type: string
description: The type of the event as in the event's ``type`` field. description: |-
The type of the event as in the event's ``type`` field.
Required if the notification relates to a specific
Matrix event.
sender: sender:
type: string type: string
description: The sender of the event as in the corresponding event field. description: |-
The sender of the event as in the corresponding event field.
Required if the notification relates to a specific
Matrix event.
sender_display_name: sender_display_name:
type: string type: string
description: |- description: |-
@ -114,56 +138,58 @@ paths:
description: |- description: |-
The ``content`` field from the event, if present. If the The ``content`` field from the event, if present. If the
event had no content field, this field is omitted. event had no content field, this field is omitted.
counts: counts:
type: object type: object
description: |- title: Counts
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: |- description: |-
The number of unread messages a user has across all of the This is a dictionary of the current number of unacknowledged
rooms they are a member of. communications for the recipient user. Counts whose value is
missed_calls: zero are omitted.
type: integer 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: |- description: |-
The number of unacknowledged missed calls a user has This is an array of devices that the notification should be sent to.
across all rooms of which they are a member. items:
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 type: object
title: PusherData title: Device
description: |- properties:
A dictionary of additional pusher-specific data. For app_id:
'http' pushers, this is the data dictionary passed in at type: string
pusher creation minus the ``url`` key. description: |-
tweaks: The app_id given when the pusher was created.
type: object pushkey:
title: Tweaks type: string
description: |- description: The pushkey given when the pusher was created.
A dictionary of customisations made to the way this pushkey_ts:
notification is to be presented. These are added by push rules. 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: responses:
200: 200:
description: A list of rejected push keys. description: A list of rejected push keys.

1
specification/index.rst
View file

@ -20,6 +20,7 @@ The following APIs are documented in this specification:
- `Server-Server API <server_server.html>`_ version %SERVER_RELEASE_LABEL% for writing servers which can federate with Matrix. - `Server-Server API <server_server.html>`_ version %SERVER_RELEASE_LABEL% for writing servers which can federate with Matrix.
- `Application Service API <application_service.html>`_ version %CLIENT_RELEASE_LABEL% for writing privileged plugins to servers. - `Application Service API <application_service.html>`_ version %CLIENT_RELEASE_LABEL% for writing privileged plugins to servers.
- `Identity Service API <identity_service.html>`_ version unstable for mapping third party identifiers (e.g. email addresses) to Matrix IDs. - `Identity Service API <identity_service.html>`_ version unstable for mapping third party identifiers (e.g. email addresses) to Matrix IDs.
- `Push Gateway API <push_gateway.html>`_ version unstable for implementing a server that receives notifications about Matrix events a user is interested in.
There are also some `appendices <appendices.html>`_. There are also some `appendices <appendices.html>`_.

2
specification/push_gateway.rst
View file

@ -39,4 +39,4 @@ This describes the format used by "HTTP" pushers to send notifications of
events to Push Gateways. If the endpoint returns an HTTP error code, the events to Push Gateways. If the endpoint returns an HTTP error code, the
homeserver SHOULD retry for a reasonable amount of time using exponential backoff. homeserver SHOULD retry for a reasonable amount of time using exponential backoff.
{{push_notifier_http_api}} {{push_notifier_push_http_api}}

3
specification/targets.yaml
View file

@ -22,6 +22,9 @@ targets:
identity_service: identity_service:
files: files:
- identity_service_api.rst - identity_service_api.rst
push_gateway:
files:
- push_gateway.rst
appendices: appendices:
files: files:
- appendices.rst - appendices.rst

1
templating/matrix_templates/units.py
View file

@ -21,6 +21,7 @@ HTTP_APIS = {
"../api/application-service": "as", "../api/application-service": "as",
"../api/client-server": "cs", "../api/client-server": "cs",
"../api/identity": "is", "../api/identity": "is",
"../api/push-gateway": "push",
} }
EVENT_EXAMPLES = "../event-schemas/examples" EVENT_EXAMPLES = "../event-schemas/examples"
EVENT_SCHEMA = "../event-schemas/schema" EVENT_SCHEMA = "../event-schemas/schema"