Mallard

https://mallard.bot/docs
Admin
Mallard is a Discord moderation bot with a built-in JavaScript scripting engine that allows server...
Tokens:71,761
Snippets:578
Trust Score:2.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### startStage(channelId, topic, options?)

Source: https://mallard.bot/docs/functions

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.

```APIDOC
## startStage(channelId, topic, options?)

### Description
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.

### Method
async

### Endpoint
startStage(channelId, topic, options?)

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

### Response
#### Success Response
- **Promise<string>** - The stage instance ID.

#### Response Example
```json
"stage_instance_id"
```
```

--------------------------------

### getKV(key, options?)

Source: https://mallard.bot/docs/functions

Gets a value from the guild's key-value store, optionally locking the key for safe read-modify-write.

```APIDOC
## getKV(key, options?)

### Description
Retrieves a value from the guild's key-value store. Reads don't lock by default; pass `{ lock: true }` to take the key's lock for a safe read-modify-write. The reserved system key "env" is not accessible here.

### Method
Function

### Endpoint
getKV(key, options?)

### Parameters
- **key** (`string`) - Required - Key to look up.
- **options** (`{ lock?: boolean }`, optional) - `lock`: take the key's lock before reading.

### Returns
`Promise<string | null>` - The stored JSON string, or null if not found / expired.

```

--------------------------------

### createAutoModRule(options)

Source: https://mallard.bot/docs/functions

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.

```APIDOC
## createAutoModRule(options)

### Description
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.

### Requirements
Mallard needs: ManageGuild

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

### Returns
- **Promise<string>** - The new rule's ID.
```

--------------------------------

### /ban command: TriggerConfig options and script body

Source: https://mallard.bot/docs/commands

Worked example adapted from the seeded `/ban` command (the mod-role permission guard is omitted). The JSON block defines the command options: one required `User`, one required `String`, and two optional `Integer` options. The script body shows the `parseInt()` conversion and the `ctx.args.reason || "No reason provided"` fallback idiom, plus DM-before-ban, KV-store pending unban logging, and the `editResponse` summary.

```json
{
  "options": [
    { "name": "user", "type": "User", "description": "The user to ban", "required": true },
    { "name": "reason", "type": "String", "description": "Reason for the ban", "required": true },
    { "name": "duration_min", "type": "Integer", "description": "Duration in minutes (0 = permanent)", "required": false },
    { "name": "delete_message_days", "type": "Integer", "description": "Days of messages to delete", "required": false }
  ]
}
```

```javascript
var userId = ctx.args.user;
var reason = ctx.args.reason || "No reason provided";
var durationMin = ctx.args.duration_min ? parseInt(ctx.args.duration_min) : 0;
var deleteDays = ctx.args.delete_message_days ? parseInt(ctx.args.delete_message_days) : 0;
var isPermanent = durationMin <= 0;
var target = getMember(userId);
var targetName = target ? target.username : userId;

// DM before the ban: afterwards there's no mutual guild left to DM through.
// false means their DMs are closed, and the ban still goes ahead.
var dmSent = sendDm(userId, "", [{
    title: isPermanent ? "Permanent Ban" : "Temporary Ban",
    description: "Reason: " + reason,
}]);

ban(userId, reason, deleteDays);

if (!isPermanent) {
    // Actions can't be delayed, so log the unban due time to the KV store;
    // a Scheduled script sweeps due entries on its next run.
    var pending = JSON.parse(getKV("mod:pending_unbans") || "[]");
    pending.push({ userId: userId, unbanAt: Date.now() + durationMin * 60000, reason: reason });
    setKV("mod:pending_unbans", JSON.stringify(pending));
}
var target = getMember(userId);
var targetName = target ? target.username : userId;
editResponse("Banned " + targetName + " (" + userId + "). Reason: " + reason
    + (dmSent ? "" : " (could not DM them the appeal link)"));
```

--------------------------------

### expectReply(userId, channelId, scriptName, timeoutSeconds, payload?)

Source: https://mallard.bot/docs/functions

Waits for a user's next message in a channel and hands it to a ReplyReceived script, with a payload. This is the building block for step-by-step setups. 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.

```APIDOC
## expectReply(userId, channelId, scriptName, timeoutSeconds, payload?)

### Description
Waits for a user's next message in a channel and hands it to a ReplyReceived script, with a payload. This is the building block for step-by-step setups. 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.

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

### Returns
- **void**
```

--------------------------------

### createThread(channelId, name, isPrivate, userIds?, initialMessage?, options?)

Source: https://mallard.bot/docs/functions

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().

```APIDOC
## createThread(channelId, name, isPrivate, userIds?, initialMessage?, options?)

### Description
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().

### Method
async

### Endpoint
createThread(channelId, name, isPrivate, userIds?, initialMessage?, options?)

### Parameters
#### Path Parameters
- **channelId** (string) - Required - Discord snowflake ID of the parent channel.
- **name** (string) - Required - Thread name.
- **isPrivate** (boolean) - Required - 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.

### Response
#### Success Response
- **Promise<string>** - The created thread's snowflake ID.

#### Response Example
```json
"thread_id"
```
```

--------------------------------

### zIncr(set, member, by?)

Source: https://mallard.bot/docs/functions

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.

```APIDOC
## zIncr(set, member, by?)

### Description
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.

### Parameters
- **set** (string) - Required - The set's name, e.g. "xp".
- **member** (string) - Required - 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).

### Returns
- **Promise<number>** - The member's new score.
```

--------------------------------

### listKV(prefix?, limit?, afterKey?)

Source: https://mallard.bot/docs/functions

Lists stored keys with optional prefix, limit, and pagination.

```APIDOC
## listKV(prefix?, limit?, afterKey?)

### Description
Lists server's stored keys, optionally filtered by prefix, in alphabetical order. Returns keys, not values. Page past the limit with afterKey. Expired keys and the reserved "env" row are never listed.

### Method
Function

### Endpoint
listKV(prefix?, limit?, afterKey?)

### Parameters
- **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 previous page).

### Returns
`Promise<string[]>` - Array of matching keys.

```

--------------------------------

### getAutoModRule(ruleId)

Source: https://mallard.bot/docs/functions

Gets a single AutoMod rule.

```APIDOC
## getAutoModRule(ruleId)

### Description
Gets a single AutoMod rule.

### Requirements
Mallard needs: ManageGuild

### Parameters
- **ruleId** (string) - Required - The rule's ID.

### Returns
- **Promise<AutoModRule | null>** - The rule, or null when it doesn't exist.
```

--------------------------------

### zGet(set, member)

Source: https://mallard.bot/docs/functions

Gets a member's score.

```APIDOC
## zGet(set, member)

### Description
Gets a member's score.

### Parameters
- **set** (string) - Required - The set's name.
- **member** (string) - Required - The member.

### Returns
- **Promise<number | null>** - The score, or null when the member isn't in the set.
```

--------------------------------

### fetch()

Source: https://mallard.bot/docs/subsystems

Documentation for the fetch() function, the only network access available to scripts.

```APIDOC
## fetch()

### Description
Performs outbound HTTP requests from scripts. HTTPS-only by default, with configurable timeout and automatic decompression. Supports GET, POST, PUT, PATCH, DELETE, and HEAD methods. Blocks private/internal addresses (SSRF-guarded).

### Method
GET, POST, PUT, PATCH, DELETE, HEAD

### Endpoint
N/A (outbound HTTP)

### Parameters
#### Options (object or JSON string)
- **method** (string) - Optional - HTTP method (default: GET)
- **headers** (object) - Optional - Allowed headers: `accept`, `content-type`, `authorization`, `user-agent`, `client-id`, `api-key`, `anthropic-version`, and any `x-*` header. Others are dropped.
- **body** (string | object) - Optional - Request body, capped at 64 KB.
- **timeoutMs** (number) - Optional - Timeout in milliseconds, up to 30000 (default: 5000).

### Request Example
```json
{
  "method": "POST",
  "headers": {
    "content-type": "application/json"
  },
  "body": {
    "key": "value"
  },
  "timeoutMs": 10000
}
```

### Response
#### Success Response
- Response body auto-decompressed, capped at 1 MB (post-decompression).

### Notes
- HTTPS-only by default; HTTP allowed only when env record has `fetch_allow_http` set.
- Standard ports only.
- Private/internal addresses are blocked.
- `{{secret:NAME}}` placeholders in URL, header values, or body are substituted server-side.
- Per-guild limits: 30 requests/minute (flat sliding window) and hourly call budget by tier (10/30/60/120 on Free/Plus/Pro/Ultra).
- Live remaining calls available via `ctx.fetchCallsRemaining`.
```

--------------------------------

### createThreadFromMessage

Source: https://mallard.bot/docs/functions

Starts a thread from an existing message and returns the thread ID.

```APIDOC
## createThreadFromMessage

### Description
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.

### Signature
`createThreadFromMessage(channelId, messageId, name, options?): Promise<string>`

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

### Returns
`Promise<string>` - The new post's thread ID.

### Permissions
Mallard needs: CreatePublicThreads
```

--------------------------------

### getVoiceState(userId)

Source: https://mallard.bot/docs/functions

Gets a member's current voice state.

```APIDOC
## getVoiceState

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

### Parameters
- **userId** (string) - Required - Discord snowflake ID of the member.

### Returns
- **Promise\<VoiceMember | null>** - Their voice state.
```

--------------------------------

### createChannel(name, type, parentIdOrOptions?, topic?, reason?)

Source: https://mallard.bot/docs/functions

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"] }] }).

```APIDOC
## createChannel(name, type, parentIdOrOptions?, topic?, reason?)

### Description
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"] }] }).

### Parameters
- **name** (`string`) - Required - Name for the new channel.
- **type** (`string`) - Required - 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.

### Returns
`Promise<string>` - The created channel's snowflake ID.
```

--------------------------------

### lockThread(threadId, locked, reason?)

Source: https://mallard.bot/docs/functions

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

```APIDOC
## lockThread(threadId, locked, reason?)

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

### Method
async

### Endpoint
lockThread(threadId, locked, reason?)

### Parameters
#### Path Parameters
- **threadId** (string) - Required - Discord snowflake ID of the thread.
- **locked** (boolean) - Required - true to lock, false to unlock.
- **reason** (string, optional) - Audit log reason.

### Response
#### Success Response
No return value.
```

--------------------------------

### zRank(set, member, options?)

Source: https://mallard.bot/docs/functions

Gets 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.

```APIDOC
## zRank(set, member, options?)

### Description
Gets 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.

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

### Returns
- **Promise<number | null>** - The member's rank, or null when not in the set.
```

--------------------------------

### pauseInvites(hours, reason?)

Source: https://mallard.bot/docs/functions

Pauses joining through invites for up to 24 hours. Requires the ManageGuild permission.

```APIDOC
## pauseInvites(hours, reason?)

### Description
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.

### Method
async function

### Parameters
- **hours** (number) - Required - How long to pause (0-24; fractions allowed). 0 resumes.
- **reason** (string, optional) - Optional - Audit log reason.

### Returns
void

### Permissions
Mallard needs: ManageGuild
```

--------------------------------

### getKVMany(keys)

Source: https://mallard.bot/docs/functions

Batch retrieves multiple keys from the KV store in a single call.

```APIDOC
## getKVMany(keys)

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

### Method
Function

### Endpoint
getKVMany(keys)

### Parameters
- **keys** (`string[]`) - Required - Up to 1000 keys.

### Returns
`Promise<Record<string, string | null>>` - Mapping of key to stored JSON string, or null if missing.

```

--------------------------------

### getStickers()

Source: https://mallard.bot/docs/functions

Returns the server's stickers.

```APIDOC
## getStickers()

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

### Method
async function

### Signature
getStickers(): Promise<StickerSummary[]>

### Returns
Promise<StickerSummary[]> - The server's stickers.
```

--------------------------------

### setKV(key, value, ttlSeconds?)

Source: https://mallard.bot/docs/functions

Stores a value in the guild's key-value store, overwriting existing values, with optional TTL.

```APIDOC
## setKV(key, value, ttlSeconds?)

### Description
Stores a value in the guild's key-value store, overwriting any existing value. Strings are stored as-is (should be JSON); other values are JSON-encoded. Written immediately, survives script errors. The reserved system key "env" cannot be written.

### Method
Function

### Endpoint
setKV(key, value, ttlSeconds?)

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

### Returns
`void` - Nothing.

```

--------------------------------

### setVerificationLevel(level, reason?)

Source: https://mallard.bot/docs/functions

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

```APIDOC
## setVerificationLevel(level, reason?)

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

### Parameters
- **level** (`string`) - Required - "none", "low", "medium", "high" or "veryHigh".
- **reason** (`string`, optional) - Audit log reason.

### Returns
`Promise<void>`
```

--------------------------------

### getIntegrations()

Source: https://mallard.bot/docs/functions

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

```APIDOC
## getIntegrations()

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

### Method
async

### Endpoint
getIntegrations()

### Parameters
None

### Response
#### Success Response
- **IntegrationSummary[]** - The server's integrations.

#### Response Example
```json
[]
```
```

--------------------------------

### listChannels()

Source: https://mallard.bot/docs/functions

Lists the guild's cached channels (id, name, type, category, position; no threads). This is a cheap cached read with no REST call.

```APIDOC
## listChannels()

### Description
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.

### Method
Function

### Signature
`listChannels(): Promise<ChannelSummary[]>`

### Parameters
None

### Returns
`Promise<ChannelSummary[]>` - Array of the guild's channels.
```

--------------------------------

### listLater(scriptName?)

Source: https://mallard.bot/docs/functions

Lists the server's pending runLater() jobs, soonest first. Optionally filter by script name.

```APIDOC
## listLater(scriptName?)

### Description
Lists the server's pending runLater() jobs, soonest first. Optionally filter by script name.

### Parameters
- **scriptName** (string, optional) - Only jobs for this script.

### Returns
- **Promise<PendingJob[]>** - Pending jobs.
```
Tokens:
Raw