Script functions

ban(userId, reason, deleteMessageDays?): boolean

Bans a user from the guild (members and non-members alike). For a temporary ban, queue the unban with runLater() and a Delayed script that calls unban(), rather than sweeping a list on a timer.

• userId (string): Discord snowflake ID of the user to ban.
• reason (string): Reason for the ban.
• deleteMessageDays (number, optional): Days of their messages to delete, 0-7 (fractions allowed, e.g. 0.5 for 12 hours). Values outside 0-7 are clamped. Defaults to 0.

kick(userId, reason): boolean

Kicks a user from the guild. Returns false (rather than failing the script) if they had already left.

• userId (string): Discord snowflake ID of the user to kick.
• reason (string): Reason for the kick.

timeout(userId, reason, durationMinutes): boolean

Times out a user in the guild. Returns false (rather than failing the script) if they had already left. The duration is in minutes but may be fractional, so parseDuration("30s") (0.5) works; Discord's maximum is 28 days (40320 minutes), and a longer value throws. 0 ends a timeout, like untimeout().

• userId (string): Discord snowflake ID of the user to time out.
• reason (string): Reason for the timeout.
• durationMinutes (number): Duration in minutes (fractions allowed, up to 40320).

unban(userId, reason): boolean

Unbans a user from the guild. Returns false (rather than failing the script) if they weren't banned.

• userId (string): Discord snowflake ID of the user to unban.
• reason (string): Reason for the unban.

untimeout(userId, reason): boolean

Clears a member's timeout early. Prefer this over timeout(userId, reason, 0): both end the timeout, but only this clears the expiry, so the member stops reading as timed-out in ctx.member.timeoutUntil and in Discord's UI.

• userId (string): Discord snowflake ID of the member.
• reason (string): Audit log reason.

getBans(limit?): BanSummary[]

Returns the server's ban list (userId, username, displayName, reason), newest first. Live REST read.

• limit (number, optional): How many to return (1-1000; defaults to 100).

isBanned(userId): boolean

Whether a user is currently banned from the server. Cheaper and clearer than scanning getBans(). Live REST read.

• userId (string): Discord snowflake ID of the user.

bulkBan(userIds, deleteMessageSeconds?, reason?): BulkResult

Bans up to 200 users in one call, the raid-cleanup primitive: far faster than 200 ban() calls. Returns who was banned and who couldn't be (already banned, or above Mallard in the role list).

• userIds (string[]): Up to 200 user IDs.
• deleteMessageSeconds (number, optional): Seconds of their messages to delete (0-604800, i.e. up to 7 days). Defaults to 0.
• reason (string, optional): Audit log reason.

pauseInvites(hours, reason?): void

Pauses joining through invites for up to 24 hours (Discord's own raid-mode switch, shown to members as "invites paused"). 0 resumes them. The other pause (DMs) is left as it is.

• hours (number): How long to pause (0-24; fractions allowed). 0 resumes.
• reason (string, optional): Audit log reason.

pauseDms(hours, reason?): void

Stops members who aren't friends DMing each other through the server for up to 24 hours, which cuts off a raid's DM spam. 0 resumes. Moderators and bots are unaffected.

• hours (number): How long to pause (0-24; fractions allowed). 0 resumes.
• reason (string, optional): Audit log reason.

setVerificationLevel(level, reason?): void

Changes the server's verification level, raid mode's other half: "high" makes new accounts wait 10 minutes in the server before talking.

• level (string): "none", "low", "medium", "high" or "veryHigh".
• reason (string, optional): Audit log reason.

getAuditLog(query?): AuditLogEntry[]

Reads recent audit-log entries, newest first: who banned someone, who deleted a channel. Filter with { actionType: "GuildUserBanAdd", userId, targetId, limit }.

• query ({ actionType?: string, userId?: string, targetId?: string, limit?: number }, optional): actionType uses the names in AuditLogEntry.actionType; userId is who acted; limit is 1-100 (default 25).

canModerate(userId): boolean

Whether Mallard can act on a member at all: they aren't the owner, and their highest role sits below Mallard's. Check it before ban/kick/timeout/role changes to give a clear message instead of a failed call.

• userId (string): Discord snowflake ID of the member.

setSlowmode(channelId, seconds, reason?): void

Sets the slowmode delay for a channel.

• channelId (string): Discord snowflake ID of the channel.
• seconds (number): Slowmode delay in seconds (0 to disable, up to 21600).
• reason (string, optional): Audit log reason.

getForumTags(channelId): ForumTag[]

Returns the tags defined on a forum or media channel, meaning the set a post can be tagged with, resolved to id/name/emoji. Pair with ctx.thread.tags (the tags actually applied to a new post) on a ThreadCreate script, or call it from any trigger. Live read (not cached); throws if the channel is not a forum/media channel.

• channelId (string): Discord snowflake ID of the forum or media channel.

createChannel(name, type, parentIdOrOptions?, topic?, reason?): string

Creates a channel in the guild and returns its snowflake ID. Pass an options object as the third argument to set everything at once, including permission overwrites, which is how a private ticket channel is made in a single step: createChannel("ticket-42", "text", { parentId, overwrites: [{ targetId: ctx.guildId, deny: ["ViewChannel"] }, { targetId: ctx.actorId, targetIsRole: false, allow: ["ViewChannel", "SendMessages"] }] }).

• name (string): Name for the new channel.
• type (string): Channel kind: "text", "voice", "category", "announcement", "forum", "media", or "stage".
• parentIdOrOptions (string | ChannelOptions, optional): Category ID to nest under (empty for none), or an options object: {parentId, topic, position, nsfw, slowmode, userLimit, bitrate, overwrites: [{targetId, targetIsRole?, allow?, deny?}]}.
• topic (string, optional): Channel topic/description (empty for none).
• reason (string, optional): Audit log reason.

deleteChannel(channelId, reason?): void

Deletes a channel (or thread) in the guild.

• channelId (string): Discord snowflake ID of the channel to delete.
• reason (string, optional): Audit log reason.

modifyChannel(channelId, nameOrOptions, topic?, reason?): void

Changes a channel. The short form renames and/or re-topics it: an empty name leaves the name alone, while an empty topic CLEARS the topic (pass null or omit it to leave the topic alone). Pass an options object as the second argument to change anything else: modifyChannel(id, { parentId, position, userLimit, bitrate, nsfw, slowmode, syncPermissions: true }). Works on threads too (name, slowmode, autoArchiveMinutes).

• channelId (string): Discord snowflake ID of the channel.
• nameOrOptions (string | ChannelOptions): New name (empty to leave unchanged), or an options object: {name, topic, parentId, position, nsfw, slowmode, userLimit, bitrate, syncPermissions, autoArchiveMinutes}.
• topic (string | null, optional): New topic (empty to clear, null/omitted to keep).
• reason (string, optional): Audit log reason.

setChannelTopic(channelId, topic, reason?): void

Sets a channel's topic/description.

• channelId (string): Discord snowflake ID of the channel.
• topic (string): The new topic (empty to clear).
• reason (string, optional): Audit log reason.

listChannels(): ChannelSummary[]

Lists the guild's cached channels (id, name, type, category, position; no threads). Cheap cached read (no REST), like listMembers. type and parentId fill in when the bot next reconnects for channels cached before this field existed.

renameChannel(channelId, name, reason?): void

Renames a channel or category. Does nothing when the channel already has that name, so a scheduled rename (a member-count channel, say) doesn't spend Discord's limit of about 2 renames per 10 minutes per channel.

• channelId (string): Discord snowflake ID of the channel or category.
• name (string): The new name.
• reason (string, optional): Audit log reason.

getChannel(channelId): ChannelInfo | null

Returns one channel's detail (name, type, topic, parent, position, nsfw, slowmode, user limit, bitrate), or null when it doesn't exist. Read from the bot's channel cache, which gateway events keep current; a REST read only for a channel the cache hasn't fully recorded yet.

• channelId (string): Discord snowflake ID of the channel.

setChannelPermission(channelId, targetId, allow, deny, reason?, targetIsRole?): boolean

Sets or clears one permission overwrite on a channel: the primitive behind a lockdown or raid-mode script, since slowmode alone cannot stop posting. Permissions named in neither list are left to inherit. Passing BOTH lists empty removes the overwrite entirely, which is how a lockdown is lifted, and is different from denying nothing. To lock a channel, deny ["SendMessages"] for the @everyone role, whose ID is the server's own ID (ctx.guildId).

• channelId (string): Discord snowflake ID of the channel.
• targetId (string): Role ID (or user ID when targetIsRole is false). Use ctx.guildId for @everyone.
• allow (string[]): Permission names to explicitly allow, e.g. ["SendMessages"]. Empty for none. Discord's own spelling ("SEND_MESSAGES") works too.
• deny (string[]): Permission names to explicitly deny. Empty for none.
• reason (string, optional): Audit log reason.
• targetIsRole (boolean, optional): True (the default) when targetId is a role; false for a per-member overwrite.

getEmojis(): EmojiSummary[]

Returns the server's custom emoji (id, name, animated, available, mention, imageUrl). The mention field is the "<:name:id>" form you paste into message content. Live REST read.

deleteEmoji(emojiId, reason?): boolean

Deletes a custom emoji from the server.

• emojiId (string): Discord snowflake ID of the emoji.
• reason (string, optional): Audit log reason.

getChannelPermissions(channelId): PermissionOverwrite[]

Lists a channel's permission overwrites: which roles and members are explicitly allowed or denied what. Useful to check whether a channel is locked, or to copy its permissions.

• channelId (string): The channel.

setVoiceStatus(channelId, status): void

Sets the status line shown under a voice channel's name (up to 500 characters), e.g. "🎮 Game night". Empty clears it.

• channelId (string): The voice channel.
• status (string): The status text (empty to clear).

createEmoji(name, mediaId, reason?): EmojiSummary

Creates a custom emoji from an image on the server's Media page (PNG, JPEG, WebP or GIF, 256 KB at most) and returns it. Only the Media page is a source: Mallard never fetches an arbitrary URL for this.

• name (string): Emoji name (2-32 letters, numbers or underscores).
• mediaId (string): ID of an image on the Media page.
• reason (string, optional): Audit log reason.

getIntegrations(): IntegrationSummary[]

Lists the server's integrations: bots, Twitch/YouTube subscription roles and other connections. Pair with the GuildIntegrationsUpdate trigger.

startStage(channelId, topic, options?): string

Starts a stage in a stage channel with a topic and returns the stage instance's ID. options.notify pings @everyone that the stage started.

• channelId (string): The stage channel.
• topic (string): What the stage is about (1-120 characters).
• options ({ notify?: boolean }, optional): Extras.

modifyStage(channelId, topic): void

Changes the topic of a live stage.

• channelId (string): The stage channel.
• topic (string): The new topic.

endStage(channelId): boolean

Ends the live stage in a stage channel.

• channelId (string): The stage channel.

setForumTags(threadId, tagIds, reason?): void

Replaces the forum tags applied to a forum/media post. tagIdsJson is a JSON array of tag ID strings (e.g. from getForumTags or ctx.thread.tags); an empty array clears all tags.

• threadId (string): Discord snowflake ID of the forum post (thread).
• tagIds (string[] | string): Tag IDs to apply, as an array or a JSON array string.
• reason (string, optional): Audit log reason.

archiveThread(threadId, archived, reason?): void

Archives or unarchives a thread / forum post.

• threadId (string): Discord snowflake ID of the thread.
• archived (boolean): true to archive, false to unarchive.
• reason (string, optional): Audit log reason.

lockThread(threadId, locked, reason?): void

Locks or unlocks a thread / forum post (locked threads can't get new messages).

• threadId (string): Discord snowflake ID of the thread.
• locked (boolean): true to lock, false to unlock.
• reason (string, optional): Audit log reason.

deleteThread(threadId, reason?): void

Deletes a thread / forum post.

• threadId (string): Discord snowflake ID of the thread to delete.
• reason (string, optional): Audit log reason.

createThread(channelId, name, isPrivate, userIds?, initialMessage?, options?): string

Creates a thread under a channel, optionally adding initial members and an opening message. Returns the created thread's snowflake ID. On a forum or media channel this creates a post, using initialMessage (or the name, when empty) as its body; createForumPost() gives more control there. To start a thread from an existing message, use createThreadFromMessage().

• channelId (string): Discord snowflake ID of the parent channel.
• name (string): Thread name.
• isPrivate (boolean): Create a private thread.
• userIds (string | string[], optional): User IDs to add, as an array or a comma-separated string (empty for none).
• initialMessage (string, optional): Message posted into the thread after creation, or empty string.
• options ({ autoArchiveMinutes?: number, slowmode?: number, tagIds?: string[], reason?: string }, optional): autoArchiveMinutes is 60, 1440, 4320 or 10080; tagIds applies to forum posts.

addThreadMember(threadId, userId): void

Adds a user to a thread.

• threadId (string): Discord snowflake ID of the thread.
• userId (string): Discord snowflake ID of the user.

removeThreadMember(threadId, userId): void

Removes a user from a thread.

• threadId (string): Discord snowflake ID of the thread.
• userId (string): Discord snowflake ID of the user.

createForumPost(forumId, title, content, options?): string

Creates a post in a forum or media channel and returns its thread ID. The body is a string or a MessageOptions object, so a post can carry embeds, buttons and files; options.tagIds applies forum tags (see getForumTags()).

• forumId (string): The forum or media channel.
• title (string): The post title.
• content (string | MessageOptions): The opening message.
• options ({ tagIds?: string[], autoArchiveMinutes?: number, slowmode?: number, reason?: string }, optional): Extras.

createThreadFromMessage(channelId, messageId, name, options?): string

Starts a thread from an existing message (the "Create Thread" item on a message) and returns the thread ID. Auto-thread every post in a channel from a MessageCreate script.

• channelId (string): The channel the message is in.
• messageId (string): The message to start from.
• name (string): Thread name (1-100 characters).
• options ({ autoArchiveMinutes?: number, slowmode?: number, reason?: string }, optional): Extras.

listActiveThreads(parentId?): ThreadSummary[]

Lists the server's active (unarchived) threads and forum posts, optionally only those under one channel. For stale-ticket sweeps and forum housekeeping.

• parentId (string, optional): Only threads in this channel or forum.

getThreadMembers(threadId): string[]

Returns the user IDs who have joined a thread (up to 1000).

• threadId (string): The thread.

sendMessage(channelId, content, embeds?, buttons?, pings?, replyToMessageId?): string

Sends a message to a channel and returns its ID, so you can edit, pin or react to it later (store the ID in the KV store for a panel you keep updated). Pass embeds and/or buttons to attach them; both are plain arrays, no JSON.stringify needed. For select menus, files, stickers or @silent, pass a MessageOptions object as the second argument instead of the content: sendMessage(channelId, { content, selects, files, silent: true }).

• channelId (string): Discord snowflake ID of the channel.
• content (string | MessageOptions): Message content (empty string for embed-only), or a MessageOptions object carrying everything.
• embeds (EmbedData[], optional): Up to 10 embeds. A single embed object is also accepted.
• buttons (ButtonData[], optional): Buttons to attach, up to 25 (5 per row).
• pings (boolean, optional): Whether @mentions in the content actually notify (ping). Defaults to true; pass false to send a silent mention (still shows as a tag, no notification).
• replyToMessageId (string, optional): Send this as a reply to a message in the same channel. If that message has since been deleted, the message still posts, just without the reply. To repost a message elsewhere instead, use forwardMessage.

sendEmbed(channelId, title, description, colorArgb?): string

Sends a single embed to a channel, as a shorthand for sendMessage with one embed object, and returns the message ID. The description is the body text and is required, since Discord rejects an embed carrying neither a title nor a description; pass an empty string as the title for none. colorArgb is the stripe down the left edge as a decimal number (e.g. 15548997 for red). For several embeds, fields, an author or footer, a timestamp or an image, use sendMessage.

• channelId (string): Discord snowflake ID of the channel.
• title (string): Embed title (empty string for none).
• description (string): Embed body text.
• colorArgb (number, optional): Colour as a decimal number (omit for none).

forwardMessage(sourceChannelId, messageId, targetChannelId): string

Forwards an existing message into another channel, the same way the Discord client's Forward does: the original is shown as a snapshot, with no content of your own attached. Returns the forward's message ID. Both channels must belong to this guild. Discord refuses to forward polls, calls, and system messages, and refuses any message whose content the bot can't read (error 160014); either ends the script unless caught, so guard with getMessage first if the source might be gone. To add a comment, send it as a separate sendMessage.

• sourceChannelId (string): Discord snowflake ID of the channel holding the message to forward (must be in this guild).
• messageId (string): Discord snowflake ID of the message to forward.
• targetChannelId (string): Discord snowflake ID of the channel to forward it into (must be in this guild).

forwardDm(targetChannelId): string

Forwards the DM that triggered this script into one of this guild's channels or threads, exactly as the Discord client's Forward does: the original appears as a snapshot carrying its text, attachments and embeds, so nothing has to be copied or re-linked. Returns the forward's message ID. DirectMessageCreate only, and it deliberately takes no source arguments: the DM being forwarded is always the one that triggered the run. Like forwardMessage it carries no content of its own (Discord refuses that, error 160011), so send the details embed and any buttons as a separate sendMessage. A target thread that has been deleted or archived fails the call, which ends the script unless you catch it.

• targetChannelId (string): Discord snowflake ID of the channel or thread to forward the DM into (must be in this guild).

sendDm(userId, content, embeds?, buttons?, pings?): boolean

Sends a direct message to a member of this server. DMs always carry an embed attributing them to this server. Only current members can be messaged (DM before you kick or ban, as the seeded /ban does); anyone else returns false. Whether a user accepts DMs is their own privacy setting, so a refused DM also returns false rather than failing the script. Check the result if you want to say so.

• userId (string): Discord snowflake ID of the user.
• content (string | MessageOptions): Message content (empty string for embed-only), or a MessageOptions object.
• embeds (EmbedData[], optional): Up to 10 embeds. A single embed object is also accepted.
• buttons (ButtonData[], optional): Buttons to attach, up to 25 (5 per row).
• pings (boolean, optional): Whether @mentions in the content actually notify (ping). Defaults to true; pass false to send a silent mention.

editResponse(content, embeds?, buttons?, pings?): stringinteraction triggers only

Edits the bot's reply to the interaction and returns its message ID. The reply is already showing a "thinking…" state by the time the script runs, so this fills it in. Each call fully replaces the message: embeds and buttons you don't pass are removed. Whether only the invoking user sees it is the script's Ephemeral setting. On a button/select trigger set to "Update the clicked message", there is no new reply: this rewrites the message the button or menu sits on (pagination, toggles). For a second message, use followUp().

• content (string | MessageOptions): Message content (empty string for embed-only), or a MessageOptions object.
• embeds (EmbedData[], optional): Up to 10 embeds. A single embed object is also accepted.
• buttons (ButtonData[], optional): Buttons to attach, up to 25 (5 per row).
• pings (boolean, optional): Whether @mentions in the content actually notify (ping). Defaults to true; pass false to send a silent mention.

sendWebhookMessage(channelId, username, avatarUrl, content, embeds?, pings?, options?): string

Sends a message through a channel webhook with a custom username and avatar (persona messages) and returns its ID, which editWebhookMessage()/deleteWebhookMessage() take. The webhook is created on first use and belongs to Mallard, so its messages can carry buttons and select menus like any other. channelId may be a thread, in which case the webhook is created on its parent channel and the message is posted into the thread; to start a new forum post instead, pass the forum's ID with options.threadName.

• channelId (string): Discord snowflake ID of the channel, or a thread.
• username (string): Display name for the webhook message.
• avatarUrl (string): Avatar image URL (empty string for the default).
• content (string): Message content.
• embeds (EmbedData[], optional): Up to 10 embeds. A single embed object is also accepted.
• pings (boolean, optional): Whether @mentions in the content actually notify (ping). Defaults to true; pass false to send a silent mention.
• options ({ threadName?: string, tagIds?: string[], buttons?: ButtonData[], selects?: SelectMenuData[], files?: FileData[], silent?: boolean }, optional): Extras: threadName (with a forum channelId) starts a new post, tagIds tags it, plus components, files and @silent.

sendPoll(channelId, question, answers, durationHours?, allowMultiselect?): string

Sends a native Discord poll to a channel and returns its message ID (what endPoll() and getPollResults() take). answers is an array of 1-10 answers, each a string or { text, emoji }; a JSON array string still works.

• channelId (string): Discord snowflake ID of the channel.
• question (string): The poll question.
• answers ((string | { text: string, emoji?: string })[] | string): The answers (1-10).
• durationHours (number, optional): How long the poll runs, in hours (1-768; defaults to 24).
• allowMultiselect (boolean, optional): Whether voters can pick multiple answers. Defaults to false.

endPoll(channelId, messageId): void

Immediately closes a poll the bot posted.

• channelId (string): Discord snowflake ID of the channel.
• messageId (string): Discord snowflake ID of the poll message.

followUp(content, options?): stringinteraction triggers only

Sends an additional message to the interaction, after the first reply, and returns its ID. Unlike editResponse() it can be ephemeral or public whatever the script's Ephemeral setting: followUp("Only you can see this", { ephemeral: true }). Up to 15 minutes after the interaction.

• content (string | MessageOptions): Content, or a MessageOptions object.
• options (MessageOptions, optional): Extras when content is a string, e.g. { ephemeral: true, embeds }.

deleteResponse(): voidinteraction triggers only

Deletes the interaction's reply (the "thinking…" message or what editResponse() put there), e.g. when the real result went out as a followUp() or a channel message. On an "Update the clicked message" trigger this deletes the clicked message itself.

triggerTyping(channelId): void

Shows "Mallard is typing…" in a channel for about 10 seconds, or until the next message it sends. Cosmetic, for replies that take a while (an AI call through fetch()).

• channelId (string): Discord snowflake ID of the channel.

editWebhookMessage(channelId, messageId, content, embeds?): void

Edits a message sendWebhookMessage() posted. Like editMessage it replaces the message wholesale.

• channelId (string): The channel (or thread) it was posted in.
• messageId (string): The ID sendWebhookMessage() returned.
• content (string | MessageOptions): New content, or a MessageOptions object.
• embeds (EmbedData[], optional): Replacement embeds.

deleteWebhookMessage(channelId, messageId): boolean

Deletes a message sendWebhookMessage() posted.

• channelId (string): The channel (or thread) it was posted in.
• messageId (string): The ID sendWebhookMessage() returned.

getStickers(): StickerSummary[]

Returns the server's stickers, whose IDs MessageOptions.stickerIds takes. Live REST read.

getMessage(channelId, messageId): CachedMessage | null

Fetches a single message, or null if it no longer exists. A message the bot saw in the last 3 hours comes from its message cache; anything older, and any poll, is fetched live over REST, and that call's time counts toward the run like any other. The returned message's reactions field is a per-emoji count/me summary (see getReactionUsers for who reacted). The channel must belong to this guild.

• channelId (string): Discord snowflake ID of the channel (must be in this guild).
• messageId (string): Discord snowflake ID of the message.

getMessages(channelId, max?, options?): CachedMessage[]

Fetches a channel's messages from Discord live over REST, newest first (up to 100 per call). With no options it returns the most recent ones; pass { before: messageId } to page further back, { after: messageId } to get newer ones, or { around: messageId } for context around a message. Each message's reactions field is a per-emoji count/me summary. The channel must belong to this guild.

• channelId (string): Discord snowflake ID of the channel (must be in this guild).
• max (number, optional): Maximum messages to return (1-100; defaults to 100).
• options ({ before?: string, after?: string, around?: string }, optional): Page from a message ID instead of the newest message.

deleteMessage(channelId, messageId, reason?): boolean

Deletes a single message. Returns false (rather than failing the script) if it was already gone.

• channelId (string): Discord snowflake ID of the channel.
• messageId (string): Discord snowflake ID of the message.
• reason (string, optional): Audit log reason.

bulkDelete(channelId, count, reason?): number

Deletes the most recent N messages in a channel (1-100) and returns how many went. Messages older than 14 days are deleted individually, which is slower. To delete only some (one user's, or ones containing a word), use purge().

• channelId (string): Discord snowflake ID of the channel.
• count (number): Number of recent messages to delete (1-100).
• reason (string, optional): Audit log reason.

addReaction(channelId, messageId, emoji): void

Adds a reaction to a message as the bot. Emoji is a unicode emoji ("🦆") or a custom emoji as "name:id".

• channelId (string): Discord snowflake ID of the channel.
• messageId (string): Discord snowflake ID of the message.
• emoji (string): Unicode emoji or custom emoji as "name:id".

removeReaction(channelId, messageId, emoji, userId?): void

Removes reactions for an emoji from a message: one user's reaction when userId is set, or every user's reaction for that emoji when userId is empty or omitted.

• channelId (string): Discord snowflake ID of the channel.
• messageId (string): Discord snowflake ID of the message.
• emoji (string): Unicode emoji or custom emoji as "name:id".
• userId (string, optional): User whose reaction to remove, or empty/omitted for all users.

clearReactions(channelId, messageId): void

Removes every reaction from a message.

• channelId (string): Discord snowflake ID of the channel.
• messageId (string): Discord snowflake ID of the message.

getReactionUsers(channelId, messageId, emoji, max?, options?): string[]

Returns the user IDs who reacted to a message with a specific emoji, up to 1000 per call (paged from Discord 100 at a time), which is enough for most giveaways; pass { after: lastUserId } to continue past that. Discord's endpoint is per-emoji, so read the emoji list off getMessage()'s reactions summary first. The channel must belong to this guild.

• channelId (string): Discord snowflake ID of the channel.
• messageId (string): Discord snowflake ID of the message.
• emoji (string): Unicode emoji or custom emoji as "name:id".
• max (number, optional): Maximum users to return (1-1000; defaults to 100).
• options ({ after?: string, burst?: boolean }, optional): after: continue from this user ID; burst: list super-reactions instead of normal ones.

pinMessage(channelId, messageId, reason?): void

Pins a message in its channel.

• channelId (string): Discord snowflake ID of the channel.
• messageId (string): Discord snowflake ID of the message.
• reason (string, optional): Audit log reason.

unpinMessage(channelId, messageId, reason?): void

Unpins a message in its channel.

• channelId (string): Discord snowflake ID of the channel.
• messageId (string): Discord snowflake ID of the message.
• reason (string, optional): Audit log reason.

publishMessage(channelId, messageId): void

Publishes (crossposts) a message in an announcement channel.

• channelId (string): Discord snowflake ID of the announcement channel.
• messageId (string): Discord snowflake ID of the message.

editMessage(channelId, messageId, content, embeds?, buttons?, pings?): void

Edits a message the bot previously sent in a channel (keep the ID sendMessage returned). The edit fully replaces the message: embeds, buttons and menus you don't pass are removed. Pass a MessageOptions object as the third argument for select menus or files.

• channelId (string): Discord snowflake ID of the channel.
• messageId (string): Discord snowflake ID of the message to edit.
• content (string | MessageOptions): New message content (empty string for embed-only), or a MessageOptions object.
• embeds (EmbedData[], optional): Up to 10 embeds. A single embed object is also accepted.
• buttons (ButtonData[], optional): Buttons to attach, up to 25 (5 per row).
• pings (boolean, optional): Whether @mentions in the new content notify. Defaults to true.

getPins(channelId): PinnedMessage[]

Returns a channel's pinned messages (id, channelId, authorId, content). Live REST read.

• channelId (string): Discord snowflake ID of the channel.

searchMessages(query): SearchResult

Searches the whole server's message history, the way Discord's search bar does: by text, author, channel, mention, or what the message has (links, files, images, embeds, polls). Returns up to 25 matches per call plus the total. Discord builds the search index lazily, so a server that has never been searched may first throw "still indexing"; catch it and try again later.

• query (SearchQuery): {content?, authorId?, channelId?, mentions?, has?: "link"|"file"|"image"|"video"|"embed"|"poll"|"sticker", pinned?, sortBy?: "timestamp"|"relevance", limit? (1-25), offset?}

purge(channelId, options): number

Deletes recent messages in a channel that match a filter, the classic /purge: purge(channelId, { count: 50, authorId }) removes that user's last 50. Scans back through up to 500 recent messages to find up to count matches (1-100). Returns how many were deleted.

• channelId (string): Discord snowflake ID of the channel.
• options (PurgeOptions): {count, authorId?, contains?, bots? (only bot/webhook messages), attachments? (only ones with files), before?, reason?}

deleteMessages(channelId, messageIds, reason?): number

Deletes specific messages from one channel in as few calls as possible (Discord's bulk delete for anything under 14 days old, one by one otherwise). Returns how many were deleted; IDs already gone are skipped.

• channelId (string): Discord snowflake ID of the channel.
• messageIds (string[]): Up to 100 message IDs.
• reason (string, optional): Audit log reason.

getPollResults(channelId, messageId): PollData | null

Reads a poll's current counts per answer (exact once isFinalized is true).

• channelId (string): Discord snowflake ID of the channel.
• messageId (string): The poll message's ID.

getPollVoters(channelId, messageId, answerId, max?): string[]

Returns the user IDs who voted for one poll answer (up to 1000).

• channelId (string): Discord snowflake ID of the channel.
• messageId (string): The poll message's ID.
• answerId (number): The answer's id (see getPollResults()).
• max (number, optional): Maximum voters to return (1-1000; defaults to 100).

hasRole(userId, roleId): boolean

Returns true when the user currently has the given role. Backed by the bot's guild-member cache (loaded from the gateway whenever the bot connects and kept live by member events); a user not in the cache returns false.

• userId (string): Discord snowflake ID of the user to check.
• roleId (string): Discord snowflake ID of the role. An empty string returns false rather than throwing, so an unconfigured role ID (e.g. from ctx.env) can be checked safely.

listMembers(afterUserId?, limit?): MemberSummary[]

Returns a page of cached guild members ordered by user ID. The member cache is loaded in full from the gateway whenever the bot connects and kept live by member events (requires the bot's Server Members privileged intent). Page with the last userId of the previous call.

• afterUserId (string, optional): Return members with a user ID greater than this; empty or omitted starts from the beginning.
• limit (number, optional): Page size (1-500; defaults to 100).

hasPermission(userId, permission): boolean

Whether a member holds a server-level permission, computed the way Discord does: the @everyone role plus every role they hold, with Administrator and server ownership each granting everything. Use this instead of hard-coding moderator role IDs. NOTE: this is server-level and does NOT apply channel permission overwrites, so it answers "may they do this in general", not "may they do this in #channel" (hasChannelPermission() does that). Like hasRole(), an uncached member returns false.

• userId (string): Discord snowflake ID of the member.
• permission (string): Permission name, e.g. "ManageMessages", "BanMembers", "KickMembers", "ModerateMembers", "ManageRoles", "ManageChannels", "Administrator". Discord's own spelling ("BAN_MEMBERS") works too.

createInvite(channelId, maxAgeSeconds, maxUses, temporary, reason?, options?): InviteSummary

Creates an invite to a channel and returns it. options.roleIds makes it a community invite that gives those roles to whoever joins with it.

• channelId (string): Channel the invite should point at.
• maxAgeSeconds (number): Lifetime in seconds (0 = never expires).
• maxUses (number): Use limit (0 = unlimited).
• temporary (boolean): Whether joiners get temporary membership (kicked on disconnect unless given a role).
• reason (string, optional): Audit log reason.
• options ({ roleIds?: string[], unique?: boolean }, optional): roleIds: roles granted on join; unique: always mint a new code.

deleteInvite(code, reason?): boolean

Revokes one of this server's invites by its code. An invite belonging to another server is refused.

• code (string): The invite code (the part after discord.gg/).
• reason (string, optional): Audit log reason.

getInvites(): InviteSummary[]

Returns the server's active invites, including how many times each has been used. This is the only way to read a use count, and Discord only reports uses when Mallard has the Manage Server permission (without it every uses is 0). To attribute a join, ctx.member.inviteCode on GuildMemberAdd is simpler. Live REST read.

getMember(userId): MemberSummary | null

Returns one cached guild member (userId, username, displayName, nickname, avatarUrl, joinedAt, roleIds), or null if not cached. Cheap cached read, no REST. For the user who triggered the script, ctx.actor already holds this, so no call is needed.

• userId (string): Discord snowflake ID of the member.

listRoles(): RoleSummary[]

Lists the guild's cached roles (id + name). Cheap cached read (no REST).

setNickname(userId, nickname, reason?): void

Sets or clears a member's nickname (empty string resets it to their username).

• userId (string): Discord snowflake ID of the member.
• nickname (string): The new nickname (empty to reset).
• reason (string, optional): Audit log reason.

moveMember(userId, channelId, reason?): void

Moves a member to a voice channel (they must already be connected to voice).

• userId (string): Discord snowflake ID of the member.
• channelId (string): Voice channel to move them into.
• reason (string, optional): Audit log reason.

disconnectMember(userId, reason?): void

Disconnects a member from voice.

• userId (string): Discord snowflake ID of the member.
• reason (string, optional): Audit log reason.

muteMember(userId, muted, reason?): void

Server-mutes or unmutes a member in voice.

• userId (string): Discord snowflake ID of the member.
• muted (boolean): true to mute, false to unmute.
• reason (string, optional): Audit log reason.

deafenMember(userId, deafened, reason?): void

Server-deafens or undeafens a member in voice.

• userId (string): Discord snowflake ID of the member.
• deafened (boolean): true to deafen, false to undeafen.
• reason (string, optional): Audit log reason.

getUser(userId): UserSummary | null

Looks up any Discord user by ID, member of this server or not: name, avatar, account age. Live REST read.

• userId (string): Discord snowflake ID of the user.

fetchMember(userId): MemberContext | null

Reads a member live from Discord rather than the member cache, with every field (boost, timeout, pending, flags). For a member getMember() doesn't have yet, or when those fields matter. Null when they aren't in the server.

• userId (string): Discord snowflake ID of the member.

searchMembers(query, limit?): MemberSummary[]

Finds members whose username or nickname starts with the query, e.g. for a text command that takes a name.

• query (string): The start of a username or nickname.
• limit (number, optional): Maximum to return (1-100; defaults to 25).

getMembersWithRole(roleId, limit?): MemberSummary[]

Lists cached members who hold a role, e.g. to strip a role from everyone or count staff. Cache read, no REST.

• roleId (string): Discord snowflake ID of the role.
• limit (number, optional): Maximum to return (1-1000; defaults to 100).

getVoiceMembers(channelId): VoiceMember[]

Lists who is in a voice or stage channel right now, from the live voice-state cache. The basis for join-to-create channels (delete when empty), voice XP and event attendance.

• channelId (string): The voice or stage channel.

getVoiceState(userId): VoiceMember | null

Where a member is in voice right now, or null when they aren't connected.

• userId (string): Discord snowflake ID of the member.

hasChannelPermission(userId, channelId, permission): boolean

Whether a member holds a permission in one specific channel, applying the channel's overwrites the way Discord does (roles, then @everyone and member overwrites). The per-channel counterpart of hasPermission().

• userId (string): Discord snowflake ID of the member.
• channelId (string): The channel.
• permission (string): Permission name, e.g. "SendMessages", "ViewChannel".

setBotProfile(options): { nickname: string, avatarUrl: string }

Changes how Mallard looks in this server only: nickname, avatar, banner and bio. Seasonal avatars on a cron schedule, or branding per event. Images come from the server's Media page. Pro and Ultra only, at most once every 10 minutes; the audit log names the script. Pass nick: "" to go back to the bot's own name.

• options ({ nick?: string, avatarMediaId?: string, bannerMediaId?: string, bio?: string }): Only what you pass changes. nick up to 32 characters, bio up to 190; image IDs from the Media page.

hasAi(): boolean

Returns true if the guild has an OpenRouter AI integration configured on the Integrations page.

aiChat(promptOrOptions, options?): AiChatResponse

Sends a chat completion request to OpenRouter using the server's configured OpenRouter API key. Pass a prompt string or an options object ({ prompt, messages, model, maxTokens, temperature, reasoning, webSearch, webFetch, datetime, imageGen, advisor, subagent, tools, timeoutMs }). Default server tools configured on the Integrations page run automatically unless overridden with shorthand boolean flags (e.g. webSearch: false) or tools: []. Returns { content, text, model, finishReason, usage }.

• promptOrOptions (string | AiChatOptions): A prompt string, or an options object specifying messages, model, tools, or limits.
• options (AiChatOptions, optional): Optional options object when the first parameter is a prompt string.

fetch(url, options?): FetchResponse

Performs an HTTP request to an external API or feed and returns {status, headers, body} (body is a string, so parse JSON/XML yourself). Restrictions: https only (http via "fetch_allow_http" in the env record), standard ports only, GET/POST/PUT/PATCH/DELETE/HEAD only, 5s default timeout (up to 30s via options.timeoutMs), 1 MB response cap, 30 requests/minute per guild plus an hourly budget (see ctx.fetchCallsRemaining), and private/internal addresses are blocked. options is an object or JSON string: {method, headers (accept, content-type, authorization, user-agent, client-id, api-key, anthropic-version, and any "x-*" header; user-agent defaults to MallardBot/1.0), body, timeoutMs}. HEAD returns an empty body, handy for checking a URL exists. Any "{{secret:NAME}}" placeholder from ctx.secret (admin-only) in the url, a header value, or the body is replaced with the real secret just before the request is sent.

• url (string): Absolute https URL to request.
• options (object | string, optional): Request options ({method, headers, body, timeoutMs}), as an object or JSON string, or omitted for a plain GET.

addRole(userId, roleId, reason?): void

Adds a role to a guild member.

• userId (string): Discord snowflake ID of the user.
• roleId (string): Discord snowflake ID of the role.
• reason (string, optional): Audit log reason.

removeRole(userId, roleId, reason?): void

Removes a role from a guild member.

• userId (string): Discord snowflake ID of the user.
• roleId (string): Discord snowflake ID of the role.
• reason (string, optional): Audit log reason.

createRole(name, colorArgb?, hoist?, mentionable?, reason?): RoleInfo

Creates a role and returns it. The new role has NO permissions: a script that could mint a permission it doesn't itself hold would be a privilege-escalation path, so permissions stay something a human sets in Discord.

• name (string): Role name.
• colorArgb (number, optional): Colour as a number (e.g. 0xED4245 / 15548997 for red). Omit for no colour.
• hoist (boolean, optional): Show the role separately in the member list.
• mentionable (boolean, optional): Let anyone @mention the role.
• reason (string, optional): Audit log reason.

modifyRole(roleId, name?, colorArgb?, hoist?, mentionable?, reason?): boolean

Renames or recolours a role. Omitted parameters are left unchanged. Permissions are not settable here, for the same reason as createRole().

• roleId (string): Discord snowflake ID of the role.
• name (string, optional): New name, or omit to keep it.
• colorArgb (number, optional): New colour as a number, or omit to keep it.
• hoist (boolean, optional): Show separately in the member list.
• mentionable (boolean, optional): Let anyone @mention it.
• reason (string, optional): Audit log reason.

deleteRole(roleId, reason?): boolean

Deletes a role from the server.

• roleId (string): Discord snowflake ID of the role.
• reason (string, optional): Audit log reason.

setRoles(userId, roleIds, reason?): boolean

Replaces a member's entire role set in one call. Prefer this over a loop of addRole() / removeRole(): those are one action each against the hourly budget and leave the member in visible intermediate states, whereas this is a single action and a single change. Roles Discord manages itself (bot and integration roles, the booster role) cannot be set and must be left in the list as they are.

• userId (string): Discord snowflake ID of the member.
• roleIds (string[]): The complete set of role IDs the member should end up with.
• reason (string, optional): Audit log reason.

getRole(roleId): RoleInfo | null

Reads one role live, with its permissions and position.

• roleId (string): Discord snowflake ID of the role.

getRoleMemberCounts(): Record<string, number>

How many members hold each role, straight from Discord without walking the member list. Keyed by role ID (@everyone is left out).

addRoleToMany(userIds, roleId, reason?): BulkResult

Adds one role to many members at once (up to 500), running the calls in parallel, which is far quicker than a loop of addRole(). Returns who got it and who didn't (left the server, or above Mallard).

• userIds (string[]): Members to give the role to.
• roleId (string): The role.
• reason (string, optional): Audit log reason.

removeRoleFromMany(userIds, roleId, reason?): BulkResult

Removes one role from many members at once (up to 500), in parallel. Pair with getMembersWithRole() to clear a role from everyone.

• userIds (string[]): Members to take the role from.
• roleId (string): The role.
• reason (string, optional): Audit log reason.

getKV(key, options?): string | null

Retrieves a value from the guild's key-value store. Reads don't lock, so two runs at once can read the same value and the later setKV() overwrites the earlier one. For counters use incrKV(); for any other read-modify-write use updateKV(), or pass { lock: true } here, which holds the key until this run ends so no other run can change it in between. The reserved system key "env" is not accessible here; read it through ctx.env instead.

• key (string): Key to look up.
• options ({ lock?: boolean }, optional): lock: take the key's lock before reading, for a safe read-modify-write.

setKV(key, value, ttlSeconds?): void

Stores a value in the guild's key-value store, overwriting any existing value. A string is stored as-is (it should be JSON, e.g. from JSON.stringify); any other value (object, array, number, boolean) is JSON-encoded for you. Written the moment this call returns, so it is visible to getKV right away and kept even if the script errors or times out afterward. The reserved system key "env" cannot be written (it is managed on the dashboard's Database page).

• key (string): Key to store under.
• value (any): A JSON string, or any value to be JSON-encoded.
• ttlSeconds (number, optional): Time-to-live in seconds; 0 or omitted for no expiry.

deleteKV(key): void

Deletes a key from the guild's key-value store. The reserved system key "env" cannot be deleted.

• key (string): Key to delete.

listKV(prefix?, limit?, afterKey?): string[]

Lists the server's stored keys, optionally only those starting with a prefix, in alphabetical order. Returns KEYS, not values: a store can run to megabytes, so getKV() the ones you want, or use listKVEntries()/getKVMany(). This is what makes namespaced keys ("warns:123") usable as a collection. Page past the limit with afterKey. Expired keys and the reserved "env" row are never listed.

• prefix (string, optional): Only keys starting with this. Empty or omitted lists everything.
• limit (number, optional): How many to return (1-1000; defaults to 100).
• afterKey (string, optional): Return keys after this one (the last key of the previous page).

updateKV(key, fn, ttlSeconds?): any

Safely read-modify-writes one key: takes the key's lock, calls fn with the current value (parsed from JSON, or null when missing), and stores what fn returns (undefined leaves it unchanged, null deletes it). No other run can change the key in between, so concurrent runs never lose each other's updates. Returns the stored value.

• key (string): Key to update.
• fn ((current: any) => any): Computes the new value from the current one.
• ttlSeconds (number, optional): Time-to-live for the new value (0 or omitted: none).

incrKV(key, by?, ttlSeconds?): number

Atomically adds to a number stored under a key (missing counts as 0) and returns the new total. The safe way to count: XP, message counts, ticket numbers.

• key (string): Key holding the number.
• by (number, optional): Amount to add (may be negative; defaults to 1).
• ttlSeconds (number, optional): Time-to-live to (re)apply (0 or omitted: keep none).

getKVMany(keys): Record<string, string | null>

Reads many keys in one call, e.g. every key listKV() returned. Missing keys come back null.

• keys (string[]): Up to 1000 keys.

ttlKV(key): number | null

How many seconds a key has left before it expires: null when it never expires, -1 when it doesn't exist.

• key (string): The key.

listKVEntries(prefix?, limit?, afterKey?): KvEntry[]

Like listKV() but returns each key's value and expiry too, for small collections (a leaderboard, a warn list) you'd otherwise read key by key.

• prefix (string, optional): Only keys starting with this.
• limit (number, optional): How many to return (1-500; defaults to 100).
• afterKey (string, optional): Return keys after this one.

log(...values): void

Logs a line. It appears in the run's trace on the Logs page: expand any execution to see your log output interleaved with the Discord, fetch and database calls the script made, in the order they happened. Takes any number of arguments like console.log, and objects and arrays are printed as JSON; console.log/info/warn/error work too (warn and error are marked as such). Traces are kept for 8 days and are visible to anyone with dashboard access to this server, so don't log anything you wouldn't want kept.

• ...values (any[]): What to log.

formatTimestamp(isoOrEpoch, style?, timeZone?): string

Turns an ISO 8601 timestamp (any of the ctx date fields), a Date or a unix-seconds number into Discord's timestamp markup, which renders in each reader's own timezone and language. This is the best way to show a time in a message: pass a timeZone to read what someone typed as their local time. No Discord call, so it costs nothing.

• isoOrEpoch (string): An ISO 8601 timestamp (e.g. ctx.member.joinedAt) or unix seconds.
• style (string, optional): One of t (short time), T (long time), d (short date), D (long date), f (short date+time), F (long date+time), R (relative, e.g. "3 hours ago"). Defaults to R.
• timeZone (string, optional): An IANA zone such as "Europe/London". With it, a time without an offset ("2026-10-02 20:00") or a phrase parseTime() understands ("fri 8pm", "tomorrow 9am") is read as local time there, so formatTimestamp(ctx.args.when, "F", "Europe/London") turns what an organiser typed into a time every reader sees in their own zone.

parseDuration(text): number

Parses a human duration into MINUTES, so it feeds straight into timeout(). Accepts a run of amount+unit pairs using s/m/h/d/w, e.g. "10m", "2h30m", "7d". A bare number is read as minutes. Seconds give a fraction ("30s" is 0.5), which timeout() accepts. Throws when it can't parse, so a bad slash-command argument fails loudly rather than timing someone out for the wrong span. Multiply by 60 for runLater()'s seconds. No Discord call.

• text (string): A duration such as "10m", "2h30m" or "7d".

snowflakeTime(id): string

Turns any Discord ID (user, message, channel) into the ISO 8601 time it was created. A user's ID gives their account age. No Discord call.

• id (string): A Discord snowflake ID.

randomInt(min, max): number

A cryptographically secure random whole number between min and max, both included. Use it instead of Math.random() for giveaways and anything people might dispute.

• min (number): Smallest possible result.
• max (number): Largest possible result.

randomUUID(): string

A random UUID (v4), for ticket IDs and unique keys.

base64Encode(text): string

Encodes text (as UTF-8) in base64, e.g. for a Basic auth header: "Basic " + base64Encode(user + ":" + pass). Up to 64 KB.

• text (string): The text.

base64Decode(text): string

Decodes base64 (standard or URL-safe, padding optional) back to UTF-8 text.

• text (string): Base64 text.

sha256(text): string

The SHA-256 hash of some text (UTF-8, up to 64 KB), as lowercase hex.

• text (string): The text.

hmacSha256(key, data, encoding?): string

Signs text with HMAC-SHA256, as signed APIs require. The key may be a secret placeholder (ctx.secret.MyKey): it's resolved on the server, so the real secret never enters the script. Also checks an incoming webhook's own signature scheme.

• key (string): The signing key, usually ctx.secret.NAME.
• data (string): The text to sign (up to 64 KB).
• encoding (string, optional): "hex" (default) or "base64".

encodeQuery(params): string

Builds a URL query string from an object: encodeQuery({ q: "duck facts", page: 2 }) is "q=duck%20facts&page=2". An array value repeats the key; null and undefined are skipped.

• params (Record<string, any>): Keys and values.

parseQuery(text): Record<string, string | string[]>

Reads a query string (or a whole URL, or a form-urlencoded body) into an object. A key that repeats becomes an array.

• text (string): "a=1&b=2", "?a=1" or a URL.

splitMessage(text, maxLength?): string[]

Splits long text into chunks that fit in one message (2000 characters by default), breaking at line ends, then spaces, where it can. Send each chunk with sendMessage().

• text (string): The text.
• maxLength (number, optional): Chunk size (100-4000; defaults to 2000).

listScheduledEvents(): ScheduledEventContext[]

Returns the server's scheduled events, the read that createScheduledEvent() / modifyScheduledEvent() / deleteScheduledEvent() never had. Same shape as ctx.scheduledEvent. Live REST read.

createScheduledEvent(options): string

Creates a guild scheduled event. options is an object (or JSON string): {name, description, entityType ("external"|"voice"|"stage"), channelId, location, startsAt (ISO 8601), endsAt (ISO 8601), recurrence, coverMediaId, reason}. External events need location + endsAt; voice/stage events need channelId. recurrence makes it repeat: {frequency: "daily"|"weekly"|"monthly"|"yearly", interval?, byWeekday?: ["monday", …]} (Discord allows daily, weekly on one day, every other week, monthly on a date or weekday, yearly). coverMediaId is an image from the Media page. Returns the created event's snowflake ID.

• options (object | string): The event definition (see description).

modifyScheduledEvent(eventId, options): void

Edits an existing scheduled event. options uses the same shape as createScheduledEvent, plus an optional status ("active"|"completed"|"canceled") to transition it: flip a newly-created event to "active" so it shows as happening now, or "completed" when it ends. Only the fields you set change.

• eventId (string): Discord snowflake ID of the scheduled event.
• options (object | string): The fields to change.

deleteScheduledEvent(eventId, reason?): void

Deletes a scheduled event.

• eventId (string): Discord snowflake ID of the scheduled event.
• reason (string, optional): Audit log reason.

getScheduledEventUsers(eventId, max?): string[]

Returns the user IDs who RSVP'd to a scheduled event (up to 1000), e.g. to ping them 15 minutes before it starts.

• eventId (string): The scheduled event.
• max (number, optional): Maximum to return (1-1000; defaults to 100).

runLater(scriptName, delaySeconds, payload?): string

Runs another script (one with the Delayed trigger) after a delay, with a payload it reads from ctx.delayed.payload: the way to unban after 7 days, remove a temp role, send a reminder or end a giveaway. Returns a job ID for cancelLater(). The delay can be up to 90 days; a server can have at most 1000 pending jobs (Free: 100). The run is budgeted like any other when it comes due.

• scriptName (string): Name of a script with the Delayed trigger.
• delaySeconds (number): How long to wait (1 second to 90 days).
• payload (any, optional): Anything JSON-serialisable (up to 4 KB).

emit(eventName, payload?): boolean

Sends a named event to every enabled CustomEvent script subscribed to it, with a payload they read from ctx.event.payload. The emitter needn't know who listens. Subscribers run within a couple of seconds, each budgeted like any other run. A run can emit 5 events, a server 60 a minute, and events can chain at most 3 deep.

• eventName (string): e.g. "ticket.closed" (letters, digits and . _ : -).
• payload (any, optional): Anything JSON-serialisable (up to 16 KB).

require(name): any

Loads a Library script and returns its module.exports. Each library runs once per run however often it's required. Pass the name as a plain string: libraries are looked up when the run is queued, so require(someVariable) can't find one.

• name (string): Name of a script with the Library trigger.

cancelLater(jobId): boolean

Cancels a pending runLater() job.

• jobId (string): The ID runLater() returned.

listLater(scriptName?): PendingJob[]

Lists the server's pending runLater() jobs, soonest first.

• scriptName (string, optional): Only jobs for this script.

expectReply(userId, channelId, scriptName, timeoutSeconds, payload?): void

Waits for a user's next message in a channel and hands it to a ReplyReceived script, with a payload: the building block for step-by-step setups ("Which channel should I post in?"). If they don't answer within the timeout, the same script runs with ctx.reply.timedOut true. A new wait for the same user and channel replaces the old one.

• userId (string): Whose reply to wait for.
• channelId (string): Where (a channel or thread in this server).
• scriptName (string): Name of a script with the ReplyReceived trigger.
• timeoutSeconds (number): How long to wait (5 seconds to 24 hours).
• payload (any, optional): Anything JSON-serialisable, read back as ctx.reply.payload.

cancelReply(userId, channelId): boolean

Stops waiting for a user's reply in a channel.

• userId (string): The user.
• channelId (string): The channel.

listAutoModRules(): AutoModRule[]

Lists the server's AutoMod rules (Discord's own filter, which blocks a message before anyone sees it and costs no runtime). createdByBot marks the ones Mallard's scripts made. Live REST read.

getAutoModRule(ruleId): AutoModRule | null

One AutoMod rule.

• ruleId (string): The rule's ID.

createAutoModRule(options): string

Creates an AutoMod rule: setup wizards, a /raidmode toggle, word lists synced from the key-value store. Discord allows 6 keyword rules and one each of spam, preset, mentionSpam and memberProfile. Rules that would match every message (an empty-matching regex, the keyword "*") are refused. The audit log names the script. A run can create, change or delete 5 rules.

• options (AutoModRuleOptions): e.g. { name: "No invites", trigger: "keyword", keywords: ["discord.gg/*"], actions: [{ type: "block", message: "No invite links" }] }.

modifyAutoModRule(ruleId, options): void

Changes an AutoMod rule. Only the options you pass change; pass enabled: false to switch a rule off. A rule's trigger can't be changed.

• ruleId (string): The rule's ID.
• options (AutoModRuleOptions): What to change.

deleteAutoModRule(ruleId, reason?): boolean

Deletes an AutoMod rule.

• ruleId (string): The rule's ID.
• reason (string, optional): Audit log reason.

zIncr(set, member, by?): number

Adds to a member's score in a sorted set (a missing member starts at 0) and returns the new score. Atomic, so any number of runs can add at once without a lock: the way to keep XP, message counts or invite counts for a leaderboard. Each member costs its length plus 16 bytes of storage; a set holds up to 10,000 members on Free (25k Plus, 50k Pro, 100k Ultra) and a server can have 100 sets.

• set (string): The set's name, e.g. "xp".
• member (string): Who or what is scored, usually a user ID (up to 100 characters).
• by (number, optional): Amount to add (may be negative; defaults to 1).

zSet(set, member, score): number

Sets a member's score outright, adding the member if needed.

• set (string): The set's name.
• member (string): The member.
• score (number): The score.

zGet(set, member): number | null

A member's score.

• set (string): The set's name.
• member (string): The member.

zRank(set, member, options?): number | null

A member's position, counting from 0 at the highest score (so rank + 1 is their place on the leaderboard). Pass { asc: true } to count from the lowest instead.

• set (string): The set's name.
• member (string): The member.
• options ({ asc?: boolean }, optional): Ascending order instead of descending.

zRange(set, start?, stop?, options?): string[] | { member: string, score: number }[]

Members by rank, highest score first: zRange("xp", 0, 9, { withScores: true }) is the top ten. At most 100 per call; page with start/stop.

• set (string): The set's name.
• start (number, optional): First rank (0-based; defaults to 0).
• stop (number, optional): Last rank, inclusive (defaults to start + 9).
• options ({ asc?: boolean, withScores?: boolean }, optional): asc: lowest first. withScores: return { member, score } objects.

zRemove(set, member): boolean

Removes a member from a set, e.g. when they leave the server.

• set (string): The set's name.
• member (string): The member.

zCount(set): number

How many members a set has.

• set (string): The set's name.

zDelete(set): boolean

Deletes a whole set, e.g. to reset a monthly leaderboard, and frees its storage.

• set (string): The set's name.

parseTime(text, timeZone?, from?): string | null

Reads a time the way people type it: "20:00", "8pm", "tomorrow 9am", "fri 8:30pm", "noon", "in 2h30m" or "2026-10-02 20:00", as local time in a zone. A time of day alone means its next occurrence. Pair it with formatTimestamp() so everyone sees it in their own zone, or with runLater() for a reminder (seconds = (Date.parse(iso) - Date.now()) / 1000).

• text (string): What the user typed.
• timeZone (string, optional): IANA zone the text is local to (default UTC).
• from (string, optional): ISO time to count from (default now).

zonedTime(iso?, timeZone?): ZonedTime

The wall-clock time in a zone: year, month (1-12), day, hour, minute, second, weekday ("Monday"), offsetMinutes and a local ISO string. Scripts only get UTC Dates (there's no Intl), so this is how to ask "is it the weekend in New York?". Daylight saving is handled.

• iso (string, optional): ISO time, Date or unix seconds (default now).
• timeZone (string, optional): IANA zone such as "America/New_York" (default UTC).

fromZonedTime(parts, timeZone?): string

The opposite of zonedTime(): a local date and time in a zone as a UTC ISO string. A time skipped when the clocks go forward moves forward by the jump; a time repeated when they go back takes the earlier one.

• parts ({ year: number, month: number, day: number, hour?: number, minute?: number, second?: number } | string): The local time as parts, or as text like "2026-10-02 20:00".
• timeZone (string, optional): IANA zone (default UTC).

formatDate(iso, timeZone?, pattern?): string

Formats a time as text in a zone, in English, for places Discord's timestamp markup doesn't render (embed footers, channel names, KV keys). Tokens: yyyy, MMMM, MMM, MM, M, dddd, ddd, dd, d, HH, H, hh, h, mm, ss, tt (AM/PM), zzz (offset); text in 'single quotes' is kept as is. For messages, prefer formatTimestamp().

• iso (string): ISO time, Date or unix seconds (default now).
• timeZone (string, optional): IANA zone (default UTC).
• pattern (string, optional): Format pattern (default "yyyy-MM-dd HH:mm").

nextOccurrence(cron, timeZone?, from?): string | null

The next time a five-field cron expression fires in a zone, e.g. nextOccurrence("0 20 * * 5", "Europe/London") for "next Friday 20:00 London time".

• cron (string): minute hour day month weekday.
• timeZone (string, optional): IANA zone (default UTC).
• from (string, optional): ISO time to search after (default now).