Specification for direct-to-device messages
Richard van der Hoff
8 years ago
parent
459f4b953d
commit
ccd7bb32d5
@ -0,0 +1,89 @@
|
|||||||
|
# Copyright 2016 OpenMarket 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 Client-Server Send-to-device API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/sendToDevice/{eventType}/{txnId}":
|
||||||
|
put:
|
||||||
|
summary: Send to-device event to a given set of devices.
|
||||||
|
description: |-
|
||||||
|
This endpoint is used to send store-and-forward events to a set of
|
||||||
|
client devices.
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: eventType
|
||||||
|
description: The type of event to send.
|
||||||
|
required: true
|
||||||
|
x-example: "m.new_device"
|
||||||
|
- in: path
|
||||||
|
name: txnId
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The transaction ID for this event. Clients should generate an
|
||||||
|
ID unique across requests with the same access token; it will be
|
||||||
|
used by the server to ensure idempotency of requests.
|
||||||
|
required: true
|
||||||
|
x-example: "35"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
title: body
|
||||||
|
properties:
|
||||||
|
messages:
|
||||||
|
type: object
|
||||||
|
description: |-
|
||||||
|
The messages to send. A map from user ID, to a map from
|
||||||
|
device ID to message body. The device ID may also be `*`,
|
||||||
|
meaning all known devices for the user.
|
||||||
|
additionalProperties:
|
||||||
|
type: object
|
||||||
|
additionalProperties:
|
||||||
|
type: object
|
||||||
|
title: EventContent
|
||||||
|
description: Message content
|
||||||
|
example: {
|
||||||
|
"@alice:example.com": {
|
||||||
|
"tLLbenaag": {
|
||||||
|
"example_content_key": "value"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description:
|
||||||
|
The message was successfully sent.
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{}
|
||||||
|
tags:
|
||||||
|
- Store-and-forward messaging
|
||||||
@ -0,0 +1,140 @@
|
|||||||
|
.. Copyright 2016 OpenMarket 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.
|
||||||
|
|
||||||
|
Store-and-Forward messaging
|
||||||
|
===========================
|
||||||
|
|
||||||
|
.. _module:to_device:
|
||||||
|
|
||||||
|
This module provides a means by which clients can exchange signalling messages
|
||||||
|
without them being stored permanently as part of a shared communication
|
||||||
|
history. A message is delivered exactly once to each client device.
|
||||||
|
|
||||||
|
Client behaviour
|
||||||
|
----------------
|
||||||
|
To send a message to other devices, a client should call |/sendToDevice|_.
|
||||||
|
Only one message can be sent to each device per transaction, and they must all
|
||||||
|
have the same event type. The device ID in the request body can be set to ``*``
|
||||||
|
to request that the message be sent to all known devices.
|
||||||
|
|
||||||
|
If there are store-and-forward messages waiting for a client, they will be
|
||||||
|
returned by |/sync|_, as detailed in `Extensions to /sync`_. Clients should
|
||||||
|
inspect the ``type`` of each returned event, and ignore any they do not
|
||||||
|
understand.
|
||||||
|
|
||||||
|
Server behaviour
|
||||||
|
----------------
|
||||||
|
Servers should store pending messages for local users until they are
|
||||||
|
successfully delivered to the destination device. When a client calls |/sync|_
|
||||||
|
with an access token which corresponds to a device with pending messages, the
|
||||||
|
server should list the pending messages, in order of arrival, in the response
|
||||||
|
body.
|
||||||
|
|
||||||
|
When the client calls ``/sync`` again with the ``next_batch`` token from the
|
||||||
|
first response, the server should infer that any store-and-forward messages in
|
||||||
|
that response have been delivered successfully, and delete them from the store.
|
||||||
|
|
||||||
|
If there is a large queue of store-and-forward messages, the server should
|
||||||
|
limit the number sent in each ``/sync`` response. 100 messages is recommended
|
||||||
|
as a reasonable limit.
|
||||||
|
|
||||||
|
If the client sends messages to users on remote domains, those messages should
|
||||||
|
be sent on to the remote servers via
|
||||||
|
`federation`_.
|
||||||
|
|
||||||
|
.. _`federation`: ../server_server/latest.html#store-and-forward-messages
|
||||||
|
|
||||||
|
.. TODO-spec:
|
||||||
|
|
||||||
|
* Is a server allowed to delete undelivered messages? After how long? What
|
||||||
|
about if the device is deleted?
|
||||||
|
|
||||||
|
* If the destination HS doesn't support the ``m.direct_to_device`` EDU, it
|
||||||
|
will just get dumped. Should we indicate that to the client?
|
||||||
|
|
||||||
|
|
||||||
|
Protocol definitions
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
{{to_device_cs_http_api}}
|
||||||
|
|
||||||
|
.. TODO-spec:
|
||||||
|
|
||||||
|
* What should a server do if the user id or device id is unknown? Presumably
|
||||||
|
it shouldn't reject the request outright, because some of the destinations
|
||||||
|
may be valid. Should we add something to the response?
|
||||||
|
|
||||||
|
.. anchor for link from /sync api spec
|
||||||
|
.. |store_and_forward_sync| replace:: Store-and-Forward messaging
|
||||||
|
.. _store_and_forward_sync:
|
||||||
|
|
||||||
|
Extensions to /sync
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
This module adds the following properties to the |/sync|_ response:
|
||||||
|
|
||||||
|
.. todo: generate this from a swagger definition?
|
||||||
|
|
||||||
|
========= ========= =======================================================
|
||||||
|
Parameter Type Description
|
||||||
|
========= ========= =======================================================
|
||||||
|
to_device ToDevice Optional. Information on the store-and-forward messages
|
||||||
|
for the client device.
|
||||||
|
========= ========= =======================================================
|
||||||
|
|
||||||
|
``ToDevice``
|
||||||
|
|
||||||
|
========= ========= =============================================
|
||||||
|
Parameter Type Description
|
||||||
|
========= ========= =============================================
|
||||||
|
events [Event] List of store-and-forward messages
|
||||||
|
========= ========= =============================================
|
||||||
|
|
||||||
|
``Event``
|
||||||
|
|
||||||
|
================ ============ ==================================================
|
||||||
|
Parameter Type Description
|
||||||
|
================ ============ ==================================================
|
||||||
|
content EventContent The content of this event. The fields in this
|
||||||
|
object will vary depending on the type of event.
|
||||||
|
sender string The Matrix user ID of the user who sent this
|
||||||
|
event.
|
||||||
|
type string The type of event.
|
||||||
|
================ ============ ==================================================
|
||||||
|
|
||||||
|
|
||||||
|
Example response:
|
||||||
|
|
||||||
|
.. code:: json
|
||||||
|
|
||||||
|
{
|
||||||
|
"next_batch": "s72595_4483_1934",
|
||||||
|
"rooms": {"leave": {}, "join": {}, "invite": {}},
|
||||||
|
"to_device": {
|
||||||
|
"events": [
|
||||||
|
{
|
||||||
|
"sender": "@alice:example.com",
|
||||||
|
"type": "m.new_device",
|
||||||
|
"content": {
|
||||||
|
"device_id": "XYZABCDE",
|
||||||
|
"rooms": ["!726s6s6q:example.com"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
.. |/sendToDevice| replace:: ``/sendToDevice``
|
||||||
|
.. _/sendToDevice: #put-matrix-client-%CLIENT_MAJOR_VERSION%-sendtodevice-eventtype-txnid
|
||||||
Loading…
Reference in New Issue