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
| Status | Meaning | Body |
|---|---|---|
| 200 | The caller's conversations. | DirectMessage[] |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Field | Type | Description |
|---|---|---|
user_ids (required) | string (uuid)[] | UserIDs are the other members: one for a conversation with one person, two to nine for a group. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The existing conversation with that member. | DirectMessage |
| 201 | The new conversation. | DirectMessage |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: the conversation cannot be started (always the same text). | ErrorResponse |
| 409 | CONFLICT: the caller is in 100 group conversations. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests, or 10 conversations started in 24 hours. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
DirectMessage
| Field | Type | Description |
|---|---|---|
call | DMCall | Call 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) | boolean | CanSend 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 | null | FavouritePosition is the conversation's place in the caller's favourites, 0 first (null: not a favourite). |
group (required) | boolean | Group is true for a conversation that can take more members; a conversation with one other person is not. |
hidden (required) | boolean | Hidden 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_message | DMLastMessage | LastMessage 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 | null | LastMessageAt 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) | integer | UnreadCount 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
| Field | Type | Description |
|---|---|---|
ids (required) | string (uuid)[] | IDs are the favourite conversations, first to last; every other conversation stops being one. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Done. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Conversation ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The conversation. | DirectMessage |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
DirectMessage
| Field | Type | Description |
|---|---|---|
call | DMCall | Call 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) | boolean | CanSend 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 | null | FavouritePosition is the conversation's place in the caller's favourites, 0 first (null: not a favourite). |
group (required) | boolean | Group is true for a conversation that can take more members; a conversation with one other person is not. |
hidden (required) | boolean | Hidden 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_message | DMLastMessage | LastMessage 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 | null | LastMessageAt 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) | integer | UnreadCount 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Conversation ID. |
Request body (application/json, required): SetDMHiddenRequest
| Field | Type | Description |
|---|---|---|
hidden (required) | boolean |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Done. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 409 | CONFLICT: the conversation is a favourite. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Conversation ID. |
Request body (application/json, required): AddDMMemberRequest
| Field | Type | Description |
|---|---|---|
user_id (required) | string (uuid) |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The conversation, with the new member. | DirectMessage |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: the member cannot be added (always the same text). | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 409 | CONFLICT: the group is full. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
DirectMessage
| Field | Type | Description |
|---|---|---|
call | DMCall | Call 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) | boolean | CanSend 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 | null | FavouritePosition is the conversation's place in the caller's favourites, 0 first (null: not a favourite). |
group (required) | boolean | Group is true for a conversation that can take more members; a conversation with one other person is not. |
hidden (required) | boolean | Hidden 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_message | DMLastMessage | LastMessage 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 | null | LastMessageAt 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) | integer | UnreadCount 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Conversation ID. |
user | path | string | yes | Must be the literal @me (or the caller's own id): members can only remove themselves. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Left. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Status | Meaning | Body |
|---|---|---|
| 200 | The settings. | DMSettings |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
DMSettings
| Field | Type | Description |
|---|---|---|
list_collapsed (required) | boolean | ListCollapsed is whether the member folded the sidebar section. |
mute_all (required) | boolean | MuteAll 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
| Field | Type | Description |
|---|---|---|
list_collapsed (required) | boolean | ListCollapsed is whether the member folded the sidebar section. |
mute_all (required) | boolean | MuteAll silences every conversation: no push, no sound, no highlight. Unread counts stay. A conversation's own notification setting overrides it. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The settings. | DMSettings |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
DMSettings
| Field | Type | Description |
|---|---|---|
list_collapsed (required) | boolean | ListCollapsed is whether the member folded the sidebar section. |
mute_all (required) | boolean | MuteAll silences every conversation: no push, no sound, no highlight. Unread counts stay. A conversation's own notification setting overrides it. |