clickclack/docs/features/dms.md

read_when
changing direct message conversations or DM listing

Direct Messages

DMs are workspace-scoped multi-party conversations. They reuse the messages table — every DM message sets direct_conversation_id and leaves channel_id null.

Endpoints

GET  /api/dms?workspace_id=                              # caller's conversations in a workspace
POST /api/dms                                            # { workspace_id, member_ids }
GET  /api/dms/{conversation_id}/messages?after_seq=&limit=
POST /api/dms/{conversation_id}/messages                 # { body }

Conversations include their members hydrated from users. 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, otherwise it opens the profile pane with a Message action.

POST to /dms/{id}/messages increments a per-conversation sequence on messages.channel_seq and emits a durable event into the workspace event stream so DM lists and unread counts stay live.

Membership

• Listing conversations requires workspace membership.
• Sending a DM requires membership in the conversation (direct_conversation_members).
• DM creation requires that all member_ids are members of the same workspace.

What is intentionally missing

• DM-only auth tokens.
• One-on-one vs group distinctions in the API surface — the client decides based on member count.
• Message reactions/edits in DMs. The schema supports it, but the API surface for DM-specific mutations is intentionally minimal in V1.