Merge pull request #389 from matrix-org/erikj/create_room_is_direct

Spec /createRoom is_direct flag, is_direct in member event and m.direct

api/client-server/create_room.yaml

@@ -170,7 +170,12 @@ paths:
                   ``public_chat``: =>
                       ``join_rules`` is set to ``public``.
                       ``history_visibility`` is set to ``shared``.
-
+              is_direct:
+                type: boolean
+                description: |-
+                  This flag makes the server set the ``is_direct`` flag on the
+                  ``m.room.member`` events sent to the users in ``invite`` and
+                  ``invite_3pid``. See `Direct Messaging`_ for more information.
       responses:
         200:
           description: Information about the newly created room.

changelogs/client_server.rst

@@ -25,6 +25,9 @@
   - Add top-level ``account_data`` key to the responses to ``GET /sync`` and
     ``GET /initialSync``
     (`#380 <https://github.com/matrix-org/matrix-doc/pull/380>`_).
+  - Add ``is_direct`` flag to |/createRoom|_ and invite member event.
+    Add 'Direct Messaging' module.
+    (`#389 <https://github.com/matrix-org/matrix-doc/pull/389>`_).
   - Add ``contains_url`` option to ``RoomEventFilter``.
     (`#390 <https://github.com/matrix-org/matrix-doc/pull/390>`_).
   - Add ``filter`` optional query param to ``/messages``

event-schemas/examples/m.direct

@@ -0,0 +1,9 @@
+{
+  "type": "m.direct",
+  "content": {
+    "@bob:example.com": [
+        "!abcdefgh:example.com",
+        "!hgfedcba:example.com"
+      ]
+  }
+}

event-schemas/schema/m.direct

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

event-schemas/schema/m.room.member

@@ -39,6 +39,9 @@ properties:
           - leave
           - ban
         type: string
+      is_direct:
+        description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See `Direct Messaging`_.
+        type: boolean
       third_party_invite:
         properties:
           display_name:

specification/client_server_api.rst

@@ -1281,6 +1281,9 @@ have to wait in milliseconds before they can try again.
 .. |/events| replace:: ``/events``
 .. _/events: #get-matrix-client-%CLIENT_MAJOR_VERSION%-events
 
+.. |/createRoom| replace:: ``/createRoom``
+.. _/createRoom: #post-matrix-client-%CLIENT_MAJOR_VERSION%-createroom
+
 .. |/rooms/<room_id>/initialSync| replace:: ``/rooms/<room_id>/initialSync``
 .. _/rooms/<room_id>/initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync
 
@@ -1316,3 +1319,6 @@ have to wait in milliseconds before they can try again.
 
 .. |/account/3pid| replace:: ``/account/3pid``
 .. _/account/3pid: #post-matrix-client-%CLIENT_MAJOR_VERSION%-account-3pid
+
+.. |/user/<user_id>/account_data/<type>| replace:: ``/user/<user_id>/account_data/<type>``
+.. _/user/<user_id>/account_data/<type>: #put-matrix-client-%CLIENT_MAJOR_VERSION%-user-userid-account-data-type

specification/modules/dm.rst

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

specification/targets.yaml

@@ -54,6 +54,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: ["=", "-", "~", "+", "^", "`", "@", ":"]