Merge branch 'master' of github.com:matrix-org/matrix-doc into erikj/public_rooms
Erik Johnston
8 years ago
commit
a69d6c63c6
@ -0,0 +1,142 @@
|
||||
# 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 Notifications 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:
|
||||
"/notifications":
|
||||
get:
|
||||
summary: Gets a list of events that the user has been notified about
|
||||
description: |-
|
||||
This API is used to paginate through the list of events that the
|
||||
user has been, or would have been notified about.
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: query
|
||||
type: string
|
||||
name: from
|
||||
description: Pagination token given to retrieve the next set of events.
|
||||
required: false
|
||||
x-example: "xxxxx"
|
||||
- in: query
|
||||
type: number
|
||||
name: limit
|
||||
description: Limit on the number of events to return in this request.
|
||||
required: false
|
||||
x-example: "20"
|
||||
- in: query
|
||||
name: only
|
||||
type: string
|
||||
description: |-
|
||||
Allows basic filtering of events returned. Supply ``highlight``
|
||||
to return only events where the notification had the highlight
|
||||
tweak set.
|
||||
required: false
|
||||
x-example: "highlight"
|
||||
responses:
|
||||
200:
|
||||
description: A batch of events is being returned
|
||||
examples:
|
||||
application/json: |-
|
||||
{
|
||||
"next_token": "abcdef",
|
||||
"notifications": [
|
||||
{
|
||||
"actions": [
|
||||
"notify"
|
||||
],
|
||||
"profile_tag": "hcbvkzxhcvb",
|
||||
"read": true,
|
||||
"room_id": "!abcdefg:example.com",
|
||||
"ts": 1475508881945,
|
||||
"event": {
|
||||
"sender": "@alice:example.com",
|
||||
"type": "m.room.message",
|
||||
"age": 124524,
|
||||
"txn_id": "1234",
|
||||
"content": {
|
||||
"body": "I am a fish",
|
||||
"msgtype": "m.text"
|
||||
},
|
||||
"origin_server_ts": 1417731086797,
|
||||
"event_id": "$74686972643033:example.com"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
required: ["notifications"]
|
||||
properties:
|
||||
next_token:
|
||||
type: string
|
||||
description: |-
|
||||
The token to supply in the ``from`` param of the next
|
||||
``/notifications`` request in order to request more
|
||||
events. If this is absent, there are no more results.
|
||||
notifications:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
required: ["actions", "event", "read", "room_id", "ts"]
|
||||
title: Notification
|
||||
properties:
|
||||
actions:
|
||||
type: array
|
||||
description: |-
|
||||
The action(s) to perform when the conditions for this rule are met.
|
||||
See `Push Rules: API`_.
|
||||
items:
|
||||
type:
|
||||
- object
|
||||
- string
|
||||
event:
|
||||
type: object
|
||||
title: Event
|
||||
description: The Event object for the event that triggered the notification.
|
||||
allOf:
|
||||
- "$ref": "definitions/event.yaml"
|
||||
profile_tag:
|
||||
type: string
|
||||
description: The profile tag of the rule that matched this event.
|
||||
read:
|
||||
type: boolean
|
||||
description: |-
|
||||
Indicates whether the user has sent a read receipt indicating
|
||||
that they have read this message.
|
||||
room_id:
|
||||
type: string
|
||||
description: The ID of the room in which the event was posted.
|
||||
ts:
|
||||
type: integer
|
||||
description: |-
|
||||
The unix timestamp at which the event notification was sent,
|
||||
in milliseconds.
|
||||
description: The list of events that triggered notifications.
|
||||
tags:
|
||||
- Push notifications
|
||||
@ -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 an event to a given set of devices.
|
||||
description: |-
|
||||
This endpoint is used to send send-to-device 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": {
|
||||
"TLLBEANAAG": {
|
||||
"example_content_key": "value"
|
||||
}
|
||||
}
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The message was successfully sent.
|
||||
examples:
|
||||
application/json: |-
|
||||
{}
|
||||
tags:
|
||||
- Send-to-Device messaging
|
||||
@ -0,0 +1,9 @@
|
||||
{
|
||||
"type": "m.direct",
|
||||
"content": {
|
||||
"@bob:example.com": [
|
||||
"!abcdefgh:example.com",
|
||||
"!hgfedcba:example.com"
|
||||
]
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,21 @@
|
||||
---
|
||||
allOf:
|
||||
- $ref: core-event-schema/event.yaml
|
||||
description: |-
|
||||
A map of which rooms are considered 'direct' rooms for specific users
|
||||
is kept in ``account_data`` in an event of type ``m.direct``. The
|
||||
content of this event is an object where the keys are the user IDs
|
||||
and values are lists of room ID strings of the 'direct' rooms for
|
||||
that user ID.
|
||||
properties:
|
||||
content:
|
||||
additionalProperties:
|
||||
type: array
|
||||
title: User ID
|
||||
type: object
|
||||
type:
|
||||
enum:
|
||||
- m.direct
|
||||
type: string
|
||||
title: Direct Chat Mapping
|
||||
type: object
|
||||
@ -0,0 +1,58 @@
|
||||
.. 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.
|
||||
|
||||
Direct Messaging
|
||||
================
|
||||
|
||||
.. _module:dm:
|
||||
|
||||
All communication over Matrix happens within a room. It is sometimes
|
||||
desirable to offer users the concept of speaking directly to one
|
||||
particular person. This module defines a way of marking certain rooms
|
||||
as 'direct chats' with a given person. This does not restrict the chat
|
||||
to being between exactly two people since this would preclude the
|
||||
presence of automated 'bot' users or even a 'personal assistant' who is
|
||||
able to answer direct messages on behalf of the user in their absence.
|
||||
|
||||
A room may not necessarily be considered 'direct' by all members of the
|
||||
room, but a signalling mechanism exists to propagate the information of
|
||||
whether a chat is 'direct' to an invitee.
|
||||
|
||||
Events
|
||||
------
|
||||
|
||||
{{m_direct_event}}
|
||||
|
||||
Client behaviour
|
||||
----------------
|
||||
To start a direct chat with another user, the inviting user's client
|
||||
should set the ``is_direct`` flag to |/createRoom|_. The client should do
|
||||
this whenever the flow the user has followed is one where their
|
||||
intention is to speak directly with another person, as opposed to bringing that
|
||||
person in to a shared room. For example, clicking on 'Start Chat' beside a
|
||||
person's profile picture would imply the ``is_direct`` flag should be set.
|
||||
|
||||
The invitee's client may use the ``is_direct`` flag in the `m.room.member`_
|
||||
event to automatically mark the room as a direct chat but this is not
|
||||
required: it may for example, prompt the user, or ignore the flag altogether.
|
||||
|
||||
Both the inviting client and the invitee's client should record the fact that
|
||||
the room is a direct chat by storing an ``m.direct`` event in the account data
|
||||
using |/user/<user_id>/account_data/<type>|_.
|
||||
|
||||
Server behaviour
|
||||
----------------
|
||||
When the ``is_direct`` flag is given to |/createRoom|_, the home
|
||||
server must set the ``is_direct`` flag in the invite member event for any users
|
||||
invited in the |/createRoom|_ call.
|
||||
@ -0,0 +1,146 @@
|
||||
.. 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.
|
||||
|
||||
Send-to-Device 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.
|
||||
|
||||
The primary motivation for this API is exchanging data that is meaningless or
|
||||
undesirable to persist in the room DAG - for example, one-time authentication
|
||||
tokens or key data. It is not intended for conversational data, which should be
|
||||
sent using the normal |/rooms/<room_id>/send|_ API for consistency throughout
|
||||
Matrix.
|
||||
|
||||
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 send-to-device 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 send-to-device messages in
|
||||
that response have been delivered successfully, and delete them from the store.
|
||||
|
||||
If there is a large queue of send-to-device 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#send-to-device-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
|
||||
.. |send_to_device_sync| replace:: Send-to-Device messaging
|
||||
.. _send_to_device_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 send-to-device messages
|
||||
for the client device.
|
||||
========= ========= =======================================================
|
||||
|
||||
``ToDevice``
|
||||
|
||||
========= ========= =============================================
|
||||
Parameter Type Description
|
||||
========= ========= =============================================
|
||||
events [Event] List of send-to-device 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
|
||||
@ -0,0 +1,13 @@
|
||||
---
|
||||
layout: project
|
||||
title: MatrixTool
|
||||
categories: projects other
|
||||
description: Commands to interact with a Matrix homeserver
|
||||
author: LeoNerd
|
||||
maturity: Alpha
|
||||
---
|
||||
# {{ page.title }}
|
||||
|
||||
The tool provides a wrapper around a number of sub-commands that provide useful interactions with a Matrix homeserver.
|
||||
|
||||
You can grab it from [CPAN](http://search.cpan.org/~pevans/App-MatrixTool/).
|
||||
@ -0,0 +1,12 @@
|
||||
---
|
||||
layout: project
|
||||
title: telematrix
|
||||
categories: projects as
|
||||
author: SijmenSchoon
|
||||
maturity: Alpha
|
||||
---
|
||||
|
||||
# {{ page.title }}
|
||||
This project bridges [Telegram Messenger](https://telegram.org/) to Matrix. It's currently in early development, and not considered to be in a usable state yet.
|
||||
|
||||
Get it and report issues at [github](https://github.com/SijmenSchoon/telematrix)!
|
||||
Loading…
Reference in New Issue