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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The other person’s account ref.
Request Body required
Section titled “Request Body required ”object
The message text. Surrounding white space is removed, and text that is blank after that gets 400; the maximum length shown isn’t checked.
Responses
Section titled “ Responses ”The message as saved.
A direct message between two accounts.
object
The message’s id.
The account that sent it.
The account it was sent to.
The text as saved, with surrounding white space removed.
When the server saved it.
When the recipient marked the conversation read, which both people can see. Left out while unread.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completed