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