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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
limit | query | integer | no | Page size. Values below 1 or non-numeric fall back to the default; larger values are clamped to 100. |
before | query | string (uuid) | no | Messages older than this message. |
after | query | string (uuid) | no | Messages newer than this message. |
around | query | string (uuid) | no | Messages around (and including) this message. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | A page of messages. | Message[] |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Request body (application/json, required): CreateMessageRequest
| Field | Type | Description |
|---|---|---|
attachment_ids | string (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) | string | Content is required unless attachment_ids is set. |
lifetime_seconds | integer | LifetimeSeconds 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). |
nonce | string (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_id | string | null | ParentID must be a root message of the same channel (thread reply). |
reply_to_id | string | null | ReplyToID must be a message of the same conversation (quoted reply). |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The message already created with this nonce (a retried send). | Message |
| 201 | Created message. | Message |
| 400 | Invalid 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 |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: 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 |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 410 | MESSAGE_DELETED: the message sent with this nonce was deleted since; it is not posted again. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Message
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | 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_mentions | string (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 | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (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. |
forward | ForwardRef | Forward 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_bot | boolean | IsBot 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_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (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). |
nonce | string (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) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (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_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Request body (application/json, required): BulkDeleteRequest
| Field | Type | Description |
|---|---|---|
count (required) | integer | Count is how many of their latest messages (replies included), 1 to 100. |
reason | string | Reason is kept in the audit log. Optional. |
user_id (required) | string (uuid) | UserID is the member whose latest messages in the channel go. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | How many messages went. | BulkDeleteResult |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage messages permission in the channel, or the member's highest role is not below yours, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
BulkDeleteResult
| Field | Type | Description |
|---|---|---|
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | Message ID. |
Request body (application/json): DeleteMessageRequest
| Field | Type | Description |
|---|---|---|
reason | string | Reason is shown to the author when a moderator deletes their message, and kept in the audit log. Up to 200 characters. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: you are neither the author nor hold Manage messages in the channel, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | Message ID. |
Request body (application/json, required): EditMessageRequest
| Field | Type | Description |
|---|---|---|
content (required) | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated message. | Message |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: 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 |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Message
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | 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_mentions | string (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 | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (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. |
forward | ForwardRef | Forward 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_bot | boolean | IsBot 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_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (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). |
nonce | string (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) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (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_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | Message ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Earlier versions, newest first. | MessageEditHistory |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage messages permission in the channel. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
MessageEditHistory
| Field | Type | Description |
|---|---|---|
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | Message ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The message. | Message |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage messages permission in the channel, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Message
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | 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_mentions | string (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 | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (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. |
forward | ForwardRef | Forward 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_bot | boolean | IsBot 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_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (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). |
nonce | string (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) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (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_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | Message ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The message. | Message |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation, or the message has a lifetime (it cannot be pinned). | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: missing the Manage messages permission in the channel, or cross-origin request rejected. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 409 | CONFLICT: the channel already has 50 pinned messages. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Message
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | 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_mentions | string (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 | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (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. |
forward | ForwardRef | Forward 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_bot | boolean | IsBot 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_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (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). |
nonce | string (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) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (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_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The pinned messages. | Message[] |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Request body (application/json, required): CreatePostRequest
| Field | Type | Description |
|---|---|---|
content (required) | string | |
tag_ids | string[] | |
title (required) | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Created post. | Message |
| 400 | INVALID_INPUT | ErrorResponse |
| 401 | UNAUTHORIZED | ErrorResponse |
| 403 | FORBIDDEN | ErrorResponse |
| 404 | NOT_FOUND | ErrorResponse |
Message
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | 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_mentions | string (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 | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (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. |
forward | ForwardRef | Forward 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_bot | boolean | IsBot 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_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (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). |
nonce | string (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) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (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_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | Message ID. |
Request body (application/json, required): UpdatePostRequest
| Field | Type | Description |
|---|---|---|
is_locked | boolean | |
is_resolved | boolean | IsResolved marks the post as solved (author or Manage messages) or reopens it. |
tag_ids | string[] | |
title | string |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Updated post. | Message |
| 400 | INVALID_INPUT | ErrorResponse |
| 401 | UNAUTHORIZED | ErrorResponse |
| 403 | FORBIDDEN | ErrorResponse |
| 404 | NOT_FOUND | ErrorResponse |
Message
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | 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_mentions | string (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 | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (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. |
forward | ForwardRef | Forward 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_bot | boolean | IsBot 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_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (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). |
nonce | string (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) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (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_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel or conversation ID. |
Request body (application/json, required): CreateScheduledRequest
| Field | Type | Description |
|---|---|---|
content (required) | string | |
lifetime_seconds | integer | LifetimeSeconds 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_id | string | null | |
reply_to_id | string | 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
| Status | Meaning | Body |
|---|---|---|
| 201 | The scheduled message. | Scheduled |
| 400 | Invalid input (INVALID_INPUT): bad content, a time that is not in the future or too far ahead, an unknown reply target. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 403 | FORBIDDEN: missing the Send messages permission in the channel. RULES_NOT_ACCEPTED: the member has not accepted the community rules yet. | ErrorResponse |
| 404 | NOT_FOUND: no such channel, or it is hidden from the caller. | ErrorResponse |
| 409 | CONFLICT: the member has 50 scheduled messages already. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Scheduled
| Field | Type | Description |
|---|---|---|
channel_id (required) | string (uuid) | |
channel_name (required) | string | ChannelName 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) | string | FailureReason is set when State is failed: slow_mode, not_allowed, unavailable or refused. |
id (required) | string (uuid) | |
lifetime_seconds | integer | LifetimeSeconds 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) | string | State 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
| Status | Meaning | Body |
|---|---|---|
| 200 | The reminders. | ReminderList |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
ReminderList
| Field | Type | Description |
|---|---|---|
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
| Field | Type | Description |
|---|---|---|
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
| Status | Meaning | Body |
|---|---|---|
| 201 | The reminder. | Reminder |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, or a time that is not in the future or too far ahead. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 404 | NOT_FOUND: no such message, or the channel is hidden from the caller. | ErrorResponse |
| 409 | CONFLICT: the member has 100 reminders already. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Reminder
| Field | Type | Description |
|---|---|---|
available (required) | boolean | Available 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 | null | DeliveredAt is set once the reminder fell due; it then waits in the list until the caller dismisses it. |
id (required) | string (uuid) | |
message | MessageRef | |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
reminderID | path | string (uuid) | yes | Reminder ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Removed. | |
| 400 | Invalid input (INVALID_INPUT): bad ID. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 404 | NOT_FOUND: the caller has no such reminder. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | no | Page size. Values below 1 or non-numeric fall back to the default; larger values are clamped to 100. |
before | query | string (uuid) | no | Page back: only entries older than this saved message. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | One page of the saved list. | SavedPage |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the before cursor no longer exists (it was deleted since the previous page); reload the list. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
SavedPage
| Field | Type | Description |
|---|---|---|
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
messageID | path | string (uuid) | yes | Message ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Removed (or was not saved). | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
messageID | path | string (uuid) | yes | Message ID. |
Request body (application/json): SaveRequest
| Field | Type | Description |
|---|---|---|
note | string | null | Note replaces the note; left out (or null), a saved message keeps its note and a new one starts without. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The saved entry. | SavedMessage |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 409 | CONFLICT: the saved list is full. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
SavedMessage
| Field | Type | Description |
|---|---|---|
available (required) | boolean | Available 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. |
message | Message | |
message_id (required) | string (uuid) | |
note (required) | string | Note 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
| Status | Meaning | Body |
|---|---|---|
| 200 | The scheduled messages. | ScheduledList |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
ScheduledList
| Field | Type | Description |
|---|---|---|
items (required) | Scheduled[] |
Delete a scheduled message
DELETE /api/me/scheduled/{scheduledID}
Removes a waiting or failed scheduled message.
Authentication: Session cookie
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
scheduledID | path | string (uuid) | yes | Scheduled message ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Removed. | |
| 400 | Invalid input (INVALID_INPUT): bad ID. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 404 | NOT_FOUND: the caller has no such scheduled message (it may have been sent). | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
scheduledID | path | string (uuid) | yes | Scheduled message ID. |
Request body (application/json, required): UpdateScheduledRequest
| Field | Type | Description |
|---|---|---|
content | string | null | |
send_at | string | null | SendAt moves the message; for a failed one it also puts it back to waiting. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The scheduled message. | Scheduled |
| 400 | Invalid input (INVALID_INPUT): bad content or time. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 404 | NOT_FOUND: the caller has no such scheduled message (it may have been sent). | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Scheduled
| Field | Type | Description |
|---|---|---|
channel_id (required) | string (uuid) | |
channel_name (required) | string | ChannelName 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) | string | FailureReason is set when State is failed: slow_mode, not_allowed, unavailable or refused. |
id (required) | string (uuid) | |
lifetime_seconds | integer | LifetimeSeconds 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) | string | State 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
before | query | string (uuid) | no | Page back: only messages older than this message. |
limit | query | integer | no | Page size. Values below 1 or non-numeric fall back to the default; larger values are clamped to 50. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | One page of mentions. | MentionsPage |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the before cursor no longer exists (it was deleted since the previous page); reload the list. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
MentionsPage
| Field | Type | Description |
|---|---|---|
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
| Status | Meaning | Body |
|---|---|---|
| 200 | The settings. | LifetimeSettings |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
LifetimeSettings
| Field | Type | Description |
|---|---|---|
message_lifetime_max_seconds (required) | integer | MaxSeconds is the longest lifetime anybody may choose. |
message_lifetimes_enabled (required) | boolean | Enabled lets members send messages with a lifetime. |
Get a message by its link number
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
number | path | integer | yes | Message number. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Message. | Message |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Message
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | 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_mentions | string (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 | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (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. |
forward | ForwardRef | Forward 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_bot | boolean | IsBot 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_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (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). |
nonce | string (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) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (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_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
messageID | path | string (uuid) | yes | ID of the forwarded message. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The quote. | ForwardQuote |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the message does not exist, is not a forward, or the caller cannot see it. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
ForwardQuote
| Field | Type | Description |
|---|---|---|
attachment_count | integer | |
author | UserRef | |
available (required) | boolean | |
channel_id | string (uuid) | |
channel_name | string | |
content | string | |
created_at | string (date-time) | |
deleted | boolean | |
is_edited | boolean | |
message_id | string (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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
messageID | path | string (uuid) | yes | Message ID. |
Request body (application/json, required): ForwardRequest
| Field | Type | Description |
|---|---|---|
channel_id (required) | string (uuid) | ChannelID is the channel or direct message conversation to forward to. |
comment | string | Comment is the forwarder's own text, optional. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The new message. | Message |
| 400 | Invalid 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 |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: 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 |
| 429 | RATE_LIMITED: too many requests, or the target's slow mode. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Message
| Field | Type | Description |
|---|---|---|
attachments (required) | MediaAttachment[] | |
avatar_url | string | |
channel_id (required) | string (uuid) | |
components | ActionRow[] | 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_mentions | string (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 | |
embeds | Embed[] | Embeds are the rich cards of a webhook message (a subset). |
expires_at | string (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. |
forward | ForwardRef | Forward 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_bot | boolean | IsBot 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_locked | boolean | IsLocked marks a forum post as locked: only moderators can post replies. |
is_pinned (required) | boolean | |
is_resolved | boolean | IsResolved marks a forum post as solved or answered. |
is_webhook | boolean | IsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label). |
last_activity_at | string (date-time) | LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time. |
mention_roles | string (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). |
nonce | string (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) | integer | Number is the message's short, stable link number (/m/4821). |
parent_id | string (uuid) | |
pinned_at | string (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_by | UserRef | |
poll | Poll | Poll is set when the message is a poll; its content is the question. |
reactions (required) | ReactionSummary[] | |
reply_count (required) | integer | |
reply_to | ReplyPreview | |
reply_to_id | string (uuid) | |
tags | ForumTag[] | Tags are the forum tags attached to a forum post (up to 5 tags). |
title | string | Title 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
messageID | path | string (uuid) | yes | Message ID. |
Request body (application/json, required): ReactionRequest
| Field | Type | Description |
|---|---|---|
emoji (required) | string | Emoji has no whitespace, control characters, '<' or '>'. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Resulting reactions. | ReactionResult |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 403 | FORBIDDEN: 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 |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 409 | CONFLICT: too many reactions on this message. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
ReactionResult
| Field | Type | Description |
|---|---|---|
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
messageID | path | string (uuid) | yes | Message ID. |
Request body (application/json, required): CreateReportRequest
| Field | Type | Description |
|---|---|---|
category (required) | string | Category is why the message is reported. |
note | string | Note is an optional explanation for the moderators, up to 500 characters. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The report was filed. | ReportFiled |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 409 | CONFLICT: too many open reports. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
ReportFiled
| Field | Type | Description |
|---|---|---|
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
messageID | path | string (uuid) | yes | Message ID. |
limit | query | integer | no | Page size. Values below 1 or non-numeric fall back to the default; larger values are clamped to 100. |
before | query | string (uuid) | no | Replies older than this reply. |
after | query | string (uuid) | no | Replies newer than this reply. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Thread. | Thread |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Thread
| Field | Type | Description |
|---|---|---|
following | boolean | Following: 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q | query | string | no | Search terms, whitespace separated; a quoted phrase is one term, a leading minus excludes a word. |
channel_id | query | string (uuid) | no | Only messages of this channel. |
author_id | query | string (uuid) | no | Only messages of this author. |
author | query | string | no | Only messages by this author type: bot, webhook or member. |
has | query | string | no | Only messages with a file, an image, a video, a link, an embed, a poll or an edit. |
is | query | string | no | Only pinned messages. |
mentions | query | string (uuid) | no | Only messages that mention this user (directly or via @all/@here). |
filename | query | string | no | Only messages with an attachment matching this file name (case-insensitive substring). |
after | query | string (date-time) | no | Only messages created after this instant (RFC 3339); must be earlier than before_date. |
before_date | query | string (date-time) | no | Only messages created before this instant (RFC 3339). |
during | query | string (date) | no | Only messages created during this day (YYYY-MM-DD) in the caller's timezone. |
tz | query | string | no | Timezone 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). |
before | query | string (uuid) | no | Page back: only messages older (or newer, if sort=oldest) than this message. |
sort | query | string | no | Sort order: newest (default) or oldest. relevance is accepted as an alias of newest: search has no ranking. |
dm | query | boolean | no | Search the caller's direct message conversations instead of channels. Only conversations the caller is in are searched; channel_id may name one of them. |
limit | query | integer | no | Page size. Values below 1 or non-numeric fall back to the default; larger values are clamped to 50. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | One page of results. | SearchResult |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the before cursor no longer exists (it was deleted since the previous page); reload the list. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
SearchResult
| Field | Type | Description |
|---|---|---|
has_more (required) | boolean | |
messages (required) | Message[] | |
roots (required) | object | Roots 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
| Status | Meaning | Body |
|---|---|---|
| 200 | Followed threads. | FollowedThreads |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
FollowedThreads
| Field | Type | Description |
|---|---|---|
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
threadID | path | string (uuid) | yes | ID of the thread's root message. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The follow state. | ThreadFollow |
| 400 | Invalid input (INVALID_INPUT): malformed ID. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 404 | NOT_FOUND: no such thread, or its channel is hidden from the caller. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
ThreadFollow
| Field | Type | Description |
|---|---|---|
following (required) | boolean | Following: 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
threadID | path | string (uuid) | yes | ID of the thread's root message. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The follow state. | ThreadFollow |
| 400 | Invalid input (INVALID_INPUT): malformed ID. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED). | ErrorResponse |
| 404 | NOT_FOUND: no such thread, or its channel is hidden from the caller. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
ThreadFollow
| Field | Type | Description |
|---|---|---|
following (required) | boolean | Following: replies of the thread notify the caller. |
thread_id (required) | string (uuid) | ThreadID is the root message of the thread. |