REST: Bot API

The REST API of bot accounts (/api/bot/v1), authenticated with a bot token. Errors are JSON with a message and a code; see doc/bots.md for the gateway. Generated from mnema-talk v3.3.13 (cca4f0fdb723).

List the bot's channels

GET /api/bot/v1/channels

The categories and channels the bot may view, through its roles and overwrites. A bot without a role sees nothing. A category shows when its own permissions allow it or any of its channels is visible.

Authentication: Bot token (Authorization: Bot <token>)

Responses

StatusMeaningBody
200Visible categories and channels.ChannelHierarchy
401Missing or invalid token (0).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error
ChannelHierarchy
FieldTypeDescription
categories (required)Category[]
uncategorized (required)Channel[]

List channel messages

GET /api/bot/v1/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. Needs View channels in the channel; a channel the bot cannot view answers 404 like a missing one.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
limitqueryintegernoPage size (1 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 form body (50035).Error
401Missing or invalid token (0).Error
404Unknown Channel (10003) or Unknown Message (10008).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error

Post a message

POST /api/bot/v1/channels/{channelID}/messages

Posts as the bot (author name, avatar and the BOT badge). Needs View channels and Send messages in the channel. At least one of content, embeds or components (buttons and select menus, stored with the message and part of message_create). @all and @here notify only when the bot may mention everyone and allowed_mentions.parse asks for "everyone". Limit: 5 messages per 5 seconds per channel, on top of 50 requests per second per bot. For files use the upload route.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (application/json, required): BotCreateMessageRequest

FieldTypeDescription
allowed_mentions (required)BotAllowedMentionsAllowedMentions limits who is notified. Default: members mentioned by @username are, @all and @here are not.
componentsActionRow[]Components are buttons and select menus in up to 5 action rows (doc/bots.md, Message components).
content (required)stringContent is the message text (Markdown), at most 4000 characters.
embeds (required)Embed[]Embeds are rich cards (at most 10).
lifetime_secondsintegerLifetimeSeconds makes the server delete the message that long after it is stored, as for a member (60 to 2592000, at most the community's ceiling; doc/timed-messages.md). Needs the messages.lifetime feature.
message_reference (required)BotMessageReferenceMessageReference quotes a message of the same channel.
parent_idstring | nullParentID posts into the thread of a root message of the channel.

Responses

StatusMeaningBody
201The created message.Message
400Invalid form body (50035) or empty message (50006).Error
401Missing or invalid token (0).Error
403Missing Permissions (50013).Error
404Unknown Channel (10003).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error
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 message

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

The bot's own messages, or any message when the bot holds Manage messages in the channel. Also deletes the message's thread replies and attachments.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

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

Responses

StatusMeaningBody
204Deleted.
400Invalid form body (50035).Error
401Missing or invalid token (0).Error
403Missing Permissions (50013).Error
404Unknown Channel (10003) or Unknown Message (10008).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error

Get a message

GET /api/bot/v1/channels/{channelID}/messages/{messageID}

Needs View channels in the channel.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

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

Responses

StatusMeaningBody
200The message.Message
400Invalid form body (50035).Error
401Missing or invalid token (0).Error
404Unknown Channel (10003) or Unknown Message (10008).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error
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 the bot's own message

PATCH /api/bot/v1/channels/{channelID}/messages/{messageID}

Only the bot's own messages; needs Send messages in the channel. content and components are each optional and stay as they are when left out; "components": [] removes them. The content may be empty while the message keeps an attachment, embeds or components. An edit that keeps the content does not mark the message edited. Broadcasts message_update (MESSAGE_UPDATE on the gateway).

Authentication: Bot token (Authorization: Bot <token>)

Parameters

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

Request body (application/json, required): BotEditMessageRequest

FieldTypeDescription
allowed_mentionsBotAllowedMentionsAllowedMentions narrows whom the new text notifies, as on a post (and on callback 7 and @original). An edit that sends it counts towards the per-channel limit of posts.
componentsActionRow[]Components replace the message's buttons and select menus; [] removes them.
contentstring | nullContent is the new text. It may be empty while the message keeps an attachment, embeds or components.

Responses

StatusMeaningBody
200The updated message.Message
400Invalid form body (50035).Error
401Missing or invalid token (0).Error
403Missing Permissions (50013), or not the bot's own message.Error
404Unknown Channel (10003) or Unknown Message (10008).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error
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

Remove the bot's reaction

DELETE /api/bot/v1/channels/{channelID}/messages/{messageID}/reactions/{emoji}/@me

Idempotent. Taking a reaction back always works. It removes the emoji in every form it is stored in (with and without U+FE0F).

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesMessage ID.
emojipathstringyesThe emoji, URL-encoded.

Responses

StatusMeaningBody
204Removed, or not there.
400Invalid form body (50035).Error
401Missing or invalid token (0).Error
404Unknown Channel (10003) or Unknown Message (10008).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error

Add the bot's reaction

PUT /api/bot/v1/channels/{channelID}/messages/{messageID}/reactions/{emoji}/@me

Idempotent. The emoji is URL-encoded. Needs Add reactions in the channel. One emoji with and without U+FE0F is one reaction, stored in its fully-qualified Unicode form. A user may add at most 20 different emoji to one message, and a message carries at most 50 different emoji (409).

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.
messageIDpathstring (uuid)yesMessage ID.
emojipathstringyesThe emoji, URL-encoded.

Responses

StatusMeaningBody
204Added, or already there.
400Invalid form body (50035).Error
401Missing or invalid token (0).Error
403Missing Permissions (50013).Error
404Unknown Channel (10003) or Unknown Message (10008).Error
409Too many reactions.Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error

Post a message with an attachment

POST /api/bot/v1/channels/{channelID}/upload

multipart/form-data. Creates a message carrying the file as the bot. Needs View channels, Send messages and Attach files in the channel. The size limit is the Owner's upload limit for the bot's roles (and the server's), the type is sniffed and checked against an allowlist. Counts towards the send limit of the channel.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
channelIDpathstring (uuid)yesChannel ID.

Request body (multipart/form-data, required): object

FieldTypeDescription
allowed_mentionsstringThe allowed_mentions object of the message route (parse, users, roles), JSON-encoded. Without it the caption notifies the members it names, never @all, @here or a role.
contentstringOptional caption.
file (required)string (binary)The file; type is sniffed and checked against an allowlist.
lifetime_secondsintegerThe message's lifetime: the server deletes it that long after storing it (60 to 2592000, at most the community's ceiling). Needs the messages.lifetime feature.
parent_idstring (uuid)Thread root message ID (reply in a thread).
reply_to_idstring (uuid)Quoted message ID.

Responses

StatusMeaningBody
201Created message.Message
400Invalid form body (50035).Error
401Missing or invalid token (0).Error
403Missing Permissions (50013).Error
404Unknown Channel (10003).Error
413Request entity too large (40005).Error
415The file type is not allowed.Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error
503File storage is not available.Error
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 the bot's commands

GET /api/bot/v1/commands

The commands this bot registered, including those an admin switched off. Registration is by PUT (replace all) or POST (one).

Authentication: Bot token (Authorization: Bot <token>)

Responses

StatusMeaningBody
200The bot's commands.Command[]
401Missing or invalid token (0).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error

Register a command

POST /api/bot/v1/commands

Creates the command, or updates the one with the same name (keeping an admin's disabled flag).

Authentication: Bot token (Authorization: Bot <token>)

Request body (application/json, required): CommandInput

FieldTypeDescription
default_member_permissionsstring
description (required)string
name (required)stringName is lowercase letters, digits, '-' and '_' (1 to 32).
options (required)Option[]

Responses

StatusMeaningBody
200The command.Command
400Invalid form body (50035).Error
401Missing or invalid token (0).Error
409The bot has the maximum number of commands.Error
429Rate limited; see retry_after and Retry-After.RateLimitError
Command
FieldTypeDescription
bot_id (required)string (uuid)
created_at (required)string (date-time)
default_member_permissionsstring | null
description (required)string
disabled (required)booleanDisabled commands are hidden from members and refuse invocations; only an admin can set it, a bot registering the command again keeps it.
id (required)string (uuid)
name (required)string
options (required)Option[]

Replace the bot's commands

PUT /api/bot/v1/commands

Bulk overwrite: adds and updates the given commands by name and removes the others. An admin's disabled flag on a command stays. At most 50 commands, 10 options each. Members see the commands in every channel the bot can view and send in.

Authentication: Bot token (Authorization: Bot <token>)

Request body (application/json, required): CommandInput[]

Responses

StatusMeaningBody
200The bot's commands.Command[]
400Invalid form body (50035).Error
401Missing or invalid token (0).Error
429Rate limited; see retry_after and Retry-After.RateLimitError

Delete a command

DELETE /api/bot/v1/commands/{commandID}

Removes one of the bot's own commands, except one an admin switched off (404; the admin deletes those). Members stop seeing it in the composer at once.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
commandIDpathstring (uuid)yesCommand ID.

Responses

StatusMeaningBody
204Deleted.
400Invalid form body (50035).Error
401Missing or invalid token (0).Error
404Unknown command.Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error

Get the gateway address

GET /api/bot/v1/gateway

Returns the WebSocket address of the gateway. The same path is the gateway itself when the request is a WebSocket upgrade; its protocol (HELLO, IDENTIFY, READY, heartbeats, DISPATCH, RESUME) is described in doc/bots.md because OpenAPI cannot express it. Authenticate the upgrade with Authorization: Bot <token> (never a query parameter) or with the token in IDENTIFY.

Authentication: Bot token (Authorization: Bot <token>)

Responses

StatusMeaningBody
200The gateway.Info
401Missing or invalid token (0).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
Info
FieldTypeDescription
heartbeat_interval (required)integerHeartbeatInterval is the interval the gateway will ask for, in milliseconds (also in HELLO).
max_connections (required)integerMaxConnections is how many gateway connections one bot may hold.
url (required)stringURL is the WebSocket address of the gateway.

Respond to an interaction

POST /api/bot/v1/interactions/{interactionID}/{token}/callback

The first response to an interaction: a command run, a component click or a modal submit. Type 4 posts a message in the channel as the bot (or, with flags 64, shows it to the member only); type 5 only acknowledges, and the answer follows with PATCH @original or follow-ups (with flags 64 it is ephemeral); type 6 acknowledges a click without changing anything; type 7 updates the message the component is on (absent fields stay); type 9 opens a modal (not for a modal submit). Types 6 and 7 need a component's message: a click, or a modal opened from one. An interaction can be answered for 15 minutes, with at most 5 messages in total. Posting or updating needs Send messages in the channel at that moment.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
interactionIDpathstring (uuid)yesInteraction ID.
tokenpathstringyesInteraction token from the INTERACTION_CREATE event.

Request body (application/json, required): CallbackRequest

FieldTypeDescription
data (required)CallbackData
type (required)integerType is 4 (reply with a message), 5 (acknowledge now, answer later), 6 (acknowledge a click), 7 (update the message the component is on) or 9 (open a modal); which answer which interaction is in doc/bots.md.

Responses

StatusMeaningBody
204Accepted.
400Invalid form body (50035), empty message (50006), or a callback type the interaction does not take.Error
401Missing or invalid token (0).Error
403Missing Permissions (50013).Error
404Unknown interaction (10062), or the message to update is gone (10008).Error
409Already answered.Error
429Rate limited; see retry_after and Retry-After.RateLimitError

Send a follow-up to an interaction

POST /api/bot/v1/interactions/{interactionID}/{token}/followups

After the first response (not a modal): another message for the same interaction (public, or ephemeral with flags 64). Counts towards the 5 messages.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
interactionIDpathstring (uuid)yesInteraction ID.
tokenpathstringyesInteraction token from the INTERACTION_CREATE event.

Request body (application/json, required): ResponseData

FieldTypeDescription
allowed_mentionsBotAllowedMentionsAllowedMentions narrows whom the message notifies, as on a post.
componentsActionRow[]Components are buttons and select menus (doc/bots.md, Message components).
content (required)string
embeds (required)InEmbed[]
flags (required)integerFlags: 64 makes the response ephemeral, visible only to the member who ran the command (never stored).

Responses

StatusMeaningBody
201The posted message.Message
204Shown to the member only.
400Invalid form body (50035) or empty message (50006).Error
401Missing or invalid token (0).Error
403Missing Permissions (50013).Error
404Unknown interaction (10062).Error
409Respond first, or too many responses.Error
429Rate limited; see retry_after and Retry-After.RateLimitError
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 the original response

DELETE /api/bot/v1/interactions/{interactionID}/{token}/messages/@original

Deletes the original response of an interaction (see the PATCH of @original): a message is deleted as by DELETE /channels/{id}/messages/{id}, an ephemeral note disappears from the member's view. Works for the 15 minutes of the interaction.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
interactionIDpathstring (uuid)yesInteraction ID.
tokenpathstringyesInteraction token from the INTERACTION_CREATE event.

Responses

StatusMeaningBody
204Deleted.
401Missing or invalid token (0).Error
403Missing Permissions (50013).Error
404Unknown interaction (10062), or no original response (10008).Error
409Respond first.Error
429Rate limited; see retry_after and Retry-After.RateLimitError

Edit the original response

PATCH /api/bot/v1/interactions/{interactionID}/{token}/messages/@original

Edits the original response of an interaction: the message of callback 4, or for a component answered with 6 or 7 the message the component is on. After callback 5 the first PATCH posts the answer (ephemeral when callback 5 had flags 64) and counts towards the 5 messages. Absent fields stay as they are. An ephemeral original is replaced in the member's view (204). Works for the 15 minutes of the interaction; needs Send messages in the channel.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
interactionIDpathstring (uuid)yesInteraction ID.
tokenpathstringyesInteraction token from the INTERACTION_CREATE event.

Request body (application/json, required): OriginalEdit

FieldTypeDescription
allowed_mentionsBotAllowedMentionsAllowedMentions narrows whom the new text notifies, as on a post.
componentsActionRow[]
contentstring
embedsInEmbed[]

Responses

StatusMeaningBody
200The edited or posted message.Message
204The member's ephemeral note was replaced, or posted.
400Invalid form body (50035) or empty message (50006).Error
401Missing or invalid token (0).Error
403Missing Permissions (50013).Error
404Unknown interaction (10062), or no original response (10008).Error
409Respond first, or too many responses.Error
429Rate limited; see retry_after and Retry-After.RateLimitError
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

Download an attachment

GET /api/bot/v1/media/{id}

Streams a message attachment to an authenticated bot. Needs View channels for a channel attachment (text or voice), or to be a participant of the direct message. Attachments of deleted or expired messages, and unfinished uploads answer 404.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesMedia ID.

Responses

StatusMeaningBody
200File content; Content-Type is the stored MIME type.string
401Missing or invalid token (0).Error
404Media not found (10003).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error
503File storage is not available.Error

List members

GET /api/bot/v1/members

Needs the GUILD_MEMBERS intent to be allowed for the bot (an admin sets it). Lists only the members who can view at least one channel the bot can view; no profile, presence or role data.

Authentication: Bot token (Authorization: Bot <token>)

Responses

StatusMeaningBody
200Members.BotMember[]
401Missing or invalid token (0).Error
403The bot is not allowed to read members (50013).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error

Get a member

GET /api/bot/v1/members/{userID}

Same rules as the list; a member the bot may not know about answers 404.

Authentication: Bot token (Authorization: Bot <token>)

Parameters

NameInTypeRequiredDescription
userIDpathstring (uuid)yesUser ID.

Responses

StatusMeaningBody
200The member.BotMember
400Invalid form body (50035).Error
401Missing or invalid token (0).Error
403The bot is not allowed to read members (50013).Error
404Unknown User (10013).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error
BotMember
FieldTypeDescription
avatar_urlstring
botbooleanBot is true for bot accounts, which are members too. Mention one by its username like any member; message.mentions then lists its id.
display_name (required)string
id (required)string (uuid)
username (required)string

Get the bot itself

GET /api/bot/v1/users/@me

The bot behind the token: its user ID (the author of its messages), name, avatar and the gateway intents it may use. Also a cheap way to check a token.

Authentication: Bot token (Authorization: Bot <token>)

Responses

StatusMeaningBody
200The bot.Self
401Missing or invalid token (0).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
Self
FieldTypeDescription
allowed_intents (required)integerAllowedIntents are the gateway intents the admin allowed.
avatar_urlstring
bot (required)boolean
bot_id (required)string (uuid)
handlestringHandle is the account's unique name, the one members mention (for example @mnemo);
id (required)string (uuid)ID is the bot's user ID: the author of its messages (user_id).
username (required)stringName is the bot's name as members see it (its display name).

Something wrong on this page? Tell us.