diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 9107e185..a321b0f7 100644 --- a/api/client-server/create_room.yaml +++ b/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. diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 60d2de17..465565e1 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -25,6 +25,9 @@ - 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 'Direct Messaging' module. + (`#389 `_). - Add ``contains_url`` option to ``RoomEventFilter``. (`#390 `_). - Add ``filter`` optional query param to ``/messages`` 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..b8a9cfc2 --- /dev/null +++ b/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 diff --git a/event-schemas/schema/m.room.member b/event-schemas/schema/m.room.member index f9aa5051..4f4077a7 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 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: diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 6217b9fc..e12f6f40 100644 --- a/specification/client_server_api.rst +++ b/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//initialSync| replace:: ``/rooms//initialSync`` .. _/rooms//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//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 new file mode 100644 index 00000000..a89d3522 --- /dev/null +++ b/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//account_data/|_. + +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. diff --git a/specification/targets.yaml b/specification/targets.yaml index 129cfe11..a157366f 100644 --- a/specification/targets.yaml +++ b/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: ["=", "-", "~", "+", "^", "`", "@", ":"]