Skip to content

Send a direct message

POST
/account/messages/{peer_ref}

Sends a direct message to the account peer_ref and returns it as saved.

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 that isn’t a whole number gets a plain-text 400 before sign-in is checked, and so does a body that can’t be decoded: an empty one, one that isn’t valid JSON, a JSON value other than an object or null, or a body that is neither text nor null. Only the first JSON value is read, and other keys are ignored. After sign-in, a body that is blank, missing or null, including a whole body of null or {}, gets 400, then messaging yourself gets 400, a peer_ref with no account gets 404, and if either of you has blocked the other the answer is 403.

Surrounding white space is removed and the rest is saved exactly as sent, line breaks included; the server doesn’t format or clean it. Text that is blank after trimming is refused, but the maximum length shown isn’t checked. Sending the same text again creates another message, so retrying a request whose answer you didn’t get can send it twice.

The block check can use a cached answer and runs just before the message is saved, so a message sent at the same moment as a block, or on a server that hasn’t caught up with it, can still go through. A block doesn’t hide or delete earlier messages, and either of you can still read the conversation and mark it read.

The message and an activity log entry holding its full text are saved in one step. Administrators with system.activities.read or system.admin can read that log, so they can see the message text; the server stores the text as sent, without encrypting it end to end. Afterwards the server tries to give the person an in-app notification with the start of the message, if their settings for direct messages include in-app notifications and the same cached block check finds no block; if writing it fails, the message is still sent. The returned read_at is as it was when saved. Server errors get a plain-text 500.

peer_ref
required
integer format: int64

The other person’s account ref.

object
body
required

The message text. Surrounding white space is removed, and text that is blank after that gets 400; the maximum length shown isn’t checked.

string
>= 1 characters <= 5000 characters

The message as saved.

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

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

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

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed