Skip to content

List your conversations

GET
/account/messages

Returns your direct message conversations, one per person, each with its latest message and how many messages from that person you haven’t marked read, most recent conversation first.

You need to be signed in; no capability is needed. Without a session cookie or bearer token that identifies you, the answer is 401, whether or not public mode is on. A limit that isn’t a whole number gets a plain-text 400 before sign-in is checked. Only conversations you are part of are returned.

There is no paging. You get at most limit conversations, 50 unless you ask for another number; values below 1 count as 1 and above 200 as 200. With no cursor and no total, older conversations past the limit can’t be listed. Conversations whose latest messages were saved at the same moment come in no fixed order. With no messages, the list is empty.

Each conversation shows the other person’s username and the name and picture stored on their profile, without the fallbacks UserPublic applies, and the full text of the latest message. Blocks and account status don’t hide a conversation. A conversation with someone whose account has been removed is left out, although its unread messages still count in getMyUnreadDirectMessageCount. Reading this list doesn’t mark anything read, and it is read fresh each time. Server errors get a plain-text 500.

limit
integer
default: 50 >= 1 <= 200

How many conversations to return, 50 if left out. Values below 1 count as 1 and above 200 as 200, and there’s no way to ask for the ones after them.

Your conversations, most recent first, at most limit of them.

object
threads
required

Up to limit conversations, most recent first; empty when there are none.

Array<object>

One conversation in your inbox: the other person, the latest message and how many of their messages you haven’t marked read.

object
peer_user_ref
required

The other person’s account ref.

integer format: int64
peer_username
required

Their username; an empty string if they have none.

string
peer_display_name

The display name stored on their profile, with no fallback to the full name or username. Left out when unset, and an empty string when stored empty.

string
nullable
peer_avatar_url

The stored picture address from their profile; the server doesn’t fetch or check it. Left out when unset, and an empty string when it was cleared.

string
nullable
last_message_id
required

The latest message’s id.

string format: uuid
last_sender_user_ref
required

Who sent the latest message: your ref or the other person’s.

integer format: int64
last_body
required

The full text of the latest message.

string
last_sent_at
required

When the latest message was saved.

string format: date-time
last_read_at

When the recipient of the latest message marked it read, whichever of you that was. Left out while it is unread.

string format: date-time
nullable
unread_count
required

How many messages from this person you haven’t marked read, in the whole conversation. Adding these up across your inbox can give less than getMyUnreadDirectMessageCount, which also counts conversations past the inbox limit and ones with removed accounts, and is read separately.

integer format: int64

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}