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