REST: Direct messages

Generated from mnema-talk v3.3.13 (cca4f0fdb723).

List direct messages

GET /api/dms

The caller's direct message conversations, the most recently active first (at most 500), with members, unread and mention counts. Conversations are not channels: they appear in no channel list. Messages are read and written under the conversation's id in the message routes, which only members can use. Moderators cannot list or open anybody else's conversations. Needs the direct_messages feature (GET /api/health).

Authentication: Session cookie

Responses

StatusMeaningBody
200The caller's conversations.DirectMessage[]
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Start a direct message

POST /api/dms

With one other member: that conversation, started now (201) or the existing one (200). With two to nine: a new group (201). Needs Send direct messages and the community's direct messages on. Every refusal about the other members (a block in either direction, their direct message setting, a disabled account, a bot, an unknown id) is the same 403, so none can be probed. At most 10 new conversations per member per 24 hours and 3 tries per minute, and 100 group conversations per member. The first messages are capped (see doc/architecture.md). Sends dm_created to all members' sessions.

Authentication: Session cookie

Request body (application/json, required): CreateDMRequest

FieldTypeDescription
user_ids (required)string (uuid)[]UserIDs are the other members: one for a conversation with one person, two to nine for a group.

Responses

StatusMeaningBody
200The existing conversation with that member.DirectMessage
201The new conversation.DirectMessage
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: the conversation cannot be started (always the same text).ErrorResponse
409CONFLICT: the caller is in 100 group conversations.ErrorResponse
429RATE_LIMITED: too many requests, or 10 conversations started in 24 hours.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
DirectMessage
FieldTypeDescription
callDMCallCall is the call going on in the conversation (absent: none). It rings for the members who have not joined while Ringing is true. Events dm_call_ring and dm_call_end keep it current.
can_send (required)booleanCanSend says whether the caller may write in it now: they hold Send direct messages, the community has direct messages on, and no timeout or pending rules apply. It says nothing about the other members; a message that cannot be sent to them is refused when sent.
created_at (required)string (date-time)
favourite_position (required)integer | nullFavouritePosition is the conversation's place in the caller's favourites, 0 first (null: not a favourite).
group (required)booleanGroup is true for a conversation that can take more members; a conversation with one other person is not.
hidden (required)booleanHidden says the caller closed the conversation in their list; the next message written in it opens it again. It is the caller's view only.
id (required)string (uuid)ID is the id messages are read and written under, in the message routes (/api/channels/{id}/messages), which accept it for members only.
last_messageDMLastMessageLastMessage is the latest message the caller can see, for a preview (absent: none yet). Messages of members the caller blocked are left out.
last_message_at (required)string | nullLastMessageAt is when the latest message was written (null: none yet).
last_read_at (required)string | null
members (required)DMMember[]Members are everybody in it, the caller included.
mention_count (required)integer
notify_level (required)NotifyLevel
unread_count (required)integerUnreadCount counts top-level messages of others since the caller last read it; MentionCount those of them that mention the caller by name or reply to them.

Set the caller's favourite direct messages

PUT /api/dms/favourites

Replaces the caller's favourites (at most 25) with the given conversations in the given order, which also reopens any that were closed. Every id must be a conversation the caller is in; otherwise nothing changes and the answer is 404, the same as for a conversation that does not exist. Sends dm_prefs_updated to the caller's sessions.

Authentication: Session cookie

Request body (application/json, required): SetDMFavouritesRequest

FieldTypeDescription
ids (required)string (uuid)[]IDs are the favourite conversations, first to last; every other conversation stops being one.

Responses

StatusMeaningBody
204Done.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Get a direct message

GET /api/dms/{id}

One conversation of the caller. Anyone who is not in it, the Owner included, gets 404.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesConversation ID.

Responses

StatusMeaningBody
200The conversation.DirectMessage
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
DirectMessage
FieldTypeDescription
callDMCallCall is the call going on in the conversation (absent: none). It rings for the members who have not joined while Ringing is true. Events dm_call_ring and dm_call_end keep it current.
can_send (required)booleanCanSend says whether the caller may write in it now: they hold Send direct messages, the community has direct messages on, and no timeout or pending rules apply. It says nothing about the other members; a message that cannot be sent to them is refused when sent.
created_at (required)string (date-time)
favourite_position (required)integer | nullFavouritePosition is the conversation's place in the caller's favourites, 0 first (null: not a favourite).
group (required)booleanGroup is true for a conversation that can take more members; a conversation with one other person is not.
hidden (required)booleanHidden says the caller closed the conversation in their list; the next message written in it opens it again. It is the caller's view only.
id (required)string (uuid)ID is the id messages are read and written under, in the message routes (/api/channels/{id}/messages), which accept it for members only.
last_messageDMLastMessageLastMessage is the latest message the caller can see, for a preview (absent: none yet). Messages of members the caller blocked are left out.
last_message_at (required)string | nullLastMessageAt is when the latest message was written (null: none yet).
last_read_at (required)string | null
members (required)DMMember[]Members are everybody in it, the caller included.
mention_count (required)integer
notify_level (required)NotifyLevel
unread_count (required)integerUnreadCount counts top-level messages of others since the caller last read it; MentionCount those of them that mention the caller by name or reply to them.

Close or reopen a direct message in the caller's list

PUT /api/dms/{id}/hidden

Hides the conversation from the caller's list, or shows it again. Nothing is deleted and nobody else is told; the next message written in it shows it again. A favourite cannot be closed (409). Anyone who is not in the conversation gets 404. Sends dm_prefs_updated to the caller's other sessions.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesConversation ID.

Request body (application/json, required): SetDMHiddenRequest

FieldTypeDescription
hidden (required)boolean

Responses

StatusMeaningBody
204Done.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
409CONFLICT: the conversation is a favourite.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Add a member to a group direct message

POST /api/dms/{id}/members

Only group conversations take members, up to 10 in all, and only a member of it can add. The new member can read the whole conversation. The same single 403 as for starting a conversation covers a block in either direction between the adder and the new member, their direct message setting, a disabled account and a bot. Sends dm_created to the new member and dm_member_added to the others.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesConversation ID.

Request body (application/json, required): AddDMMemberRequest

FieldTypeDescription
user_id (required)string (uuid)

Responses

StatusMeaningBody
200The conversation, with the new member.DirectMessage
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: the member cannot be added (always the same text).ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
409CONFLICT: the group is full.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
DirectMessage
FieldTypeDescription
callDMCallCall is the call going on in the conversation (absent: none). It rings for the members who have not joined while Ringing is true. Events dm_call_ring and dm_call_end keep it current.
can_send (required)booleanCanSend says whether the caller may write in it now: they hold Send direct messages, the community has direct messages on, and no timeout or pending rules apply. It says nothing about the other members; a message that cannot be sent to them is refused when sent.
created_at (required)string (date-time)
favourite_position (required)integer | nullFavouritePosition is the conversation's place in the caller's favourites, 0 first (null: not a favourite).
group (required)booleanGroup is true for a conversation that can take more members; a conversation with one other person is not.
hidden (required)booleanHidden says the caller closed the conversation in their list; the next message written in it opens it again. It is the caller's view only.
id (required)string (uuid)ID is the id messages are read and written under, in the message routes (/api/channels/{id}/messages), which accept it for members only.
last_messageDMLastMessageLastMessage is the latest message the caller can see, for a preview (absent: none yet). Messages of members the caller blocked are left out.
last_message_at (required)string | nullLastMessageAt is when the latest message was written (null: none yet).
last_read_at (required)string | null
members (required)DMMember[]Members are everybody in it, the caller included.
mention_count (required)integer
notify_level (required)NotifyLevel
unread_count (required)integerUnreadCount counts top-level messages of others since the caller last read it; MentionCount those of them that mention the caller by name or reply to them.

Leave a group direct message

DELETE /api/dms/{id}/members/{user}

Takes the caller out of a group conversation; they lose its history and their seat in its Talk (voice_kicked reason missing_permission, and a voice_state_update leave to the others in the call). When nobody is left the conversation and its messages and attachments are deleted. A conversation with one other person cannot be left (400): block the person instead. Sends dm_member_removed to the remaining members and the leaver's sessions.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesConversation ID.
userpathstringyesMust be the literal @me (or the caller's own id): members can only remove themselves.

Responses

StatusMeaningBody
204Left.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Read the direct message settings

GET /api/users/me/dm-settings

The caller's settings for their conversations as a whole: mute all, and whether the sidebar section is folded. Who may start a conversation is in GET /api/users/me/privacy.

Authentication: Session cookie

Responses

StatusMeaningBody
200The settings.DMSettings
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
DMSettings
FieldTypeDescription
list_collapsed (required)booleanListCollapsed is whether the member folded the sidebar section.
mute_all (required)booleanMuteAll silences every conversation: no push, no sound, no highlight. Unread counts stay. A conversation's own notification setting overrides it.

Set the direct message settings

PUT /api/users/me/dm-settings

Stores both settings. With mute_all on, conversations send no push, play no sound and highlight nothing, but unread still counts; a conversation's own notification setting (PUT /api/channels/{id}/notifications) overrides it. Sends dm_prefs_updated (no conversation) to the caller's sessions.

Authentication: Session cookie

Request body (application/json, required): DMSettings

FieldTypeDescription
list_collapsed (required)booleanListCollapsed is whether the member folded the sidebar section.
mute_all (required)booleanMuteAll silences every conversation: no push, no sound, no highlight. Unread counts stay. A conversation's own notification setting overrides it.

Responses

StatusMeaningBody
200The settings.DMSettings
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
DMSettings
FieldTypeDescription
list_collapsed (required)booleanListCollapsed is whether the member folded the sidebar section.
mute_all (required)booleanMuteAll silences every conversation: no push, no sound, no highlight. Unread counts stay. A conversation's own notification setting overrides it.

Something wrong on this page? Tell us.