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
| Status | Meaning | Body |
|---|---|---|
| 200 | Visible categories and channels. | ChannelHierarchy |
| 401 | Missing or invalid token (0). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server failure. | Error |
ChannelHierarchy
| Field | Type | Description |
|---|---|---|
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
limit | query | integer | no | Page size (1 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 form body (50035). | Error |
| 401 | Missing or invalid token (0). | Error |
| 404 | Unknown Channel (10003) or Unknown Message (10008). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Request body (application/json, required): BotCreateMessageRequest
| Field | Type | Description |
|---|---|---|
allowed_mentions (required) | BotAllowedMentions | AllowedMentions limits who is notified. Default: members mentioned by @username are, @all and @here are not. |
components | ActionRow[] | Components are buttons and select menus in up to 5 action rows (doc/bots.md, Message components). |
content (required) | string | Content is the message text (Markdown), at most 4000 characters. |
embeds (required) | Embed[] | Embeds are rich cards (at most 10). |
lifetime_seconds | integer | LifetimeSeconds 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) | BotMessageReference | MessageReference quotes a message of the same channel. |
parent_id | string | null | ParentID posts into the thread of a root message of the channel. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The created message. | Message |
| 400 | Invalid form body (50035) or empty message (50006). | Error |
| 401 | Missing or invalid token (0). | Error |
| 403 | Missing Permissions (50013). | Error |
| 404 | Unknown Channel (10003). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server failure. | Error |
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 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | Message ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. | |
| 400 | Invalid form body (50035). | Error |
| 401 | Missing or invalid token (0). | Error |
| 403 | Missing Permissions (50013). | Error |
| 404 | Unknown Channel (10003) or Unknown Message (10008). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server 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
| 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 form body (50035). | Error |
| 401 | Missing or invalid token (0). | Error |
| 404 | Unknown Channel (10003) or Unknown Message (10008). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server failure. | Error |
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 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | Message ID. |
Request body (application/json, required): BotEditMessageRequest
| Field | Type | Description |
|---|---|---|
allowed_mentions | BotAllowedMentions | AllowedMentions 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. |
components | ActionRow[] | Components replace the message's buttons and select menus; [] removes them. |
content | string | null | Content is the new text. It may be empty while the message keeps an attachment, embeds or components. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The updated message. | Message |
| 400 | Invalid form body (50035). | Error |
| 401 | Missing or invalid token (0). | Error |
| 403 | Missing Permissions (50013), or not the bot's own message. | Error |
| 404 | Unknown Channel (10003) or Unknown Message (10008). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server failure. | Error |
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 |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | Message ID. |
emoji | path | string | yes | The emoji, URL-encoded. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Removed, or not there. | |
| 400 | Invalid form body (50035). | Error |
| 401 | Missing or invalid token (0). | Error |
| 404 | Unknown Channel (10003) or Unknown Message (10008). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
messageID | path | string (uuid) | yes | Message ID. |
emoji | path | string | yes | The emoji, URL-encoded. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Added, or already there. | |
| 400 | Invalid form body (50035). | Error |
| 401 | Missing or invalid token (0). | Error |
| 403 | Missing Permissions (50013). | Error |
| 404 | Unknown Channel (10003) or Unknown Message (10008). | Error |
| 409 | Too many reactions. | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
channelID | path | string (uuid) | yes | Channel ID. |
Request body (multipart/form-data, required): object
| Field | Type | Description |
|---|---|---|
allowed_mentions | string | The 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. |
content | string | Optional caption. |
file (required) | string (binary) | The file; type is sniffed and checked against an allowlist. |
lifetime_seconds | integer | The 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_id | string (uuid) | Thread root message ID (reply in a thread). |
reply_to_id | string (uuid) | Quoted message ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Created message. | Message |
| 400 | Invalid form body (50035). | Error |
| 401 | Missing or invalid token (0). | Error |
| 403 | Missing Permissions (50013). | Error |
| 404 | Unknown Channel (10003). | Error |
| 413 | Request entity too large (40005). | Error |
| 415 | The file type is not allowed. | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server failure. | Error |
| 503 | File storage is not available. | Error |
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 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
| Status | Meaning | Body |
|---|---|---|
| 200 | The bot's commands. | Command[] |
| 401 | Missing or invalid token (0). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server 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
| Field | Type | Description |
|---|---|---|
default_member_permissions | string | |
description (required) | string | |
name (required) | string | Name is lowercase letters, digits, '-' and '_' (1 to 32). |
options (required) | Option[] |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The command. | Command |
| 400 | Invalid form body (50035). | Error |
| 401 | Missing or invalid token (0). | Error |
| 409 | The bot has the maximum number of commands. | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
Command
| Field | Type | Description |
|---|---|---|
bot_id (required) | string (uuid) | |
created_at (required) | string (date-time) | |
default_member_permissions | string | null | |
description (required) | string | |
disabled (required) | boolean | Disabled 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
| Status | Meaning | Body |
|---|---|---|
| 200 | The bot's commands. | Command[] |
| 400 | Invalid form body (50035). | Error |
| 401 | Missing or invalid token (0). | Error |
| 429 | Rate 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
commandID | path | string (uuid) | yes | Command ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. | |
| 400 | Invalid form body (50035). | Error |
| 401 | Missing or invalid token (0). | Error |
| 404 | Unknown command. | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server 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
| Status | Meaning | Body |
|---|---|---|
| 200 | The gateway. | Info |
| 401 | Missing or invalid token (0). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
Info
| Field | Type | Description |
|---|---|---|
heartbeat_interval (required) | integer | HeartbeatInterval is the interval the gateway will ask for, in milliseconds (also in HELLO). |
max_connections (required) | integer | MaxConnections is how many gateway connections one bot may hold. |
url (required) | string | URL 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
interactionID | path | string (uuid) | yes | Interaction ID. |
token | path | string | yes | Interaction token from the INTERACTION_CREATE event. |
Request body (application/json, required): CallbackRequest
| Field | Type | Description |
|---|---|---|
data (required) | CallbackData | |
type (required) | integer | Type 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
| Status | Meaning | Body |
|---|---|---|
| 204 | Accepted. | |
| 400 | Invalid form body (50035), empty message (50006), or a callback type the interaction does not take. | Error |
| 401 | Missing or invalid token (0). | Error |
| 403 | Missing Permissions (50013). | Error |
| 404 | Unknown interaction (10062), or the message to update is gone (10008). | Error |
| 409 | Already answered. | Error |
| 429 | Rate 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
interactionID | path | string (uuid) | yes | Interaction ID. |
token | path | string | yes | Interaction token from the INTERACTION_CREATE event. |
Request body (application/json, required): ResponseData
| Field | Type | Description |
|---|---|---|
allowed_mentions | BotAllowedMentions | AllowedMentions narrows whom the message notifies, as on a post. |
components | ActionRow[] | Components are buttons and select menus (doc/bots.md, Message components). |
content (required) | string | |
embeds (required) | InEmbed[] | |
flags (required) | integer | Flags: 64 makes the response ephemeral, visible only to the member who ran the command (never stored). |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The posted message. | Message |
| 204 | Shown to the member only. | |
| 400 | Invalid form body (50035) or empty message (50006). | Error |
| 401 | Missing or invalid token (0). | Error |
| 403 | Missing Permissions (50013). | Error |
| 404 | Unknown interaction (10062). | Error |
| 409 | Respond first, or too many responses. | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
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 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
interactionID | path | string (uuid) | yes | Interaction ID. |
token | path | string | yes | Interaction token from the INTERACTION_CREATE event. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. | |
| 401 | Missing or invalid token (0). | Error |
| 403 | Missing Permissions (50013). | Error |
| 404 | Unknown interaction (10062), or no original response (10008). | Error |
| 409 | Respond first. | Error |
| 429 | Rate 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
interactionID | path | string (uuid) | yes | Interaction ID. |
token | path | string | yes | Interaction token from the INTERACTION_CREATE event. |
Request body (application/json, required): OriginalEdit
| Field | Type | Description |
|---|---|---|
allowed_mentions | BotAllowedMentions | AllowedMentions narrows whom the new text notifies, as on a post. |
components | ActionRow[] | |
content | string | |
embeds | InEmbed[] |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The edited or posted message. | Message |
| 204 | The member's ephemeral note was replaced, or posted. | |
| 400 | Invalid form body (50035) or empty message (50006). | Error |
| 401 | Missing or invalid token (0). | Error |
| 403 | Missing Permissions (50013). | Error |
| 404 | Unknown interaction (10062), or no original response (10008). | Error |
| 409 | Respond first, or too many responses. | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
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 |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Media ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | File content; Content-Type is the stored MIME type. | string |
| 401 | Missing or invalid token (0). | Error |
| 404 | Media not found (10003). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server failure. | Error |
| 503 | File 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
| Status | Meaning | Body |
|---|---|---|
| 200 | Members. | BotMember[] |
| 401 | Missing or invalid token (0). | Error |
| 403 | The bot is not allowed to read members (50013). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userID | path | string (uuid) | yes | User ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The member. | BotMember |
| 400 | Invalid form body (50035). | Error |
| 401 | Missing or invalid token (0). | Error |
| 403 | The bot is not allowed to read members (50013). | Error |
| 404 | Unknown User (10013). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
| 500 | Server failure. | Error |
BotMember
| Field | Type | Description |
|---|---|---|
avatar_url | string | |
bot | boolean | Bot 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
| Status | Meaning | Body |
|---|---|---|
| 200 | The bot. | Self |
| 401 | Missing or invalid token (0). | Error |
| 429 | Rate limited; see retry_after and Retry-After. | RateLimitError |
Self
| Field | Type | Description |
|---|---|---|
allowed_intents (required) | integer | AllowedIntents are the gateway intents the admin allowed. |
avatar_url | string | |
bot (required) | boolean | |
bot_id (required) | string (uuid) | |
handle | string | Handle 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) | string | Name is the bot's name as members see it (its display name). |