Direct messages and group chats.

Every messaging call names the acting actor explicitly (the PAK lane has no end-user principal). The field name varies by operation — these are the names as they exist on the wire today:

• actor_id — the viewer/participant: open a conversation, list conversations, list messages, mark read, mute, leave.
• recipient_actor_id — the other side when opening a 1-on-1.
• sender_id — the author on send / edit / delete message.
• caller_actor_id — the acting admin on group member ops (add / remove / promote / rename).
• src_actor_id — the reactor on DM reactions.

All of them take the social actor.id UUID from stage 2.

Direct (default): idempotent on the pair — opening Alice ↔ Bob twice returns the same conversation, so "message this user" buttons don't need a lookup first. Group: pass kind: "group" with actor_ids (initial members, excluding the creator) and an optional name; every call creates a new group, and the creator becomes its admin. Size is capped by community.settings.max_group_conversation_size (default 50, see the settings reference). Opening against a blocked pair returns 409.

Bodies are 1–10 000 chars after trim. kind defaults to text; media kinds (image / video / audio) carry your CDN URLs on attachments, same bring-your-own-media model as posts. reply_to_id gives you inline threaded replies. Edits are sender-only and window-limited — 5 minutes after send, then 409. Deletes are sender-only soft-deletes: the row stays so replies don't orphan, and reads return body: "(deleted)" with deleted_at set. Sending into a conversation where a block now exists returns 409.

GET /messages is cursor-paginated newest-first — the right shape for rendering a thread from the bottom and paging history upward via next_cursor. For live updates, flip to the since polling pattern: pass since=<token> where the token encodes the newest message you've already rendered, and you get only newer messages back in ascending order — append them and update your token. The token is the base64url-encoded JSON { "created_at": "<msg.created_at>", "id": "<msg.id>" } of that last-seen message, built from fields you already have on the row. Messages from actors the viewer has a block with are filtered out of every read.

Polling every few seconds per open thread is the intended delivery mechanism today. Social's outbound webhooks don't yet emit DM events (the event catalog covers posts, comments, reactions, and follows) — when a dm.message.created event ships, it will replace the tight polling loop and since becomes the catch-up call after a webhook wakes you.

Each participant row carries last_read_at. POST /read advances it — omit read_through to mark everything up to now, or pass a timestamp to mark partially (messages with created_at <= read_through count as read). The global badge comes from GET /conversations/unread-count?actor_id= — one { "count": n } across every conversation the actor participates in, counting only incoming (not own) messages newer than each thread's marker.

Same free-form type reactions as posts and comments, on individual messages. POST is idempotent on (actor, type); DELETE is idempotent and returns the updated counts either way. Each message carries a denormalised reaction_counts map, updated in lock-step. Recipients get a dm_reaction notification.

The conversation list supports the Instagram-style "message requests" split, driven by restrict edges: ?status=inbox (default) hides conversations whose other participant the viewer has restricted; ?status=requests shows only those; ?status=all merges both. Conversations sort by most recent activity (last_message_at), cursor-paginated.

Per-thread mute lives on the caller's participant row: PATCH /conversations/:id with { "actor_id": "<alice>", "muted": true } suppresses dm_new_message notifications for that thread without leaving it. Leaving is DELETE /conversations/:id with the actor's id in the body — the conversation itself is hard-deleted when the last participant leaves.

Groups have member and admin roles (the creator starts as admin). Admin-only, all under the conversation:

• Add a member — POST /members with caller_actor_id + actor_id (+ optional role). Refused with 409 if the new member has a block with any existing participant, is already a member, or the group is full.
• Promote / demote — PATCH /members/:actorId with a role. Demoting the last admin is a 409.
• Remove — DELETE /members/:actorId. Members may remove themselves (self-leave); removing the last admin of a non-empty group is a 409.
• Rename — PATCH /name (null/empty clears the name). 409 on a direct conversation.

Members get dm_added_to_group and dm_role_changed notifications for the relevant transitions — see stage 8.

Workspace moderators can review DM content without being participants — the admin lane exposes GET /v1/workspaces/:ws/communities/:c/moderation/conversations (every conversation, most-recent-activity first) and .../conversations/:id/messages (every message, including soft-deleted rows' metadata). Requires the social.audit.read permission; auth is the admin lane's usual PAK bearer / PlatformUser bearer / session cookie. The lane is read-only today — moderator take-downs of individual messages aren't shipped yet; actor-level tools (suspension, shadow bans, blocks) are the enforcement levers.

Open → send → poll with since → mark read → badge from unread-count: that's a complete DM product. With messaging done you've now walked every primitive the tutorial covers — head back to the index or dig into the single-feature guides.