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