API reference

API reference

Every request, call, event and field a bot can use. For a walk through making a bot, start with Building a bot.

This page is written out from the server's own code by tools/apiref.mjs, so the names, fields and types are the ones the server uses. Change that file, not this page.

The basics

• Address: https://api.maplecord.app. Requests are under /api/; the live connection is at /hubs/chat.
• Token: every request carries Authorization: Bot <token>. The live connection is a SignalR connection whose access token is bot:<token>.
• Bodies and answers are JSON. Field names are camelCase.
• IDs are GUIDs, written as text. Times are ISO 8601 text, in UTC.
• Kinds (of message, of channel, and so on) are sent as numbers. The tables under Kinds say which number is which.
• Errors come back as { "error": "..." } with a status that fits: 400 the request was wrong, 401 no token or a bad one, 403 not allowed, 404 not there or not visible to the bot, 413 too large, 429 too fast.
• Something missing or hidden answers 404 either way: a bot is not told that a channel it cannot see exists.
• P2P channels: nothing in them goes through the server, so none of this reads or posts there.
• GET /api/meta needs no token. Among other things it says whether the live connection must go straight over a WebSocket (webSocketsOnly).

Limits

What	Limit	Past it
Requests	600 a minute for each bot	429 with a Retry-After header
Posting with a request	10 in any 10 seconds	429 with a Retry-After header
Posting, editing, reacting, pinning and voting over the live connection, together	10 in any 10 seconds	The call fails: "You are doing that too fast"
Other calls on the live connection	800 in any 10 seconds	The same
A webhook	30 posts a minute	429
One message over the live connection	128 KB
A message	4000 characters	400

Requests

Who and where

Looking up the bot itself and the servers it is in.

Request	What it does	Needs	Body	Answer
GET /api/me	The bot's own account.			UserDto
GET /api/guilds	Every server the bot is in, each with its channels, members and roles. Channels are limited to the ones the bot may see.			list of GuildSummaryDto
GET /api/guilds/{guildId}	One server, the same way.			GuildSummaryDto
GET /api/guilds/{guildId}/roles	That server's roles.			list of RoleDto
POST /api/guilds/{guildId}/leave	The bot leaves the server.

Reading messages

All of these need View channels in that channel.

Request	What it does	Needs	Body	Answer
GET /api/channels/{channelId}/messages	Messages, newest first. limit is 50 unless given, 200 at most. before, after or around take a message ID. thread takes the ID of a message and reads its thread. Query: before, after, around, thread, limit.	View channels		list of MessageDto
GET /api/channels/{channelId}/messages/{messageId}	One message.	View channels		MessageDto
GET /api/channels/{channelId}/posts	The posts of a forum or a gallery, newest activity first. limit is 30 unless given, 100 at most; before takes a moment. Query: before, limit.	View channels		list of MessageDto
GET /api/channels/{channelId}/pins	The pinned messages.	View channels		list of MessageDto
GET /api/channels/{channelId}/media	The pictures and videos posted there, newest first. limit is 60 unless given, 120 at most. Query: before, limit.	View channels		list of MediaItemDto
GET /api/channels/{channelId}/search	Messages containing the words in q, up to 25. Pass the before it gives back to go on from there. One search at a time for each account. Query: q, before.	View channels		SearchResultDto
GET /api/reactions	The emoji that can be used as reactions.			list of text

Calendars

A calendar is a kind of channel with events on its days. A day is written year-month-day (2026-10-31).

Request	What it does	Needs	Body	Answer
GET /api/channels/{channelId}/events	The events from the day from to the day to, 100 days at most.	View channels		list of CalendarEventDto
POST /api/channels/{channelId}/events	Puts an event on a day. at is the moment it starts, or null for one with no time. A day holds at most 25.	Post events	CalendarEventRequest	CalendarEventDto
PATCH /api/events/{eventId}	Changes an event: the bot's own while it may still post events there, or anyone's with Manage messages.		CalendarEventRequest	CalendarEventDto
DELETE /api/events/{eventId}	Takes an event off: the bot's own, or anyone's with Manage messages. Answers 204.

Posting

Editing, deleting, reacting and pinning are done over the live connection, further down.

Request	What it does	Needs	Body	Answer
POST /api/channels/{channelId}/messages	Posts a message: plain, an answer, in a thread, a post in a forum or gallery, or a poll. Answers 201 with the message. At most 10 in any 10 seconds.	Send messages	SendMessageRequest	MessageDto
POST /api/channels/{channelId}/attachments	Uploads one picture, to be put on a message by passing its id in attachmentIds. A bot can post pictures and no other kind of file. Answers 201.	Attach files	a file, as multipart/form-data	AttachmentDto
GET /api/uploads/settings	The largest file the server takes, how many days it keeps files, and whether uploads are on.			{ maxBytes, keepDays, enabled }

Slash commands

The bot uses its own token for these; {appId} is its Bot ID.

Request	What it does	Needs	Body	Answer
PUT /api/applications/{appId}/commands	Sets the bot's commands for every server it is in. The list replaces what was there. The body is a list of CommandDefinition. A P2P bot lists the commands people type to it this way, by name and description alone; they are not slash commands.			list of CommandDto
PUT /api/applications/{appId}/guilds/{guildId}/commands	The same, for one server.			list of CommandDto
GET /api/applications/{appId}/commands	The commands the bot has registered.			list of CommandDto
GET /api/applications/me	Which bot is asking: its Bot ID, name and kind.			ApplicationDto
GET /api/applications/{appId}/guilds/{guildId}/command-rules	Who a server lets use the bot's commands, and where, with the people who manage the server. For a P2P bot, whose commands are typed to it and never pass through the server: it applies this itself. (An ordinary bot has no need to ask: the server holds people to it.)			BotCommandRulesDto
GET /api/guilds/{guildId}/commands	The commands of every bot in a server that whoever asks may use there. Whoever manages a server can limit a bot's commands to certain roles, people and channels; channelIds, when it is there, is the only channels a command can be used in.			list of CommandDto
POST /api/interactions/{interactionId}/{token}	Answers a use of a command or a press of a button. Needs no Authorization header: the token in the address allows it, once. With update true in answer to a button, the message the button is on is changed to this and nothing new is posted. Answers 204.		InteractionResponse

Webhooks

Managing them needs Manage webhooks. Posting to one needs only its address.

Request	What it does	Needs	Body	Answer
POST /api/channels/{channelId}/webhooks	Makes a webhook for a text channel. The answer is the only time its token and url are given.	Manage webhooks	CreateWebhookRequest	WebhookDto
GET /api/channels/{channelId}/webhooks	That channel's webhooks.	Manage webhooks		list of WebhookDto
GET /api/guilds/{guildId}/webhooks	That server's webhooks.	Manage webhooks		list of WebhookDto
PATCH /api/webhooks/{webhookId}	Renames it, changes its picture, or moves it to another channel of the same server.	Manage webhooks	UpdateWebhookRequest	WebhookDto
POST /api/webhooks/{webhookId}/regenerate	Gives it a new address. The old one stops working.	Manage webhooks		WebhookDto
DELETE /api/webhooks/{webhookId}	Deletes it.	Manage webhooks
POST /api/webhooks/{webhookId}/{token}	Posts a message as the webhook. Needs no token of its own. The body is described under Posting to a webhook. At most 30 a minute for each webhook.			MessageDto

Running a server

A bot can do these if its roles give it the permission, as a person could.

Request	What it does	Needs	Body	Answer
PUT /api/guilds/{guildId}/welcome	Sets the welcome channel (null for none), and whether a line is posted there when someone joins.	Manage server	WelcomeRequest	GuildDto
POST /api/guilds/{guildId}/channels	Makes a channel or a category.	Manage channels	CreateChannelRequest	ChannelDto
PATCH /api/channels/{channelId}	Renames a channel or moves it. Only what is given changes.	Manage channels	UpdateChannelRequest	ChannelDto
DELETE /api/channels/{channelId}	Deletes a channel.	Manage channels
POST /api/guilds/{guildId}/invites	Makes an invite. expiresInMinutes and maxUses may each be null for no limit.	Create invites	CreateInviteRequest	InviteDto
GET /api/guilds/{guildId}/invites	The invites that still work: all of them with Manage server, the bot's own otherwise.	Create invites		list of InviteDto
DELETE /api/invites/{code}	Takes an invite back. The bot's own, or anyone's with Manage server.
GET /api/invites/{code}/qr	An invite's link as a QR code: the squares, for the asker to draw.			QrDto
POST /api/guilds/{guildId}/roles	Makes a role.	Manage roles	CreateRoleRequest	RoleDto
PATCH /api/roles/{roleId}	Changes a role. Only roles below the bot's own highest.	Manage roles	UpdateRoleRequest	RoleDto
DELETE /api/roles/{roleId}	Deletes a role.	Manage roles
PUT /api/guilds/{guildId}/members/{userId}/roles	Sets which roles a member has.	Manage roles	SetMemberRolesRequest	MemberDto
PUT /api/guilds/{guildId}/members/{userId}/nickname	Sets or clears a member's nickname. Its own needs nothing; someone else's needs Manage server.		SetNicknameRequest	MemberDto
DELETE /api/guilds/{guildId}/members/{userId}	Removes a member from the server.	Kick members
POST /api/guilds/{guildId}/bans/{userId}	Bans someone. deleteDays also deletes what they wrote there in that many days past; null deletes nothing.	Ban members	BanRequest
DELETE /api/guilds/{guildId}/bans/{userId}	Lifts a ban.	Ban members
PUT /api/guilds/{guildId}/members/{userId}/voice-mute	Mutes someone in the server's voice channels, or undoes it.	Mute members	VoiceMuteRequest	MemberDto

Posting to a webhook

The body of POST /api/webhooks/{webhookId}/{token}. Either content or embeds has to be there.

Field	Type
content	text	Up to 4000 characters
username	text	A name to post as this once, in place of the webhook's own. Up to 80 characters
avatarUrl	text	A picture to post with this once
embeds	list of embed	Up to 10 cards

An embed, the same in an answer to a slash command:

Field	Type
title	text	Up to 256 characters
description	text	Up to 2048 characters
url	text	Where the title leads
color	number	0xRRGGBB as a number: #2f6bff is 3107839
fields	list of { name, value, inline }	Up to 25. A name is up to 256 characters, a value up to 1024
image	{ url }	A picture. Up to 4 a message are shown; the server fetches each and serves its own copy
footer	{ text }	Up to 256 characters

The live connection

A SignalR connection to /hubs/chat. If GET /api/meta says webSocketsOnly is true, connect straight over a WebSocket and skip negotiation.

Calls

What a bot can call. A call that is refused fails with the reason as its message.

Call	What it does	Answer
Ready()	Call this first, and again after every reconnect. It is answered once the server has finished taking the connection in.
SendMessage(channelId, content, attachmentIds)	Posts a message. attachmentIds may be null. channelId: ID; content: text; attachmentIds: list of ID, or null.	MessageDto
Post(request)	Posts with more choices: an answer, a thread, a titled post, a poll. request: PostRequest.	MessageDto
EditMessage(messageId, content, title)	Edits one of the bot's own messages. title only matters for a post in a forum or gallery; pass null otherwise. messageId: ID; content: text; title: text, or null.
DeleteMessage(messageId)	Deletes one of its own, or someone else's with Manage messages. messageId: ID.
React(messageId, emoji, on)	Adds (on true) or removes a reaction. The emoji has to be one of GET /api/reactions. A message holds at most 20 different ones. messageId: ID; emoji: text; on: true or false.
ReactToPicture(attachmentId, emoji, on)	The same for one picture of a gallery post, apart from the post as a whole. Not in a P2P gallery. attachmentId: ID; emoji: text; on: true or false.
Pin(messageId, on)	Pins or unpins. Needs Manage messages. A channel holds at most 50 pins. messageId: ID; on: true or false.
Vote(messageId, options)	Votes in a poll: the numbers of the choices picked, counting from 0. An empty list takes the vote back. messageId: ID; options: list of number.
ClosePoll(messageId)	Closes a poll: one the bot started, or anyone's with Manage messages. messageId: ID.
SetTyping(channelId)	Shows the bot as typing in a channel for a few seconds. channelId: ID.
RespondToInteraction(interactionId, token, response)	Answers a use of one of the bot's slash commands, or a press of one of its buttons. Once. With update true in answer to a button, the message the button is on is changed to this (text, embeds, buttons) and nothing new is posted. interactionId: ID; token: text; response: InteractionResponse.

Connection() answers this connection's own ID as text. It is only needed when webSocketsOnly is true.

Events

What the server sends. Register a handler by name. A bot is only sent events for servers it is in and channels it can see.

Messages

Event	When	It carries
MessageReceived	A message was posted in a channel the bot can see.	message: MessageDto
ThreadMessage	A message was posted in a thread. These do not arrive as MessageReceived.	message: MessageDto
ThreadChanged	How many messages a thread holds now, and when the last was written.	channelId: ID; rootId: ID; count: number; lastAt: time, or null
MessageEdited	A message was edited.	channelId: ID; messageId: ID; content: text; title: text, or null; editedAt: time
MessageChanged	A bot changed one of its own messages in answer to a button on it: its text, embeds and buttons now.	channelId: ID; messageId: ID; content: text; embeds: list of EmbedDto, or null; buttons: list of ButtonDto, or null
MessageDeleted	A message was deleted.	channelId: ID; messageId: ID
MessagesRemoved	Everything one person wrote in a channel was deleted, or everything since a moment. This happens when someone is banned.	channelId: ID; authorId: ID; since: time, or null
MessagePinned	A message was pinned at a moment, or (null) is no longer pinned.	channelId: ID; messageId: ID; pinnedAt: time, or null
ReactionChanged	Someone added or took away a reaction. count is how many that emoji has on the message now.	channelId: ID; messageId: ID; emoji: text; userId: ID; on: true or false; count: number
PictureReactionChanged	The same for one picture of a gallery post.	channelId: ID; messageId: ID; attachmentId: ID; emoji: text; userId: ID; on: true or false; count: number
CalendarEventChanged	An event was put on a calendar, or one was changed.	calendarEvent: CalendarEventDto
CalendarEventDeleted	An event was taken off a calendar.	channelId: ID; eventId: ID
PollChanged	Someone voted, or the poll was closed: what they picked, the votes each choice has, and how many people voted.	channelId: ID; messageId: ID; userId: ID; theirs: list of number; counts: list of number; voters: number; closed: true or false
Typing	Someone is typing.	channelId: ID; userId: ID; username: text

Slash commands

Event	When	It carries
InteractionCreated	Someone used one of the bot's commands, or pressed one of its buttons. Answer within 8 seconds. A command the server does not let someone use never arrives.	interaction: InteractionDto
CommandsChanged	The commands available in a server changed.	guildId: ID

Servers, channels and members

Event	When	It carries
MemberJoined	Someone joined a server the bot is in.	guildId: ID; member: MemberDto
MemberLeft	Someone left, or was removed.	guildId: ID; userId: ID
MemberUpdated	A member's roles or nickname changed.	guildId: ID; member: MemberDto
MemberPresence	A member came online or went offline.	guildId: ID; userId: ID; online: true or false
PresenceStatus	Someone switched "do not disturb" on or off.	userId: ID; dnd: true or false
PresenceIdle	Someone became idle, or stopped being.	userId: ID; idle: true or false
UserUpdated	Someone changed how they appear: name, picture, name style.	user: UserDto
ChannelCreated	A channel was made.	channel: ChannelDto
ChannelUpdated	A channel was renamed, moved or changed.	channel: ChannelDto
ChannelDeleted	A channel was deleted.	guildId: ID; channelId: ID
RoleCreated	A role was made.	role: RoleDto
RoleUpdated	A role changed.	role: RoleDto
RoleDeleted	A role was deleted.	guildId: ID; roleId: ID
PermissionsChanged	What the bot may see or do in a server may have changed. Read the server again.	guildId: ID
GuildUpdated	The server's name, picture or listing changed.	guild: GuildDto
GuildDeleted	The server was deleted.	guildId: ID
VoiceStateChanged	Who is in a voice channel changed.	channelId: ID; participants: list of VoiceParticipantDto

Others

The connection is the same one the app uses, so a bot may also be sent events that are about people, not bots: rolls, friends, calls, files sent between people, P2P channels and notices from whoever runs the server. A bot can leave these without a handler.

DirectTextPeerJoined, DirectTextPeerLeft, DirectTextSignalReceived, DirectTextClosed, RollStarted, RollUpdated, RollEnded, RollStats, RpsStarted, RpsUpdated, RpsEnded, FriendRequest, FriendAccepted, FriendRemoved, FriendPresence, DmOpened, FileRequested, FileSealOffered, FileSignalReceived, FileOfferEnded, FileOfferResumed, ServerNotice, SystemMessage, ConnectionsChanged

Shapes

Every record named above, and the ones they hold. A field marked "or null" may be missing.

ApplicationDto

Token and InteractionsSecret are only present in the response to create/regenerate.

Field	Type
id	ID
name	text
description	text, or null
ownerId	ID
botUserId	ID
botUsername	text
interactionsUrl	text, or null
createdAt	time
token	text, or null
interactionsSecret	text, or null
direct	true or false
voice	true or false	It may join voice channels: ordinary ones for an ordinary bot, P2P ones for a P2P bot. Sound only, never video.
suspended	true or false	Whoever runs this Maplecord has stopped it: for now (suspended), or for good and out of every server (banned).
banned	true or false

AttachmentDto

A file on a message. contentType is what the server found the file to be: an image or video type means it can be shown in place, anything else is a download. expired means the server no longer holds it; an app that kept its own copy can still show it.

Field	Type
id	ID
fileName	text
contentType	text
size	number
url	text
expired	true or false
reactions	list of ReactionDto, or null	On a picture of a gallery post: the reactions to that picture itself, apart from those to the post.

BanRequest

DeleteDays: also delete what they wrote in this server in the last 1, 3 or 7 days, or (0) all of it. Left out, nothing is deleted.

Field	Type
reason	text, or null
deleteDays	number, or null

BotCommandRulesDto

The same rules, as a bot is told them, with the people who manage the server, whom no rule shuts out. For a P2P bot, whose commands are typed to it and never pass through the server: it applies the rules itself.

Field	Type
bot	CommandRuleDto
commands	list of CommandRuleOfDto
managers	list of ID

ButtonDto

A button under a bot's message. id is the bot's own name for it, handed back when it is pressed; label is what it says; style is 0 plain, 1 in the accent colour, 2 red.

Field	Type
id	text
label	text
style	number

CalendarEventDto

Something on a calendar channel. day is the day it is on, as year-month-day. at, when the event has a time, is the moment it starts: apps show it in each person's own time zone, where it can fall on the day before or after day.

Field	Type
id	ID
channelId	ID
authorId	ID
authorName	text
title	text
note	text, or null
day	text
at	time, or null
createdAt	time
editedAt	time, or null

CalendarEventRequest

An event to post, or what one is to become. Title 1 to 100 characters; Day as year-month-day; Note and At if it has them.

Field	Type
title	text
note	text, or null
day	text
at	time, or null

ChannelDto

directSince is set on a P2P voice channel: people in it connect straight to each other and can see each other's IP addresses. It is the moment the channel became one, so an app can tell a channel it has already warned its user about from one that has since been switched. Null for every ordinary (relayed) channel.

Field	Type
id	ID
guildId	ID, or null
parentId	ID, or null
name	text
type	ChannelType
position	number
overrides	list of ChannelOverrideDto, or null
directSince	time, or null
bots	list of ID, or null	The P2P bots (their accounts) let into this channel. Null when whatever sent this was not about them: an app then keeps what it knew.

CommandDefinition

What an application registers (bulk overwrite per scope).

Field	Type
name	text
description	text
options	list of CommandOptionDto, or null

CommandDto

Field	Type
id	ID
applicationId	ID
applicationName	text
guildId	ID, or null
name	text
description	text
options	list of CommandOptionDto
channelIds	list of ID, or null	The channels the person asking may use it in, where the server has limited that. Null for all of them.

CreateChannelRequest

Field	Type
name	text
type	ChannelType
parentId	ID, or null
direct	true or false

CreateInviteRequest

Field	Type
expiresInMinutes	number, or null
maxUses	number, or null

CreateRoleRequest

Field	Type
name	text
color	text, or null
permissions	number

CreateWebhookRequest

Field	Type
name	text
avatarUrl	text, or null

EmbedDto

A rich card attached to a message (webhooks and, later, bots). Color is 0xRRGGBB.

Field	Type
title	text, or null
description	text, or null
url	text, or null
color	number, or null
fields	list of EmbedFieldDto, or null
imageUrl	text, or null
footer	text, or null

GuildDto

Field	Type
id	ID
name	text
iconUrl	text, or null
ownerId	ID
createdAt	time
isPublic	true or false
description	text, or null
topics	list of text, or null
tagText	text, or null	The tag its members may wear, if it has set one; and whether tags have been turned off for it.
tagSymbol	text, or null
noTag	true or false
noRollStats	true or false	Rolls in this server's P2P channels are not added to people's roll totals.
welcomeChannelId	ID, or null	The text channel a line is posted in when someone joins, and whether one is posted.
welcomeMessages	true or false
fullP2P	true or false	A full P2P server: every channel in it is a P2P channel, and stays one. Fixed when the server is made.

GuildSummaryDto

Everything the client needs to render one guild in the sidebar. Channels are already filtered to what the caller may view.

Field	Type
guild	GuildDto
channels	list of ChannelDto
members	list of MemberDto
roles	list of RoleDto, or null
myPermissions	number
voice	map of ID to list of VoiceParticipantDto, or null	Who is currently in each voice channel (channel id → participants), so channels can be previewed before joining.

InteractionDto

Delivered to the bot when a user invokes one of its commands. Token authorizes exactly one response.

Field	Type
id	ID
token	text
applicationId	ID
commandId	ID
commandName	text
guildId	ID
channelId	ID
userId	ID
username	text
args	map of text to text
createdAt	time
messageId	ID, or null	When a button was pressed, not a command used: the message it is under. Null for a command.
buttonId	text, or null	When a button was pressed: the bot's own name for it. commandName is then empty.

InteractionResponse

Field	Type
content	text, or null
embeds	list of EmbedDto, or null
ephemeral	true or false
buttons	list of ButtonDto, or null	Up to five buttons under the answer. Left off an answer only its asker sees, which is not kept.
update	true or false	In answer to a button press: change the message the button is on to this (its text, embeds and buttons) and post nothing new. Ignored in answer to a slash command, which has no message to change.

InviteDto

Field	Type
code	text
guildId	ID
createdAt	time
expiresAt	time, or null
maxUses	number, or null
uses	number
createdBy	text, or null	Who made it, by the name they show. Only filled in when a server's invites are listed.
createdById	ID, or null

MediaItemDto

One picture or video of a channel, and the message it is on (and the thread that message is in, if it is in one).

Field	Type
file	AttachmentDto
messageId	ID
threadId	ID, or null
authorId	ID
authorName	text
at	time

MemberDto

Role is a legacy summary (Owner / Admin / Moderator / Member) derived from the member's permissions for older clients; RoleIds is the real list.

Field	Type
userId	ID
username	text
avatarUrl	text, or null
nickname	text, or null
role	GuildRole
online	true or false
roleIds	list of ID, or null
isBot	true or false
displayName	text, or null
nameFont	text, or null
nameColor	text, or null
nameColor2	text, or null
decoration	text, or null
dnd	true or false	Online and asking not to be disturbed. Only filled in on whole-server listings; changes arrive as PresenceStatus.
voiceMuted	true or false	Muted in this server's voice channels by someone who may mute members.
tag	TagDto, or null
directBot	true or false	A P2P bot: it is only in the P2P channels it was let into, and is shown in no other.
idle	true or false	Online and idle. Only filled in on whole-server listings; changes arrive as PresenceIdle.

MessageDto

Field	Type
id	ID
channelId	ID
authorId	ID
authorName	text
kind	MessageKind
content	text
createdAt	time
editedAt	time, or null
attachments	list of AttachmentDto
roll	RollResultDto, or null
embeds	list of EmbedDto, or null
authorAvatarUrl	text, or null
webhookId	ID, or null
ephemeral	true or false	Only delivered to one user and never persisted (bot replies marked ephemeral, command errors).
rps	RpsResultDto, or null
dice	DiceDto, or null
fileOffer	FileOfferDto, or null
call	CallLogDto, or null
replyTo	ReplyToDto, or null	The message this one answers, as it was when this was fetched; gone if it has since been deleted.
threadId	ID, or null	Set on a message that is in a thread: the message the thread hangs off. Such messages are not part of the channel's own list.
title	text, or null	A post's title, in a forum or a gallery channel.
threadCount	number	How many messages are in this message's thread, and when the last of them was written.
threadLastAt	time, or null
pinnedAt	time, or null
reactions	list of ReactionDto, or null	Who reacted with what. mine is about whoever asked for the message.
poll	PollDto, or null
buttons	list of ButtonDto, or null	Buttons under a bot's message. Pressing one tells the bot who pressed which.

PostRequest

Everything a message can be sent with. A reply names the message it answers; a message in a thread names the thread's first message; a post in a forum or gallery channel has a title.

Field	Type
channelId	ID
content	text, or null
attachmentIds	list of ID, or null
replyToId	ID, or null
threadId	ID, or null
title	text, or null
poll	NewPollDto, or null
buttons	list of ButtonDto, or null	Up to five buttons under the message. Only a bot's message can have them.

QrDto

A QR code as its squares: Size rows of Size, '1' for a dark one, with no margin around it.

Field	Type
size	number
modules	text

RoleDto

Field	Type
id	ID
guildId	ID
name	text
color	text, or null
position	number
permissions	number
isEveryone	true or false

SearchResultDto

What a search found, newest first, and how far back it looked: pass before to go on from there.

Field	Type
messages	list of MessageDto
before	time, or null
more	true or false

SendMessageRequest

A message posted with a plain request: what PostRequest holds, without the channel, which is in the address.

Field	Type
content	text, or null
attachmentIds	list of ID, or null
replyToId	ID, or null
threadId	ID, or null
title	text, or null
poll	NewPollDto, or null
buttons	list of ButtonDto, or null	Up to five buttons under the message. Only a bot's message can have them.

SetMemberRolesRequest

Field	Type
roleIds	list of ID

SetNicknameRequest

A member's name on one server only. Null or empty removes it, so their display name shows again.

Field	Type
nickname	text, or null

UpdateChannelRequest

Direct: true makes a voice channel P2P, false makes it relayed again, null leaves it. Either change empties the call.

Field	Type
name	text, or null
parentId	ID, or null
position	number, or null
direct	true or false, or null

UpdateRoleRequest

Field	Type
name	text, or null
color	text, or null
permissions	number, or null
position	number, or null

UpdateWebhookRequest

Field	Type
name	text, or null
avatarUrl	text, or null
channelId	ID, or null

UserDto

A user as they appear wherever they are shown. username is the name they registered with and never changes; displayName is what they chose to be called (null = use the username). Picture and decoration are paths on this server. The name font and colors are theirs to pick.

Field	Type
id	ID
username	text
avatarUrl	text, or null
displayName	text, or null
nameFont	text, or null
nameColor	text, or null
nameColor2	text, or null
decoration	text, or null
tag	TagDto, or null	The server tag they wear beside their name, if any.

VoiceMuteRequest

Field	Type
muted	true or false

VoiceParticipantDto

stream is what they are sharing with the channel, if anything: "screen", "window" or "camera". publicKey and seal are there in a P2P call only: the signing key of that person's app and its one-off sealing key, which the other apps use to encrypt the set-up messages they pass through the server. silenced: they cannot be heard here, because they may not speak in this channel or a moderator muted them. Their own app sends nothing, the stream server takes nothing from them, and everyone else's app plays nothing of theirs.

Field	Type
userId	ID
username	text
connectionId	text
muted	true or false
stream	text, or null
publicKey	text, or null
seal	text, or null
silenced	true or false
bot	true or false	A bot. In a P2P channel an app connects to one only if its user has agreed to that bot.
deafened	true or false	They have switched off hearing everyone. Their app says so; nothing here depends on it.
kbps	number, or null	For a bot being heard in an ordinary voice channel: the most sound it may send, in kilobits a second. The apps of the people listening hold it to that, because the server cannot measure what it sends. Null: no limit.

WebhookDto

Token is only present in the response to create/regenerate; it is stored hashed.

Field	Type
id	ID
channelId	ID
guildId	ID
name	text
avatarUrl	text, or null
createdById	ID
createdAt	time
token	text, or null
url	text, or null

WelcomeRequest

A server's welcome channel (null for none), and whether a line is posted there when someone joins.

Field	Type
channelId	ID, or null
messages	true or false

CallLogDto

How a call went: "ended" (they spoke for seconds), "missed" or "declined". The message's author is who called.

Field	Type
outcome	text
seconds	number
direct	true or false

ChannelOverrideDto

A per-channel allow/deny for one role or one user. Exactly one of RoleId/UserId is set.

Field	Type
id	ID
channelId	ID
roleId	ID, or null
userId	ID, or null
allow	number
deny	number

CommandOptionDto

Field	Type
name	text
description	text
type	CommandOptionType
required	true or false
choices	list of CommandChoiceDto, or null

CommandRuleDto

Who may use a bot's commands in one server, and where: everyone or only these roles and people; every channel or only these. Whoever manages the server is never shut out by one.

Field	Type
everyone	true or false
roleIds	list of ID
userIds	list of ID
allChannels	true or false
channelIds	list of ID

CommandRuleOfDto

One of a bot's commands, and the rule of its own a server has given it, if any (null: it goes by the bot's).

Field	Type
name	text
description	text
rule	CommandRuleDto, or null

DiceDto

Field	Type
value	number
min	number
max	number

EmbedFieldDto

Field	Type
name	text
value	text
inline	true or false

FileOfferDto

A file someone is offering to send straight from their app to whoever asks, without it being stored on the server. available is true while the sender's app is connected with the file. An offer that is not available comes back when the sender's app does, unless it was withdrawn.

Field	Type
id	ID
fileName	text
size	number
available	true or false
withdrawn	true or false

NewPollDto

What someone asks for when starting a poll: two to ten choices, whether more than one may be picked, and for how many hours it stays open (null: until its author closes it).

Field	Type
options	list of text
multi	true or false
hours	number, or null

PollDto

A poll on a message. mine on an option, and the counts, are as of when the message was fetched.

Field	Type
options	list of PollOptionDto
multi	true or false
closesAt	time, or null
voters	number
closed	true or false

ReactionDto

Field	Type
emoji	text
count	number
mine	true or false

ReplyToDto

Field	Type
id	ID
authorId	ID
authorName	text
snippet	text
gone	true or false

RollResultDto

Field	Type
sessionId	ID
channelId	ID
kind	RollKind
item	RollItemDto, or null
tieBreak	true or false
entries	list of RollEntryDto
winnerId	ID, or null
winnerName	text, or null
winningValue	number
tiedUserIds	list of ID	Non-empty when the roll ended in a tie and a tie-break session was started.
min	number
max	number

RpsResultDto

WinnerIds has one entry for a clean win, several when a tie-break round follows, none when nobody threw.

Field	Type
sessionId	ID
channelId	ID
tieBreak	true or false
entries	list of RpsEntryDto
winnerIds	list of ID
winningChoice	RpsChoice, or null
replay	true or false

TagDto

A server's tag as someone wears it: which server it is from, up to five letters or digits, and a symbol if it has one.

Field	Type
guildId	ID
text	text
symbol	text, or null

CommandChoiceDto

Field	Type
name	text
value	text

PollOptionDto

Field	Type
text	text
votes	number
mine	true or false

RollEntryDto

Field	Type
userId	ID
username	text
choice	RollChoice
value	number

RollItemDto

The thing being rolled for. PluginId/ItemId let clients that have the plugin installed resolve icon and metadata locally; Name is a snapshot so clients without the plugin still see something sensible.

Field	Type
pluginId	text, or null
itemId	text, or null
name	text
iconUrl	text, or null
quantity	number

RpsEntryDto

Field	Type
userId	ID
username	text
choice	RpsChoice

Kinds

The numbers that stand for each kind.

ChannelType

Number	Name
0	Category
1	Text
2	Voice	Voice channels also carry their own text chat.
3	DirectMessage	A private conversation between two users; no guild.
4	Forum	A list of posts, each with a title, newest activity first. What is said about a post is in its thread, not in the channel itself.
6	Calendar	A calendar: a month of days with events on them. It carries no messages. Its events are kept by the server, so it is never a P2P channel and a full P2P server has none.
5	Gallery	The same, where every post is one or more pictures: the channel shows the pictures, a post's thread what is said about it.

CommandOptionType

Number	Name
0	String
1	Integer
2	Boolean
3	User
4	Channel
5	Number

GuildRole

Number	Name
0	Member
1	Moderator
2	Admin
3	Owner

MessageKind

Number	Name
0	Text
1	System
2	Roll
3	CoinFlip
4	Webhook	Posted by an incoming webhook; AuthorName/avatar come from the webhook, not a user.
5	Bot	A bot's reply to a slash command.
6	Rps	Result of a rock-paper-scissors round.
7	Dice	A personal dice roll ("/dice"): server-generated number, no session, just posted to the channel.
8	FileOffer	Someone is offering a file straight from their app. The file is not on the server.
9	Call	A call between the two people of a direct-message channel, noted once it is over.

RollChoice

Number	Name
0	Roll
1	Need
2	Greed
3	Pass

RollKind

Number	Name
0	Standard	Everyone rolls 1-100 (or passes). Highest wins.
1	NeedGreed	Need beats Greed. Highest Need wins; if nobody needs, highest Greed wins.

RpsChoice

Number	Name
0	Rock
1	Paper
2	Scissors

Permissions

A set of permissions is one number: the sum of the numbers below for each permission held. myPermissions on a server and permissions on a role are written this way.

Number	In the app	In the code
1	View channels	ViewChannels
2	Send messages	SendMessages
4	Attach files	AttachFiles
8	Manage messages	ManageMessages
16	Start rolls	StartRolls
32	Join voice	JoinVoice
64	Speak	Speak
128	Stream	Stream
256	Create invites	CreateInvites
512	Manage channels	ManageChannels
1024	Manage roles	ManageRoles
2048	Manage webhooks	ManageWebhooks
4096	Manage server	ManageGuild
8192	Kick members	KickMembers
16384	Ban members	BanMembers
32768	Mute members	MuteMembers
65536	Create P2P channels	ManageDirectChannels
131072	Stream in P2P channels	StreamDirect
262144	Join P2P channels	JoinDirectVoice
1048576	Use the relay in P2P channels	UseRelayInDirect
524288	Disconnect members	DisconnectMembers
2097152	Wear the server tag	WearTag
4194304	Move members	MoveMembers
8388608	Post events	PostEvents
1073741824	Administrator	Administrator