diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst new file mode 100644 index 00000000..4747bd48 --- /dev/null +++ b/specification/modules/dm.rst @@ -0,0 +1,57 @@ +.. 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 communications over Matrix happens within a room. It is sometimes +desireable 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. The invitee's client may +use this flag to automatically mark the room as a direct message but +this is not required: it may for example, prompt the user, ignore the +flag altogether. + +Events +------ + +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. + +Example:: + + { + "@bob:example.com": [ + "!abcdefgh:example.com", + "!hgfedcba:example.com" + ] + } + + +When creating a room, the ``is_direct`` flag may be specified to signal +to the invitee that this is a direct chat. See +`GET /_matrix/client/unstable/initialSync`_. This flag appears as +``is_direct`` in the member event: see `m.room.member`_. diff --git a/specification/targets.yaml b/specification/targets.yaml index 6cbfa917..c63db5a6 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -53,6 +53,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/admin.rst - modules/event_context.rst - modules/cas_login.rst + - modules/dm.rst title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]