The guild() handle

Most server-scoped actions on the flat client take a serverId as their first argument. When a handler does several things in one server, you pass the same id over and over. client.guild(serverId) returns a lightweight handle that binds the id once, so every call after it reads a little cleaner.

Bind the server once

Call client.guild() with a serverId and keep the handle it returns. Each of its methods delegates to the identically named flat client method with the id already filled in. Message.serverId is string | null, and guild() takes a string. Direct messages arrive on the same messageCreate event with a null serverId, so guard before you bind.

client.on('messageCreate', async (msg) => {
  if (msg.authorId === client.user?.id) return; // ignore our own messages
  if (msg.isDM || !msg.serverId) return;        // a DM has no server to bind
  if (msg.content.trim() !== '!sweep') return;

  const g = client.guild(msg.serverId);
  await g.timeout(msg.authorId, 300);
  const roles = await g.fetchRoles();
  const history = await g.fetchMessages(msg.channelId, { limit: 100 });
  console.log(`${roles.length} roles, ${history.length} messages read`);
});

The handle carries no cache and no state. It is sugar over the flat methods, and the flat methods remain the source of truth. Reach for it when a single handler takes several actions in one server. For a one-off call, the flat form is just as good.

It is optional sugar

The two forms below do exactly the same thing. g.timeout(userId, 300) delegates straight to client.timeout(serverId, userId, 300).

// Flat form: pass the serverId every time.
await client.timeout(serverId, userId, 300);

// Handle form: bind it once, then omit it.
const g = client.guild(serverId);
await g.timeout(userId, 300);

Because the handle methods delegate to their flat counterparts, the semantics, required permissions, return types, and errors are the same. The handle only removes the repeated serverId. There is one exception. webhooks.post() does not mirror a Client method: it calls the SDK’s module-level webhook poster directly and needs no permission at all, because it posts to a URL a human already created.

The handle holds no state of its own. It fetches nothing when you create it, and it never goes stale. You can make a new one per handler without cost.

What the handle exposes

id is the serverId you passed. Every other member is a bound version of a flat client method. The semantics live in the linked guides, since the handle changes nothing about how each method behaves.

Identity

string

The serverId this handle is bound to.

Messaging

(channelId: string, text: string, opts?: SendOptions) => Promise<void>

Send an encrypted message into a channel in this server. SendOptions is { groupId?, mentions?, replyTo? }. There is no positional groupId argument. See Sending messages.

(channelId: string, opts?) => Promise<Message[]>

Read message history from a channel, oldest first. See Message history.

(channelId: string, card: CardMessage) => Promise<void>

Post a rich card. End-to-end encrypted, under the bot’s own identity, and it needs only message_send. This is the embed lane to default to. See Rich cards.

(channelId: string, post: UnencryptedWebhookPost) => Promise<void>

Post a rich embed through a webhook. Requires manage_server. See Webhook embeds.

sendEmbed() is not end-to-end encrypted. The message is stored server-side as plaintext and renders under a webhook identity rather than the bot’s. Use sendCard() when the content is sensitive.

send() and sendCard() are fire-and-forget. The promise resolves when the frame leaves the process, not when the server accepts it. A server-side denial arrives later on the sendRejected event, so a try/catch around the send will not see it.

Moderation

(userId: string) => Promise<void>

Remove a member from this server.

(userId: string, reason?: string) => Promise<void>

Ban a member, with an optional reason capped at 256 characters.

(userId: string) => Promise<void>

Lift a ban.

(userId: string, seconds: number) => Promise<void>

Time a member out for a number of seconds. 0 lifts it.

(userId: string) => Promise<void>

Clear an active timeout.

() => Promise<BanInfo[]>

List the server’s recorded bans.

All of these are covered in Moderation, including the role-rank and owner constraints that no permission check can predict.

Reads

() => Promise<Role[]>

List the server’s roles, with color, position, and member count.

() => Promise<Member[]>

List the server’s members. Currently out of service.

g.fetchMembers() binds the same broken read as client.fetchMembers(). Against every current Cloak server it neither resolves nor rejects: it hangs until the transport timeout, so a try/catch does not help. See Members and roles. g.fetchRoles() works normally.

Channels and groups

(name: string, groupId: string, type?: number) => Promise<string>

Create a channel inside a group and resolve to its new id.

(channelId: string, groupId: string, name: string) => Promise<void>

Rename a channel.

(channelId: string, groupId: string) => Promise<void>

Delete a channel, along with its messages and pins.

(channelId: string, fromGroupId: string, toGroupId: string, order: number) => Promise<void>

Move a channel between groups and set its position.

(name: string) => Promise<string | undefined>

Create a channel group. Resolves to undefined when the new group’s id could not be captured.

(groupId: string, name: string) => Promise<void>

Rename a group.

(groupId: string) => Promise<void>

Delete a group and every channel inside it.

The channel and group methods are covered in Channels and groups.

Webhooks

webhooks is a nested object on the handle, pre-bound to this server. Everything it posts is stored server-side as plaintext.

() => Promise<WebhookInfo[]>

Every webhook on the server. Never includes a token. Requires manage_server.

(channelId: string, name: string, opts?: { icon?: string; miniIcon?: string }) => Promise<WebhookMint>

Mint a webhook on a channel and return its one-time delivery URL. Requires manage_server.

(webhookId: string, changes) => Promise<void>

Rename, re-icon, or move a webhook. Requires manage_server.

(webhookId: string) => Promise<WebhookMint>

Mint a fresh token and return the new URL. This permanently invalidates the old one. Requires manage_server.

(webhookId: string) => Promise<void>

Delete a webhook. Requires manage_server.

(url: string, post: UnencryptedWebhookPost) => Promise<void>

Post to a webhook URL a human already created. No permission required, and the recommended path.

See Webhook embeds for the full lane, including why webhooks.post is preferred over minting.

Voice

(channelId: string, opts?: { groupId?: string; muted?: boolean; deafened?: boolean }) => Promise<VoiceConnection>

Join a voice channel and return the credential the server minted. Sends no media by itself.

() => Promise<void>

Ask the server to push a fresh voice roster snapshot for this server.

See Joining voice for the permission ladder and the groupId rule.

Permissions and visibility

(permission: PermissionName) => boolean

Advisory check for a single permission in this server. Returns false when no verdict has arrived yet.

() => PermissionSet | undefined

The resolved permission set for this server, or undefined if no verdict has arrived yet.

() => string[]

The channel ids the bot may currently view in this server.

These mirror the advisory checks described in Permissions.

What the handle does not bind

The handle covers server-scoped methods only. Everything below stays on the flat client, so call it there rather than looking for it on g.

Not on the handle	Why
`sendTyping(serverId, channelId, isTyping?, groupId?)`	Not bound. Use the flat method.
`sendCommand(serverId, channelId, name, args, opts)`	Not bound. Use the flat method.
`sendDM(userId, text, opts?)`	A DM has no server.
`watch(serverId, channelId, groupId?)`	Not bound. Use the flat method.
`fetchEmojis()`	The emoji catalog is global, not per server.
`messageLocation(messageId)`	Client-wide lookup across every channel seen.
`voiceRoster(channelId)`	Keyed by channel, and the bot is in at most one voice channel.
`leaveVoice()`, `voiceConnection()`, `setVoiceSelfState(state)`	Act on the bot’s single live voice session, not on a server.
`setStatus(status)`, `rest`, `destroy()`	Account-wide or client-wide.

Putting it together

A moderation handler is where the handle earns its place. One bind, then several bound calls that never repeat the server id.

import { CloakActionError } from '@cloak-software/bot-sdk';

client.on('messageCreate', async (msg) => {
  if (msg.authorId === client.user?.id) return; // ignore our own messages
  if (msg.isDM || !msg.serverId) return;        // a DM has no server to bind
  if (msg.content.trim() !== '!lockdown') return;

  const g = client.guild(msg.serverId);
  if (!g.can('member_ban')) return; // advisory pre-gate

  try {
    const bans = await g.fetchBans();
    console.log(`${g.id} currently has ${bans.length} bans`);

    await g.timeout(msg.authorId, 600);
    await g.send(msg.channelId, 'Channel is quiet for ten minutes.');
  } catch (err) {
    if (err instanceof CloakActionError) {
      console.error(`lockdown denied: ${err.message}`);
    } else {
      throw err;
    }
  }
});

Every call above delegates to the flat client, so if you already know the flat methods you already know the handle.

Moderation

Kicks, bans, and timeouts in full.

Channels and groups

Create, edit, and move channels and groups.

Sending messages

SendOptions, and why a send is fire-and-forget.

Client reference

Every flat method the handle binds.

Get started

Core concepts

Messaging

Slash commands

Embeds and cards

Voice

Server management

Advanced

Running in production

Examples

API reference

Reference

Bind the server once

It is optional sugar

What the handle exposes

Identity

Messaging

Moderation

Reads

Channels and groups

Webhooks

Voice

Permissions and visibility

What the handle does not bind

Putting it together

Next

Moderation

Channels and groups

Sending messages

Client reference

​Bind the server once

​It is optional sugar

​What the handle exposes

​Identity

​Messaging

​Moderation

​Reads

​Channels and groups

​Webhooks

​Voice

​Permissions and visibility

​What the handle does not bind

​Putting it together

​Next

Moderation

Channels and groups

Sending messages

Client reference

Bind the server once

It is optional sugar

What the handle exposes

Identity

Messaging

Moderation

Reads

Channels and groups

Webhooks

Voice

Permissions and visibility

What the handle does not bind

Putting it together

Next