| read_when |
|
|---|
DMs are workspace-scoped multi-party conversations. They reuse the messages
table — every DM message sets direct_conversation_id and leaves
channel_id null.
GET /api/dms?workspace_id= # caller's conversations in a workspace
POST /api/dms # { workspace_id, member_ids }
GET /api/dms/{conversation_id} # direct access, including closed DMs
DELETE /api/dms/{conversation_id} # close for the current human user
POST /api/dms/{conversation_id}/open # reopen for the current human user
GET /api/dms/{conversation_id}/messages?after_seq=&limit=
POST /api/dms/{conversation_id}/messages # { body, quoted_message_id?, nonce? }
POST /api/dms/{conversation_id}/read # { seq }Conversations include their members hydrated from users and a can_send
flag. The flag is false when every other member has been deleted or removed
from the workspace. Root messages and thread replies return 409 Conflict
while the conversation has no active recipient. The member_ids list on
create is deduplicated and the caller is added automatically.
The web sidebar lists existing DMs and also derives a People section from DM
members and hydrated message authors. Users appear there automatically as
conversation context is loaded; clicking a person opens their DM when one
exists with exactly that person and the current user, otherwise it opens the
profile pane with a Message action. Groups containing the person do not match.
Explicit Message and Start DM actions use the server to create or reopen that
exact one-to-one conversation. Failed starts show an error and retain the
selected recipient ID for retry. The Start DM form searches the full workspace
member directory, including people who have not posted or joined a DM. Opening
it refreshes the directory so newly joined members can be found without reloading.
It resolves an unambiguous name or handle match, asks you to select a result when
multiple people match, and also accepts an explicit usr_... user ID.
Closing the dialog or changing the current view prevents
a late response from taking over navigation. Self-DMs remain unsupported and
show the server's validation error.
Closing a DM only hides it from the current user's sidebar. Membership, history, routes, and read state remain intact for every member. Direct links still resolve. Reopening the same one-to-one member set, using the explicit open endpoint, or receiving a new root message makes the conversation visible again. The web sidebar exposes Close and an eight-second Undo action. Bot tokens cannot close or reopen a human user's sidebar state.
POST to /dms/{id}/messages increments a per-conversation sequence on
messages.channel_seq and emits a durable private event into the workspace
event stream so DM lists and unread counts stay live for conversation members.
nonce has the same retry-safe idempotency behavior as channel message
creation.
POST /dms/{id}/read updates the caller's monotonic read pointer for that
conversation and emits a private dm.read event only to the caller's own
sessions.
- Listing conversations requires workspace membership.
- Sending a DM requires membership in the conversation
(
direct_conversation_members). - DM creation requires that all
member_idsare members of the same workspace. - Editing, deleting, reacting to, attaching uploads to, or opening threads on a DM message requires direct conversation membership. Edits and deletes are author-only.
DM root messages support the same one-level thread model as channel messages.
Thread replies carry direct_conversation_id, use thread_seq, and do not
appear in the root DM timeline or unread root-message sequence.
Search supports one direct conversation through
direct_conversation_id. The caller must be a conversation member; workspace
and channel searches continue to exclude direct messages.
- DM-only auth tokens.
- One-on-one vs group distinctions in the API surface — the client decides based on member count.