From 3a5cbd14c3ec4e27e9de4e616ef61b0ef89c2273 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 29 Sep 2016 11:25:12 +0100 Subject: [PATCH 01/24] Add /createRoom is_direct flag --- api/client-server/create_room.yaml | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 9107e185..2e7cc0ad 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -170,7 +170,15 @@ paths: ``public_chat``: => ``join_rules`` is set to ``public``. ``history_visibility`` is set to ``shared``. - + is_direct: + type: boolean + description: |- + This flag shows that the intent for this room is to be a + one-to-one 'direct' conversation with the invitee. The + invitee's client should indicate this in the UI to the user, + as should the inviter. This is to keep the intent for new rooms + synchronised at first. Both users may subsequently choose to + tag the room differently. responses: 200: description: Information about the newly created room. From d01d1a07a6832de36f3f2cfb32d9ddac67e9d4c4 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 29 Sep 2016 17:19:54 +0100 Subject: [PATCH 02/24] Add changelog --- changelogs/client_server.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index d7384e31..7a8536e3 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -35,6 +35,8 @@ - Add top-level ``account_data`` key to the responses to ``GET /sync`` and ``GET /initialSync`` (`#380 `_). + - Add ``is_direct`` flag to ``/createRoom``. + (`#389 `_). r0.2.0 ====== From b121feebce9524eb1ce4102bc0c012369c85a3d5 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 30 Sep 2016 11:24:51 +0100 Subject: [PATCH 03/24] Comment what the is_direct flag actually does --- api/client-server/create_room.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 2e7cc0ad..87289682 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -179,6 +179,8 @@ paths: as should the inviter. This is to keep the intent for new rooms synchronised at first. Both users may subsequently choose to tag the room differently. + This adds an ``is_direct`` flag to the content of any invites + sent. responses: 200: description: Information about the newly created room. From 5fedc64230d20221a2758be145f3f01db17c4b06 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 3 Oct 2016 15:52:08 +0100 Subject: [PATCH 04/24] double space --- api/client-server/create_room.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 87289682..c4a9c8ff 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -173,7 +173,7 @@ paths: is_direct: type: boolean description: |- - This flag shows that the intent for this room is to be a + This flag shows that the intent for this room is to be a one-to-one 'direct' conversation with the invitee. The invitee's client should indicate this in the UI to the user, as should the inviter. This is to keep the intent for new rooms From 8fe8bd6a815c3f1fa38bb9e3942cfa9ff36399db Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 3 Oct 2016 17:33:45 +0100 Subject: [PATCH 05/24] Add is_direct to member event spec. --- api/client-server/create_room.yaml | 3 ++- event-schemas/schema/m.room.member | 3 +++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index c4a9c8ff..ce9ab46b 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -180,7 +180,8 @@ paths: synchronised at first. Both users may subsequently choose to tag the room differently. This adds an ``is_direct`` flag to the content of any invites - sent. + sent, which will appear in the content of the `m.room.member`_ + event. responses: 200: description: Information about the newly created room. diff --git a/event-schemas/schema/m.room.member b/event-schemas/schema/m.room.member index f9aa5051..adb9a831 100644 --- a/event-schemas/schema/m.room.member +++ b/event-schemas/schema/m.room.member @@ -39,6 +39,9 @@ properties: - leave - ban type: string + is_direct: + description: Flag indicating if this room was created with the intention of being a direct chat + type: boolean third_party_invite: properties: display_name: From 203ea993281d4babe8be45638bd1d395ab0a7827 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 3 Oct 2016 18:17:43 +0100 Subject: [PATCH 06/24] Spec m.direct --- specification/modules/dm.rst | 57 ++++++++++++++++++++++++++++++++++++ specification/targets.yaml | 1 + 2 files changed, 58 insertions(+) create mode 100644 specification/modules/dm.rst 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: ["=", "-", "~", "+", "^", "`", "@", ":"] From accb3941bfbb4a79fa46f3e81896718280bf1de3 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 3 Oct 2016 18:20:45 +0100 Subject: [PATCH 07/24] Changelog --- changelogs/client_server.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index f156c96e..10d4f82e 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -37,7 +37,8 @@ - Add top-level ``account_data`` key to the responses to ``GET /sync`` and ``GET /initialSync`` (`#380 `_). - - Add ``is_direct`` flag to ``/createRoom``. + - Add ``is_direct`` flag to ``/createRoom`` and invite member event. + Add 'Direct Messaging' module. (`#389 `_). - Add ``contains_url`` option to ``RoomEventFilter``. (`#390 `_). From d39f662df5221aba99ed2ebcf1cb8f0855358f50 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 4 Oct 2016 11:57:24 +0100 Subject: [PATCH 08/24] PR feedback --- api/client-server/create_room.yaml | 12 +++--------- specification/modules/dm.rst | 2 +- 2 files changed, 4 insertions(+), 10 deletions(-) diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index ce9ab46b..811b1187 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -173,15 +173,9 @@ paths: is_direct: type: boolean description: |- - This flag shows that the intent for this room is to be a - one-to-one 'direct' conversation with the invitee. The - invitee's client should indicate this in the UI to the user, - as should the inviter. This is to keep the intent for new rooms - synchronised at first. Both users may subsequently choose to - tag the room differently. - This adds an ``is_direct`` flag to the content of any invites - sent, which will appear in the content of the `m.room.member`_ - event. + 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. diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index 4747bd48..30f4067d 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -17,7 +17,7 @@ Direct Messaging .. _module:dm: -All communications over Matrix happens within a room. It is sometimes +All communication 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 From 976d41351e9dbd3b59306d996540c9b6b7da8d45 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 4 Oct 2016 12:43:41 +0100 Subject: [PATCH 09/24] spelling --- specification/modules/dm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index 30f4067d..54102e74 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -18,7 +18,7 @@ Direct Messaging .. _module:dm: All communication over Matrix happens within a room. It is sometimes -desireable to offer users the concept of speaking directly to one +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 From 85bc989c026457d233bc50ed18698cf6690b89ef Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 4 Oct 2016 15:07:14 +0100 Subject: [PATCH 10/24] pr feedback --- event-schemas/examples/m.direct | 9 +++++++++ event-schemas/schema/m.direct | 23 ++++++++++++++++++++++ specification/modules/dm.rst | 35 ++++++++++++++++++++------------- 3 files changed, 53 insertions(+), 14 deletions(-) create mode 100644 event-schemas/examples/m.direct create mode 100644 event-schemas/schema/m.direct diff --git a/event-schemas/examples/m.direct b/event-schemas/examples/m.direct new file mode 100644 index 00000000..92f13daa --- /dev/null +++ b/event-schemas/examples/m.direct @@ -0,0 +1,9 @@ +{ + "type": "m.direct", + "content": { + "@bob:example.com": [ + "!abcdefgh:example.com", + "!hgfedcba:example.com" + ] + } +} diff --git a/event-schemas/schema/m.direct b/event-schemas/schema/m.direct new file mode 100644 index 00000000..4f568078 --- /dev/null +++ b/event-schemas/schema/m.direct @@ -0,0 +1,23 @@ +{ + "type": "object", + "title": "Direct Message Map Event", + "description": "Account Data event used to store which rooms are 'direct chats' for which users.", + "allOf": [{ + "$ref": "core-event-schema/event.yaml" + }], + "properties": { + "type": { + "type": "string", + "enum": ["m.direct"] + }, + "content": { + "type": "object", + "description": "Object mapping user IDs to lists of room IDs.", + "additionalProperties": { + "title": "User ID", + "type": "array" + } + } + }, + "required": ["type", "content"] +} diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index 54102e74..6170d98a 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -27,10 +27,7 @@ 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. +whether a chat is 'direct' to an invitee. Events ------ @@ -41,17 +38,27 @@ 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`_. + +{{m_direct_event}} + +Client behaviour +---------------- +The invitee's client may use the ``is_direct`` 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. + +The inviter's client should set the ``is_direct`` flag to ``createRoom`` +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. + +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. From 8af90bfc2147439e7ad062d104941b49be177ceb Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 4 Oct 2016 15:08:48 +0100 Subject: [PATCH 11/24] Clarify 'this room' --- event-schemas/schema/m.room.member | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event-schemas/schema/m.room.member b/event-schemas/schema/m.room.member index adb9a831..06c4fa3b 100644 --- a/event-schemas/schema/m.room.member +++ b/event-schemas/schema/m.room.member @@ -40,7 +40,7 @@ properties: - ban type: string is_direct: - description: Flag indicating if this room was created with the intention of being a direct chat + description: Flag indicating if the room containing this event was created with the intention of being a direct chat. type: boolean third_party_invite: properties: From 8e096bdc48bd9c362fff074a3ec7742eacfb459e Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 4 Oct 2016 15:15:01 +0100 Subject: [PATCH 12/24] Link to createRoom, not initialsync --- specification/modules/dm.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index 6170d98a..f204583e 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -38,9 +38,9 @@ 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. -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 +When creating a room, the ``is_direct`` flag may be specified to signal to the +invitee that this is a direct chat. See `POST +/_matrix/client/%CLIENT_MAJOR_VERSION%/createRoom`_. This flag appears as ``is_direct`` in the member event: see `m.room.member`_. {{m_direct_event}} From b789251f70b879f2add117291939db7f39b82372 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 5 Oct 2016 12:59:49 +0100 Subject: [PATCH 13/24] More PR feedback --- api/client-server/create_room.yaml | 6 +++--- event-schemas/schema/m.room.member | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 811b1187..a321b0f7 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -173,9 +173,9 @@ paths: 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. + 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. diff --git a/event-schemas/schema/m.room.member b/event-schemas/schema/m.room.member index 06c4fa3b..4f4077a7 100644 --- a/event-schemas/schema/m.room.member +++ b/event-schemas/schema/m.room.member @@ -40,7 +40,7 @@ properties: - ban type: string is_direct: - description: Flag indicating if the room containing this event was created with the intention of being a direct chat. + 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: From 4480553bf96b859d9a289db989dcd187a4a16f1e Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 5 Oct 2016 13:12:14 +0100 Subject: [PATCH 14/24] Move m.direct description to the swagger Also change the swagger to yaml so I can put that description in it without having to figure out how to embed that in json. --- event-schemas/schema/m.direct | 44 +++++++++++++++++------------------ specification/modules/dm.rst | 12 +++------- 2 files changed, 24 insertions(+), 32 deletions(-) diff --git a/event-schemas/schema/m.direct b/event-schemas/schema/m.direct index 4f568078..b8a9cfc2 100644 --- a/event-schemas/schema/m.direct +++ b/event-schemas/schema/m.direct @@ -1,23 +1,21 @@ -{ - "type": "object", - "title": "Direct Message Map Event", - "description": "Account Data event used to store which rooms are 'direct chats' for which users.", - "allOf": [{ - "$ref": "core-event-schema/event.yaml" - }], - "properties": { - "type": { - "type": "string", - "enum": ["m.direct"] - }, - "content": { - "type": "object", - "description": "Object mapping user IDs to lists of room IDs.", - "additionalProperties": { - "title": "User ID", - "type": "array" - } - } - }, - "required": ["type", "content"] -} +--- +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 diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index f204583e..5ebfb169 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -32,21 +32,15 @@ whether a chat is 'direct' to an invitee. 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. +{{m_direct_event}} +Client behaviour +---------------- When creating a room, the ``is_direct`` flag may be specified to signal to the invitee that this is a direct chat. See `POST /_matrix/client/%CLIENT_MAJOR_VERSION%/createRoom`_. This flag appears as ``is_direct`` in the member event: see `m.room.member`_. -{{m_direct_event}} - -Client behaviour ----------------- The invitee's client may use the ``is_direct`` 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. From d791f3500736b90914969ccf7654af7d693c7a54 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 5 Oct 2016 13:13:50 +0100 Subject: [PATCH 15/24] Remove unnecessary paragraph --- specification/modules/dm.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index 5ebfb169..639f7f85 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -36,11 +36,6 @@ Events Client behaviour ---------------- -When creating a room, the ``is_direct`` flag may be specified to signal to the -invitee that this is a direct chat. See `POST -/_matrix/client/%CLIENT_MAJOR_VERSION%/createRoom`_. This flag appears as -``is_direct`` in the member event: see `m.room.member`_. - The invitee's client may use the ``is_direct`` 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. From e2024e58297d9517434ca7a2cce8f966bdb6e4a5 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 5 Oct 2016 13:22:30 +0100 Subject: [PATCH 16/24] Add note on how to use the account data event --- specification/modules/dm.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index 639f7f85..4785f5b1 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -38,7 +38,8 @@ Client behaviour ---------------- The invitee's client may use the ``is_direct`` 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. +the user, ignore the flag altogether. To do this, it stores this event in +account data using the ``account_data`` API: see `Client Config`_. The inviter's client should set the ``is_direct`` flag to ``createRoom`` whenever the flow the user has followed is one where their intention is to From 3f66ba713cf7fc9e05a6eacd864a032a3d57cdc7 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 5 Oct 2016 13:25:42 +0100 Subject: [PATCH 17/24] Reference m.room.member section --- specification/modules/dm.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index 4785f5b1..32c3ebfa 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -36,10 +36,11 @@ Events Client behaviour ---------------- -The invitee's client may use the ``is_direct`` 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. To do this, it stores this event in -account data using the ``account_data`` API: see `Client Config`_. +The invitee's client may use the ``is_direct`` flag in `m.room.member`_ 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. To do this, it +stores this event in account data using the ``account_data`` API: see `Client +Config`_. The inviter's client should set the ``is_direct`` flag to ``createRoom`` whenever the flow the user has followed is one where their intention is to From 2259a00ba263d4d2ef5143756d1adfbe841e063e Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 5 Oct 2016 13:29:43 +0100 Subject: [PATCH 18/24] links --- specification/modules/dm.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index 32c3ebfa..5b15e3b3 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -42,14 +42,14 @@ may for example, prompt the user, ignore the flag altogether. To do this, it stores this event in account data using the ``account_data`` API: see `Client Config`_. -The inviter's client should set the ``is_direct`` flag to ``createRoom`` -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 inviter's client should set the ``is_direct`` flag to ``createRoom`` +(`Creation`_) 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. 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. +When the ``is_direct`` flag is given to ``createRoom`` (`Creation`_), the home +server must set the ``is_direct`` flag in the invite member event for any users +invited in the ``createRoom`` call. From 2a987c33695fa2c260eba5bf17cc1a5089814a70 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 5 Oct 2016 18:19:17 +0100 Subject: [PATCH 19/24] Linkify endpoints properly --- specification/client_server_api.rst | 3 +++ specification/modules/dm.rst | 6 +++--- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index a74129b5..f12b495b 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1246,6 +1246,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//initialSync| replace:: ``/rooms//initialSync`` .. _/rooms//initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index 5b15e3b3..d148b945 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -42,14 +42,14 @@ may for example, prompt the user, ignore the flag altogether. To do this, it stores this event in account data using the ``account_data`` API: see `Client Config`_. -The inviter's client should set the ``is_direct`` flag to ``createRoom`` -(`Creation`_) whenever the flow the user has followed is one where their +The inviter's client should set the ``is_direct`` flag to .. |/createRoom|_ +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. Server behaviour ---------------- -When the ``is_direct`` flag is given to ``createRoom`` (`Creation`_), the home +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. From e2736ba1674b14dcb9fa5dfddd9adebb417255f3 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 6 Oct 2016 10:12:08 +0100 Subject: [PATCH 20/24] Linkify createroom in changelog too --- changelogs/client_server.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 10d4f82e..0386166b 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -37,7 +37,7 @@ - Add top-level ``account_data`` key to the responses to ``GET /sync`` and ``GET /initialSync`` (`#380 `_). - - Add ``is_direct`` flag to ``/createRoom`` and invite member event. + - Add ``is_direct`` flag to .. |/createRoom|_ and invite member event. Add 'Direct Messaging' module. (`#389 `_). - Add ``contains_url`` option to ``RoomEventFilter``. From 301595c071856538cc97c85266a81b68d02c7704 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 6 Oct 2016 11:15:44 +0100 Subject: [PATCH 21/24] Linkify account_data API Also change other links because it turns out the .. isn't part of the syntax --- changelogs/client_server.rst | 2 +- specification/client_server_api.rst | 3 +++ specification/modules/dm.rst | 7 +++---- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 0386166b..273ac85c 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -37,7 +37,7 @@ - Add top-level ``account_data`` key to the responses to ``GET /sync`` and ``GET /initialSync`` (`#380 `_). - - Add ``is_direct`` flag to .. |/createRoom|_ and invite member event. + - Add ``is_direct`` flag to |/createRoom|_ and invite member event. Add 'Direct Messaging' module. (`#389 `_). - Add ``contains_url`` option to ``RoomEventFilter``. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index f12b495b..38dcd188 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1281,3 +1281,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//account_data/| replace:: ``/user//account_data/`` +.. _/user//account_data/: #put-matrix-client-%CLIENT_MAJOR_VERSION%-user-userid-account-data-type diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index d148b945..26c5d85a 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -39,10 +39,9 @@ Client behaviour The invitee's client may use the ``is_direct`` flag in `m.room.member`_ 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. To do this, it -stores this event in account data using the ``account_data`` API: see `Client -Config`_. +stores this event in account data using the |/user//account_data/|_ API. -The inviter's client should set the ``is_direct`` flag to .. |/createRoom|_ +The inviter's client should set the ``is_direct`` flag to |/createRoom|_ 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 @@ -50,6 +49,6 @@ person's profile picture would imply the ``is_direct`` flag should be set. Server behaviour ---------------- -When the ``is_direct`` flag is given to .. |/createRoom|_, the home +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. From 96b6fb0129131e7adf6bc0c0c9c0dc57f91d7f2e Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 6 Oct 2016 11:16:56 +0100 Subject: [PATCH 22/24] 'In the m.room.member' event --- specification/modules/dm.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index 26c5d85a..f46a01a5 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -36,10 +36,11 @@ Events Client behaviour ---------------- -The invitee's client may use the ``is_direct`` flag in `m.room.member`_ 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. To do this, it -stores this event in account data using the |/user//account_data/|_ API. +The invitee's client may use the ``is_direct`` flag in the `m.room.member`_ +event 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. To +do this, it stores this event in account data using the +|/user//account_data/|_ API. The inviter's client should set the ``is_direct`` flag to |/createRoom|_ whenever the flow the user has followed is one where their From ed2d3644409a091e0c034ba8da3ae15c6f0c249c Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 6 Oct 2016 11:17:43 +0100 Subject: [PATCH 23/24] consistency --- specification/modules/dm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index f46a01a5..8bba7411 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -52,4 +52,4 @@ 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. +invited in the |/createRoom|_ call. From 83b89aa1ceb0d07ba96c128f33a32d1799c24bd7 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 6 Oct 2016 17:17:35 +0100 Subject: [PATCH 24/24] dm: clarify client behaviour --- specification/modules/dm.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/specification/modules/dm.rst b/specification/modules/dm.rst index 8bba7411..a89d3522 100644 --- a/specification/modules/dm.rst +++ b/specification/modules/dm.rst @@ -36,18 +36,21 @@ Events Client behaviour ---------------- -The invitee's client may use the ``is_direct`` flag in the `m.room.member`_ -event 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. To -do this, it stores this event in account data using the -|/user//account_data/|_ API. - -The inviter's client should set the ``is_direct`` flag to |/createRoom|_ -whenever the flow the user has followed is one where their +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 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//account_data/|_. + Server behaviour ---------------- When the ``is_direct`` flag is given to |/createRoom|_, the home