matrix-spec-proposals/content/client-server-api/modules/dm.md

type
module

Direct Messaging

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

{{% event event="m.direct" %}}

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.