Skip to content

List the messages with a user

GET
/account/messages/{peer_ref}

Returns the direct messages between you and the account peer_ref, in both directions, newest first, one page at a time.

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 peer_ref or limit that isn’t a whole number gets a plain-text 400 before sign-in is checked. A peer_ref with no account gets 404, even if messages with it are still stored. For your own peer_ref the answer is 200 with items set to null; a valid limit doesn’t change it and cursor is ignored. You can only read conversations you are part of, and blocks and account status don’t stop you.

Pages hold at most limit messages, 50 unless you ask for another number; values below 1 count as 1 and above 200 as 200. When older messages remain, next_cursor is set: send it back as cursor to get the messages before the last one on the page. A cursor that can’t be read gets 401. Messages saved at the same moment come in a fixed order by id. Each page is read separately, so a message sent or marked read between two requests can make them disagree, and a message can appear later with an earlier time than ones already shown.

Reading messages doesn’t mark them read; markDirectMessageThreadRead does. Each message’s read_at is when its recipient marked the conversation read, and both of you can see it. Server errors get a plain-text 500.

peer_ref
required
integer format: int64

The other person’s account ref.

limit
integer
default: 50 >= 1 <= 200

How many messages per page, 50 if left out; values below 1 count as 1 and above 200 as 200.

cursor
string

The next_cursor from the previous page, to get older messages. Left out or empty, the page starts from the newest; one that can’t be read gets 401.

A page of messages, newest first.

object
items
required

Up to limit messages, newest first; empty when there are none, and null for your own peer_ref.

Array<object>

A direct message between two accounts.

object
id
required

The message’s id.

string format: uuid
sender_user_ref
required

The account that sent it.

integer format: int64
recipient_user_ref
required

The account it was sent to.

integer format: int64
body
required

The text as saved, with surrounding white space removed.

string
sent_at
required

When the server saved it.

string format: date-time
read_at

When the recipient marked the conversation read, which both people can see. Left out while unread.

string format: date-time
nullable
next_cursor

Send this back as cursor for the older messages. Left out when there are no more.

string
nullable

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"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed