Direct Messages

Direct messages (DMs) are private conversations between two users, independent of guilds.

List DM Threads

GET /api/v1/dms

Returns all DM threads the authenticated user participates in. Includes the other user’s info and online status.

Headers: Authorization: Bearer <token>

Response 200 OK:

[
  {
    "id": 1,
    "other_user_id": 2,
    "other_username": "bob",
    "other_avatar_url": "https://cdn.example.com/bob.png",
    "other_user_online": true
  }
]

Create DM Thread

POST /api/v1/dms

Start a new DM thread with another user. If a thread already exists, it is returned instead.

Headers: Authorization: Bearer <token>

Request body:

{
  "recipient_user_id": 2
}

Response 201 Created: Returns the DM thread object.

Get DM Messages

GET /api/v1/dms/:id/messages

Fetch messages from a DM thread. Uses cursor-based pagination.

Headers: Authorization: Bearer <token>

Query parameters:

Parameter	Description
limit	Number of messages to return, default 50, max 100 (optional)
before	Message ID — returns messages older than this (optional)

Response 200 OK:

[
  {
    "id": 50,
    "direct_thread_id": 1,
    "author_id": 1,
    "content": "Hey Bob!",
    "created_at": "2026-01-15T12:00:00Z"
  }
]

Send DM Message

POST /api/v1/dms/:id/messages

Send a message in a DM thread. The user must be a participant of the thread.

Headers: Authorization: Bearer <token>

Request body:

{
  "content": "Hey Bob!"
}

Response 201 Created: Returns the created message object.

A DIRECT_MESSAGE_CREATE event is broadcast to all WebSocket clients of the thread participants.