REST: Messages

Messages, threads, reactions and search. Generated from mnema-talk v3.3.13 (cca4f0fdb723).

List channel messages

GET /api/channels/{channelID}/messages

Top-level messages only, oldest first within the page. Without an anchor returns the newest page. Use at most one of before, after, around; the anchor must be a root message of this channel.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
limitqueryintegernoPage size. Values below 1 or non-numeric fall back to the default; larger values are clamped to 100.
beforequerystring (uuid)noMessages older than this message.
afterquerystring (uuid)noMessages newer than this message.
aroundquerystring (uuid)noMessages around (and including) this message.

Responses

StatusMeaningBody
200A page of messages.Message[]
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Post a message

POST /api/channels/{channelID}/messages

Works in text and voice channels (a voice channel's chat). Resolves mentions and broadcasts message_create. With attachment_ids the message carries those staged files (up to 10, at most 100 MB together); the text may then be empty. With lifetime_seconds the server deletes the message (as its author's delete would) that long after storing it; the message carries expires_at. A lifetime is refused (400) when lifetimes are off, beyond the community's ceiling, and for the root of a forum post.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (application/json, required): CreateMessageRequest

FieldTypeDescription
attachment_idsstring (uuid)[]AttachmentIDs are files uploaded with POST /api/channels/{channelID}/attachments, at most 10, shown in this order. Needs the Attach files permission; the files must be the caller's, from this channel and not yet sent.
content (required)stringContent is required unless attachment_ids is set.
lifetime_secondsintegerLifetimeSeconds makes the server delete the message that long after it is stored: 60 to 2592000 and at most the community's ceiling (GET /api/message-settings). Fixed at sending. Needs the messages.lifetime feature (doc/timed-messages.md).
noncestring (uuid)Nonce is an optional random id the client makes per send. Sending the same nonce again (a retry after a lost connection) returns the first message with 200 instead of posting a second one.
parent_idstring | nullParentID must be a root message of the same channel (thread reply).
reply_to_idstring | nullReplyToID must be a message of the same conversation (quoted reply).

Responses

StatusMeaningBody
200The message already created with this nonce (a retried send).Message
201Created message.Message
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation, or the nonce was already used by this member in another conversation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Send messages permission in the channel, or cross-origin request rejected. RULES_NOT_ACCEPTED: the member has not accepted the community rules yet.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
410MESSAGE_DELETED: the message sent with this nonce was deleted since; it is not posted again.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them.
content (required)string
created_at (required)string (date-time)
direct_mentionsstring (uuid)[]DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list.
display_name (required)string
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (date-time)ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock.
forwardForwardRefForward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward.
id (required)string (uuid)
is_botbooleanIsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message.
is_edited (required)boolean
is_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (uuid)[]MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves.
mentions (required)string (uuid)[]Mentions are the users this message mentions (@username, @all, @here).
noncestring (uuid)Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does.
number (required)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (date-time)PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone).
pinned_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle is the required title of a root post in a forum channel (max 100 characters).
updated_at (required)string (date-time)
user_id (required)string (uuid)
username (required)string

Delete a member's latest messages in a channel

POST /api/channels/{channelID}/messages/bulk-delete

Deletes up to 100 of the member's latest messages in the channel, their thread replies and attachments included, in one step. Needs the Manage messages permission in the channel and a higher role than the member; the Owner's messages can only go by the Owner's hand. Every message gets its own audit entry with its text, plus one summary entry. The member is told through a moderation_notice event. Broadcasts message_delete per message.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (application/json, required): BulkDeleteRequest

FieldTypeDescription
count (required)integerCount is how many of their latest messages (replies included), 1 to 100.
reasonstringReason is kept in the audit log. Optional.
user_id (required)string (uuid)UserID is the member whose latest messages in the channel go.

Responses

StatusMeaningBody
200How many messages went.BulkDeleteResult
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage messages permission in the channel, or the member's highest role is not below yours, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
BulkDeleteResult
FieldTypeDescription
deleted (required)integer

Delete a message

DELETE /api/channels/{channelID}/messages/{messageID}

The author, or a member with the Manage messages permission in the channel (the Owner always). Also deletes the message's thread replies and attachments. A moderator may send a JSON body {"reason": "..."} (up to 200 characters); the reason goes to the audit log and to the author, who is told through a moderation_notice event. Broadcasts message_delete.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesMessage ID.

Request body (application/json): DeleteMessageRequest

FieldTypeDescription
reasonstringReason is shown to the author when a moderator deletes their message, and kept in the audit log. Up to 200 characters.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: you are neither the author nor hold Manage messages in the channel, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Edit own message

PUT /api/channels/{channelID}/messages/{messageID}

Only the author may edit. The content may be empty when the message has an attachment. Broadcasts message_update.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesMessage ID.

Request body (application/json, required): EditMessageRequest

FieldTypeDescription
content (required)string

Responses

StatusMeaningBody
200Updated message.Message
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: you are not the author, the message is in a direct message conversation of two, or the chat of its Talk, that cannot be written in any more (a block, or the other account disabled; the same answer as a refused new message), or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them.
content (required)string
created_at (required)string (date-time)
direct_mentionsstring (uuid)[]DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list.
display_name (required)string
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (date-time)ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock.
forwardForwardRefForward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward.
id (required)string (uuid)
is_botbooleanIsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message.
is_edited (required)boolean
is_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (uuid)[]MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves.
mentions (required)string (uuid)[]Mentions are the users this message mentions (@username, @all, @here).
noncestring (uuid)Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does.
number (required)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (date-time)PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone).
pinned_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle is the required title of a root post in a forum channel (max 100 characters).
updated_at (required)string (date-time)
user_id (required)string (uuid)
username (required)string

Edit history of a message

GET /api/channels/{channelID}/messages/{messageID}/edits

The earlier versions of an edited message, newest first (at most 50). Needs the Manage messages permission in the channel (the Owner always); the author and other members cannot read it. Not searched and not part of any export except the author's own. Rate limited per member. A read of another member's message is recorded in the audit log (message.edit_history_view), once per reader and message every ten minutes. An unedited message has an empty list.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesMessage ID.

Responses

StatusMeaningBody
200Earlier versions, newest first.MessageEditHistory
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage messages permission in the channel.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
MessageEditHistory
FieldTypeDescription
edits (required)MessageEdit[]

Unpin a message

DELETE /api/channels/{channelID}/messages/{messageID}/pin

Needs the Manage messages permission in the channel (the Owner always). Unpinning a message that is not pinned changes nothing. Broadcasts message_update and pins_changed.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesMessage ID.

Responses

StatusMeaningBody
200The message.Message
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage messages permission in the channel, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them.
content (required)string
created_at (required)string (date-time)
direct_mentionsstring (uuid)[]DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list.
display_name (required)string
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (date-time)ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock.
forwardForwardRefForward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward.
id (required)string (uuid)
is_botbooleanIsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message.
is_edited (required)boolean
is_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (uuid)[]MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves.
mentions (required)string (uuid)[]Mentions are the users this message mentions (@username, @all, @here).
noncestring (uuid)Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does.
number (required)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (date-time)PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone).
pinned_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle is the required title of a root post in a forum channel (max 100 characters).
updated_at (required)string (date-time)
user_id (required)string (uuid)
username (required)string

Pin a message

PUT /api/channels/{channelID}/messages/{messageID}/pin

Needs the Manage messages permission in the channel (the Owner always). A channel keeps at most 50 pinned messages (409 beyond). Pinning a pinned message changes nothing. Broadcasts message_update and pins_changed.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesMessage ID.

Responses

StatusMeaningBody
200The message.Message
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation, or the message has a lifetime (it cannot be pinned).ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage messages permission in the channel, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
409CONFLICT: the channel already has 50 pinned messages.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them.
content (required)string
created_at (required)string (date-time)
direct_mentionsstring (uuid)[]DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list.
display_name (required)string
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (date-time)ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock.
forwardForwardRefForward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward.
id (required)string (uuid)
is_botbooleanIsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message.
is_edited (required)boolean
is_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (uuid)[]MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves.
mentions (required)string (uuid)[]Mentions are the users this message mentions (@username, @all, @here).
noncestring (uuid)Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does.
number (required)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (date-time)PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone).
pinned_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle is the required title of a root post in a forum channel (max 100 characters).
updated_at (required)string (date-time)
user_id (required)string (uuid)
username (required)string

List a channel's pinned messages

GET /api/channels/{channelID}/pins

The channel's pinned messages, the most recently pinned first (at most 50), each with pinned_at and pinned_by. Needs View channel. Deleting a message unpins it.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Responses

StatusMeaningBody
200The pinned messages.Message[]
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Create a forum post

POST /api/channels/{channelID}/posts

Creates a new post (thread root) with title, content and optional tags. Requires Send messages.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (application/json, required): CreatePostRequest

FieldTypeDescription
content (required)string
tag_idsstring[]
title (required)string

Responses

StatusMeaningBody
201Created post.Message
400INVALID_INPUTErrorResponse
401UNAUTHORIZEDErrorResponse
403FORBIDDENErrorResponse
404NOT_FOUNDErrorResponse
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them.
content (required)string
created_at (required)string (date-time)
direct_mentionsstring (uuid)[]DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list.
display_name (required)string
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (date-time)ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock.
forwardForwardRefForward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward.
id (required)string (uuid)
is_botbooleanIsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message.
is_edited (required)boolean
is_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (uuid)[]MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves.
mentions (required)string (uuid)[]Mentions are the users this message mentions (@username, @all, @here).
noncestring (uuid)Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does.
number (required)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (date-time)PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone).
pinned_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle is the required title of a root post in a forum channel (max 100 characters).
updated_at (required)string (date-time)
user_id (required)string (uuid)
username (required)string

Update a forum post

PATCH /api/channels/{channelID}/posts/{messageID}

Updates a post's title, tags, solved mark or lock status. The author or Manage messages for title, tags and the solved mark (not on a locked post, unless Manage messages); Manage messages for lock status and for applying or removing moderated tags. A forum that requires a tag refuses a post without one.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesMessage ID.

Request body (application/json, required): UpdatePostRequest

FieldTypeDescription
is_lockedboolean
is_resolvedbooleanIsResolved marks the post as solved (author or Manage messages) or reopens it.
tag_idsstring[]
titlestring

Responses

StatusMeaningBody
200Updated post.Message
400INVALID_INPUTErrorResponse
401UNAUTHORIZEDErrorResponse
403FORBIDDENErrorResponse
404NOT_FOUNDErrorResponse
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them.
content (required)string
created_at (required)string (date-time)
direct_mentionsstring (uuid)[]DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list.
display_name (required)string
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (date-time)ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock.
forwardForwardRefForward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward.
id (required)string (uuid)
is_botbooleanIsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message.
is_edited (required)boolean
is_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (uuid)[]MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves.
mentions (required)string (uuid)[]Mentions are the users this message mentions (@username, @all, @here).
noncestring (uuid)Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does.
number (required)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (date-time)PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone).
pinned_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle is the required title of a root post in a forum channel (max 100 characters).
updated_at (required)string (date-time)
user_id (required)string (uuid)
username (required)string

Schedule a message

POST /api/channels/{channelID}/scheduled

Stores a message that the server sends at send_at as the caller, through the normal send path: permissions, slow mode, timeouts, blocks and the direct message rules are checked again at send time, and a refusal turns it into a failed draft (scheduled_message_update with state failed). Needs Send messages in the channel now. Works in channels and conversations. Text only. send_at lies at least 10 seconds and at most a year ahead. lifetime_seconds gives the message a lifetime that starts when the server posts it; it is checked now and again at send time. At most 50 per member (409 beyond).

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel or conversation ID.

Request body (application/json, required): CreateScheduledRequest

FieldTypeDescription
content (required)string
lifetime_secondsintegerLifetimeSeconds is the lifetime the message gets when the server posts it (it starts then): 60 to 2592000, at most the community's ceiling. Fixed when scheduling. Needs the messages.lifetime feature.
parent_idstring | null
reply_to_idstring | null
send_at (required)string (date-time)SendAt is the absolute time to send at, worked out by the client in the member's own time zone.

Responses

StatusMeaningBody
201The scheduled message.Scheduled
400Invalid input (INVALID_INPUT): bad content, a time that is not in the future or too far ahead, an unknown reply target.ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: missing the Send messages permission in the channel. RULES_NOT_ACCEPTED: the member has not accepted the community rules yet.ErrorResponse
404NOT_FOUND: no such channel, or it is hidden from the caller.ErrorResponse
409CONFLICT: the member has 50 scheduled messages already.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Scheduled
FieldTypeDescription
channel_id (required)string (uuid)
channel_name (required)stringChannelName is empty for a conversation and for a channel the caller can no longer see.
content (required)string
created_at (required)string (date-time)
dm (required)boolean
failure_reason (required)stringFailureReason is set when State is failed: slow_mode, not_allowed, unavailable or refused.
id (required)string (uuid)
lifetime_secondsintegerLifetimeSeconds is the lifetime the message gets when it is posted; absent for none.
parent_id (required)string | null
reply_to_id (required)string | null
send_at (required)string (date-time)
state (required)stringState is "pending" (waiting for send_at) or "failed" (the server refused to send it; it stays as a draft the caller can edit, reschedule or delete).
updated_at (required)string (date-time)

List my reminders

GET /api/me/reminders

The caller's reminders: delivered ones first (they wait until dismissed), then waiting ones by time. Visibility is checked on every read: a message the caller can no longer see comes back with available=false and no message. At most 100 reminders.

Authentication: Session cookie

Responses

StatusMeaningBody
200The reminders.ReminderList
401No valid session (UNAUTHORIZED).ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
ReminderList
FieldTypeDescription
items (required)Reminder[]

Remind me of a message

POST /api/me/reminders

Stores a private reminder. At remind_at the caller gets an in-app notification (reminder_update with state due) and a Web Push; the message is checked against their access at that moment, and a message they can no longer see is described as such. The message must be visible to the caller now (404 otherwise). remind_at lies at least 10 seconds and at most a year ahead. At most 100 reminders per member (409 beyond); at most 60 changes a minute.

Authentication: Session cookie

Request body (application/json, required): CreateReminderRequest

FieldTypeDescription
message_id (required)string (uuid)
remind_at (required)string (date-time)RemindAt is the absolute time to remind at. The client works it out in the member's own time zone ("tomorrow", "in 3 hours").

Responses

StatusMeaningBody
201The reminder.Reminder
400Invalid input (INVALID_INPUT): malformed JSON, or a time that is not in the future or too far ahead.ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
404NOT_FOUND: no such message, or the channel is hidden from the caller.ErrorResponse
409CONFLICT: the member has 100 reminders already.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Reminder
FieldTypeDescription
available (required)booleanAvailable is false when the caller may no longer see the message (it was deleted, or they lost access); then Message is absent.
created_at (required)string (date-time)
delivered_at (required)string | nullDeliveredAt is set once the reminder fell due; it then waits in the list until the caller dismisses it.
id (required)string (uuid)
messageMessageRef
remind_at (required)string (date-time)

Cancel or dismiss a reminder

DELETE /api/me/reminders/{reminderID}

Cancels a waiting reminder or dismisses a delivered one. Sends reminder_update (removed) to the caller's own sessions.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
reminderIDpathstring (uuid)yesReminder ID.

Responses

StatusMeaningBody
204Removed.
400Invalid input (INVALID_INPUT): bad ID.ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
404NOT_FOUND: the caller has no such reminder.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

List saved messages

GET /api/me/saved

The caller's private saved list, newest first. Visibility is checked on every read: a message the caller can no longer see comes back with available=false and no message, only their own note. At most 1,000 messages can be saved.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
limitqueryintegernoPage size. Values below 1 or non-numeric fall back to the default; larger values are clamped to 100.
beforequerystring (uuid)noPage back: only entries older than this saved message.

Responses

StatusMeaningBody
200One page of the saved list.SavedPage
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the before cursor no longer exists (it was deleted since the previous page); reload the list.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
SavedPage
FieldTypeDescription
has_more (required)boolean
items (required)SavedMessage[]

Remove a saved message

DELETE /api/me/saved/{messageID}

Idempotent. Works for a message the caller can no longer see. Sends saved_updated to the caller's own sessions.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
messageIDpathstring (uuid)yesMessage ID.

Responses

StatusMeaningBody
204Removed (or was not saved).
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Save a message

PUT /api/me/saved/{messageID}

Adds the message to the caller's private saved list, or changes the note of a saved one (idempotent; a body without note keeps the note). Needs View channel for the message's channel; otherwise the message does not exist for the caller (404). At most 1,000 saved messages (409 beyond). Sends saved_updated to the caller's own sessions.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
messageIDpathstring (uuid)yesMessage ID.

Request body (application/json): SaveRequest

FieldTypeDescription
notestring | nullNote replaces the note; left out (or null), a saved message keeps its note and a new one starts without.

Responses

StatusMeaningBody
200The saved entry.SavedMessage
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
409CONFLICT: the saved list is full.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
SavedMessage
FieldTypeDescription
available (required)booleanAvailable is false when the caller may no longer see the message; then Message is absent and nothing but the id and the note is sent.
messageMessage
message_id (required)string (uuid)
note (required)stringNote is the caller's own note (up to 200 characters), possibly empty.
saved_at (required)string (date-time)

List my scheduled messages

GET /api/me/scheduled

The caller's scheduled messages in channels and conversations: failed ones first (the server refused to send them at the set time and kept them as drafts), then waiting ones by time. At most 50.

Authentication: Session cookie

Responses

StatusMeaningBody
200The scheduled messages.ScheduledList
401No valid session (UNAUTHORIZED).ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
ScheduledList
FieldTypeDescription
items (required)Scheduled[]

Delete a scheduled message

DELETE /api/me/scheduled/{scheduledID}

Removes a waiting or failed scheduled message.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
scheduledIDpathstring (uuid)yesScheduled message ID.

Responses

StatusMeaningBody
204Removed.
400Invalid input (INVALID_INPUT): bad ID.ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
404NOT_FOUND: the caller has no such scheduled message (it may have been sent).ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Edit a scheduled message

PATCH /api/me/scheduled/{scheduledID}

Changes the text and/or the time of a waiting or failed scheduled message. A new time puts a failed message back to waiting. Checks run at send time, not here.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
scheduledIDpathstring (uuid)yesScheduled message ID.

Request body (application/json, required): UpdateScheduledRequest

FieldTypeDescription
contentstring | null
send_atstring | nullSendAt moves the message; for a failed one it also puts it back to waiting.

Responses

StatusMeaningBody
200The scheduled message.Scheduled
400Invalid input (INVALID_INPUT): bad content or time.ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
404NOT_FOUND: the caller has no such scheduled message (it may have been sent).ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Scheduled
FieldTypeDescription
channel_id (required)string (uuid)
channel_name (required)stringChannelName is empty for a conversation and for a channel the caller can no longer see.
content (required)string
created_at (required)string (date-time)
dm (required)boolean
failure_reason (required)stringFailureReason is set when State is failed: slow_mode, not_allowed, unavailable or refused.
id (required)string (uuid)
lifetime_secondsintegerLifetimeSeconds is the lifetime the message gets when it is posted; absent for none.
parent_id (required)string | null
reply_to_id (required)string | null
send_at (required)string (date-time)
state (required)stringState is "pending" (waiting for send_at) or "failed" (the server refused to send it; it stays as a draft the caller can edit, reschedule or delete).
updated_at (required)string (date-time)

Mentions inbox

GET /api/mentions

Messages that mention the caller (by name, @all, @here or through a role) or reply to one of their messages, newest first. Only channels the caller may view are included; the caller's own messages never are.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
beforequerystring (uuid)noPage back: only messages older than this message.
limitqueryintegernoPage size. Values below 1 or non-numeric fall back to the default; larger values are clamped to 50.

Responses

StatusMeaningBody
200One page of mentions.MentionsPage
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the before cursor no longer exists (it was deleted since the previous page); reload the list.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
MentionsPage
FieldTypeDescription
has_more (required)boolean
messages (required)Message[]

Lifetime settings

GET /api/message-settings

Whether members may send messages with a lifetime and the longest one they may choose (doc/timed-messages.md). Changes come with channels_changed. Needs the messages.lifetime feature.

Authentication: Session cookie

Responses

StatusMeaningBody
200The settings.LifetimeSettings
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
LifetimeSettings
FieldTypeDescription
message_lifetime_max_seconds (required)integerMaxSeconds is the longest lifetime anybody may choose.
message_lifetimes_enabled (required)booleanEnabled lets members send messages with a lifetime.

GET /api/messages/by-number/{number}

Resolves the short number used in links (/m/4821, /t/4821) to the message, including its channel_id and, for a thread reply, its parent_id.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
numberpathintegeryesMessage number.

Responses

StatusMeaningBody
200Message.Message
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them.
content (required)string
created_at (required)string (date-time)
direct_mentionsstring (uuid)[]DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list.
display_name (required)string
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (date-time)ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock.
forwardForwardRefForward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward.
id (required)string (uuid)
is_botbooleanIsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message.
is_edited (required)boolean
is_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (uuid)[]MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves.
mentions (required)string (uuid)[]Mentions are the users this message mentions (@username, @all, @here).
noncestring (uuid)Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does.
number (required)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (date-time)PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone).
pinned_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle is the required title of a root post in a forum channel (max 100 characters).
updated_at (required)string (date-time)
user_id (required)string (uuid)
username (required)string

Read the original of a forwarded message

GET /api/messages/{messageID}/forward

The original of a forwarded message as the caller may see it right now: its text, author, time and channel when the caller can see it, otherwise only available=false. Edits and deletes of the original show through. Needs View channel for the forwarded message itself.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
messageIDpathstring (uuid)yesID of the forwarded message.

Responses

StatusMeaningBody
200The quote.ForwardQuote
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the message does not exist, is not a forward, or the caller cannot see it.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
ForwardQuote
FieldTypeDescription
attachment_countinteger
authorUserRef
available (required)boolean
channel_idstring (uuid)
channel_namestring
contentstring
created_atstring (date-time)
deletedboolean
is_editedboolean
message_idstring (uuid)The rest is set only when Available.

Forward a message

POST /api/messages/{messageID}/forward

Posts a new message in the target channel or direct message conversation that points at the original; the original's text is never copied, and every reader sees it only if they may see the original. The caller needs to see the original and to send in the target (and the rules of a conversation apply). Forwarding a forward points at its original. The comment is optional. Every refusal answers the same 403 text. The target's slow mode applies. Broadcasts message_create.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
messageIDpathstring (uuid)yesMessage ID.

Request body (application/json, required): ForwardRequest

FieldTypeDescription
channel_id (required)string (uuid)ChannelID is the channel or direct message conversation to forward to.
commentstringComment is the forwarder's own text, optional.

Responses

StatusMeaningBody
201The new message.Message
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation, or the original has a lifetime (it cannot be forwarded: the forward would outlive it).ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: the same text for every refusal (no access to the original, no right to send in the target, a conversation that does not take the message), or cross-origin request rejected.ErrorResponse
429RATE_LIMITED: too many requests, or the target's slow mode.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them.
content (required)string
created_at (required)string (date-time)
direct_mentionsstring (uuid)[]DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list.
display_name (required)string
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (date-time)ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock.
forwardForwardRefForward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward.
id (required)string (uuid)
is_botbooleanIsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message.
is_edited (required)boolean
is_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (uuid)[]MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves.
mentions (required)string (uuid)[]Mentions are the users this message mentions (@username, @all, @here).
noncestring (uuid)Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does.
number (required)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (date-time)PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone).
pinned_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle is the required title of a root post in a forum channel (max 100 characters).
updated_at (required)string (date-time)
user_id (required)string (uuid)
username (required)string

Toggle a reaction

POST /api/messages/{messageID}/reactions

Adds the caller's reaction, or removes it if already present. A user may add at most 20 different emoji to one message, and a message carries at most 50 different emoji (409 CONFLICT beyond that). One emoji with and without U+FE0F (a red heart, a thumbs up) is one reaction, stored and returned in its fully-qualified Unicode form; skin tones and joined sequences stay separate emoji. Broadcasts message_reaction.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
messageIDpathstring (uuid)yesMessage ID.

Request body (application/json, required): ReactionRequest

FieldTypeDescription
emoji (required)stringEmoji has no whitespace, control characters, '<' or '>'.

Responses

StatusMeaningBody
200Resulting reactions.ReactionResult
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Add reactions permission in the channel, a block between the two members of a one-to-one direct message (a new reaction is refused; taking one back still works), or cross-origin request rejected. RULES_NOT_ACCEPTED: the member has not accepted the community rules yet.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
409CONFLICT: too many reactions on this message.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
ReactionResult
FieldTypeDescription
channel_id (required)string (uuid)ChannelID is the channel of the message.
message_id (required)string (uuid)
reactions (required)ReactionSummary[]

Report a message

POST /api/messages/{messageID}/report

Reports a message of a channel or a direct message to the moderators. The caller must be able to see the message (otherwise 404, as for any message they cannot see). The report keeps a copy of the message and up to 20 messages around it, so it still stands after the author deletes the message; it is the only way a moderator sees any part of a direct message. A member cannot report their own message. Repeating a report of the same message while the first is open returns the first. At most 10 reports per hour and 50 open reports per member. Records the audit entry report.create (without message text).

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
messageIDpathstring (uuid)yesMessage ID.

Request body (application/json, required): CreateReportRequest

FieldTypeDescription
category (required)stringCategory is why the message is reported.
notestringNote is an optional explanation for the moderators, up to 500 characters.

Responses

StatusMeaningBody
201The report was filed.ReportFiled
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
409CONFLICT: too many open reports.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
ReportFiled
FieldTypeDescription
id (required)string (uuid)

Get a thread

GET /api/messages/{messageID}/thread

The root message plus a page of replies, oldest first. Use at most one of before, after (reply IDs). The message must be a root message; a reply has no thread (404).

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
messageIDpathstring (uuid)yesMessage ID.
limitqueryintegernoPage size. Values below 1 or non-numeric fall back to the default; larger values are clamped to 100.
beforequerystring (uuid)noReplies older than this reply.
afterquerystring (uuid)noReplies newer than this reply.

Responses

StatusMeaningBody
200Thread.Thread
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Thread
FieldTypeDescription
followingbooleanFollowing: replies of this thread notify the caller. Servers before 1.1 do not send it.
replies (required)Message[]
root (required)Message

Search messages

GET /api/search

Text channels and voice channels' chats (with dm=true, the caller's direct messages instead), newest first (or by sort). Every term (max 8) must occur case-insensitively; a quoted phrase is one term and a leading minus excludes messages containing it. At least one of q, channel_id, author_id, mentions, has, is, after, before_date, during, filename or author is required. Reply hits carry parent_id; roots maps those ids to the thread root with a snippet.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
qquerystringnoSearch terms, whitespace separated; a quoted phrase is one term, a leading minus excludes a word.
channel_idquerystring (uuid)noOnly messages of this channel.
author_idquerystring (uuid)noOnly messages of this author.
authorquerystringnoOnly messages by this author type: bot, webhook or member.
hasquerystringnoOnly messages with a file, an image, a video, a link, an embed, a poll or an edit.
isquerystringnoOnly pinned messages.
mentionsquerystring (uuid)noOnly messages that mention this user (directly or via @all/@here).
filenamequerystringnoOnly messages with an attachment matching this file name (case-insensitive substring).
afterquerystring (date-time)noOnly messages created after this instant (RFC 3339); must be earlier than before_date.
before_datequerystring (date-time)noOnly messages created before this instant (RFC 3339).
duringquerystring (date)noOnly messages created during this day (YYYY-MM-DD) in the caller's timezone.
tzquerystringnoTimezone offset for during (e.g. +02:00, -0500, or minutes east of UTC; a signed run of three digits such as -300 is ambiguous and refused).
beforequerystring (uuid)noPage back: only messages older (or newer, if sort=oldest) than this message.
sortquerystringnoSort order: newest (default) or oldest. relevance is accepted as an alias of newest: search has no ranking.
dmquerybooleannoSearch the caller's direct message conversations instead of channels. Only conversations the caller is in are searched; channel_id may name one of them.
limitqueryintegernoPage size. Values below 1 or non-numeric fall back to the default; larger values are clamped to 50.

Responses

StatusMeaningBody
200One page of results.SearchResult
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the before cursor no longer exists (it was deleted since the previous page); reload the list.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
SearchResult
FieldTypeDescription
has_more (required)boolean
messages (required)Message[]
roots (required)objectRoots maps a reply hit's parent_id to its thread root.

Threads the caller follows

GET /api/threads/following

The root message IDs of the threads the caller follows in channels they may view, newest follow first, at most 500. A client uses it to decide which thread replies notify.

Authentication: Session cookie

Responses

StatusMeaningBody
200Followed threads.FollowedThreads
401No valid session (UNAUTHORIZED).ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
FollowedThreads
FieldTypeDescription
thread_ids (required)string (uuid)[]

Unfollow a thread

DELETE /api/threads/{threadID}/follow

Replies of the thread stop notifying the caller, except those that mention the caller or quote their message. The choice is kept: a later reply by the caller does not follow the thread again. Needs View channels. Idempotent. Sends thread_follow_updated to the caller's sessions.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
threadIDpathstring (uuid)yesID of the thread's root message.

Responses

StatusMeaningBody
200The follow state.ThreadFollow
400Invalid input (INVALID_INPUT): malformed ID.ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
404NOT_FOUND: no such thread, or its channel is hidden from the caller.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
ThreadFollow
FieldTypeDescription
following (required)booleanFollowing: replies of the thread notify the caller.
thread_id (required)string (uuid)ThreadID is the root message of the thread.

Follow a thread

PUT /api/threads/{threadID}/follow

Replies of the thread notify the caller from now on (push and in-page notifications). The root's author, everyone who replies and everyone mentioned in a reply follow automatically. Needs View channels; a reply or an unknown message is 404. Idempotent. Sends thread_follow_updated to the caller's sessions.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
threadIDpathstring (uuid)yesID of the thread's root message.

Responses

StatusMeaningBody
200The follow state.ThreadFollow
400Invalid input (INVALID_INPUT): malformed ID.ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
404NOT_FOUND: no such thread, or its channel is hidden from the caller.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
ThreadFollow
FieldTypeDescription
following (required)booleanFollowing: replies of the thread notify the caller.
thread_id (required)string (uuid)ThreadID is the root message of the thread.

Something wrong on this page? Tell us.