Channels and groups

Channels live inside groups, and a server is a set of groups holding channels. Your bot can shape that structure at runtime: open a new channel, rename it, move it between groups, or tear it down. Every method on this page needs the manage_channels permission, and every one reports a server denial by rejecting with a CloakActionError.

Channels live inside groups

A group is a labeled section of a server, and each channel belongs to exactly one group. That is why the channel methods take a groupId alongside the channelId: the pair tells the server which channel to act on and where it lives. Create groups to organize channels, and create channels inside them.

Every method here requires the manage_channels permission. Declare it on the Client and let a human approve it per server. See Permissions.

Create a channel

createChannel() opens a new channel inside a group and resolves to the new channel’s id. Pass the server, the channel name, and the group it should live in.

const channelId = await client.createChannel(serverId, 'release-notes', groupId);
console.log(`created channel ${channelId}`);

number

default:"0"

The kind of channel to create. 0 is a text channel, and it is the only value this method is documented and tested for. Cloak has other channel types, but nothing else in the SDK understands them: leave this at the default unless you already know the numeric type your server expects.

Promise<string>

The id of the newly created channel.

The SDK remembers the new channel’s group, so a later send() into it does not need a groupId in SendOptions.

Rename a channel

editChannel() renames a channel in place. Pass the channel and its group, then the new name.

await client.editChannel(serverId, channelId, groupId, 'release-notes-archive');

Move a channel

moveChannel() relocates a channel to a group and a position within it. Pass the group the channel is in now, the group it should move to, and the target order.

// Move a channel into another group, placing it at the top.
await client.moveChannel(serverId, channelId, fromGroupId, toGroupId, 0);

number

The channel’s position in the destination group. Floored to a whole number and clamped to the range 0 to 126.

Moving a channel to the same group at the same order is a no-op, and the server rejects it rather than ignoring it. Move to a different group or a different position.

Delete a channel

deleteChannel() removes a channel along with its messages and pins. Pass the channel and its group.

await client.deleteChannel(serverId, channelId, groupId);

Deleting a channel also deletes its messages and pins. There is no undo.

Work with groups

Groups are the sections that hold channels. Create one before you fill it with channels, rename it, or delete it once it is empty of anything you want to keep.

Create a group

createGroup() creates a channel group. It resolves to the new group’s id, captured best-effort from the server’s create broadcast by matching the name within a short window. When the id cannot be captured, it resolves to undefined, so always handle that case.

const groupId = await client.createGroup(serverId, 'Announcements');
if (!groupId) {
  console.warn('group was created, but its id could not be captured');
  return;
}
const channelId = await client.createChannel(serverId, 'news', groupId);

Promise<string | undefined>

The id of the new group, or undefined when it could not be captured. undefined does not mean the group failed to create.

Rename a group

editGroup() renames a group.

await client.editGroup(serverId, groupId, 'Company Announcements');

Delete a group

deleteGroup() deletes a group and every channel inside it.

await client.deleteGroup(serverId, groupId);

Deleting a group deletes its channels too. Move out anything you want to keep first.

Use the guild() handle

Every method above is also available on the guild() handle, which binds the server id for you so you pass one fewer argument. This reads well when a command already knows which server it is acting on. Message.serverId is string | null and is null for a direct message, which arrives on the same messageCreate event. Guard before you bind.

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() !== '!new-channel') return;

  const g = client.guild(msg.serverId);
  try {
    const groupId = await g.createGroup('Bot Output');
    if (!groupId) return; // id was not captured, nothing to fill
    await g.createChannel('bot-log', groupId);
    await msg.channel.send('Opened #bot-log under Bot Output.');
  } catch (err) {
    if (err instanceof CloakActionError) {
      await msg.channel.send(`Could not create the channel: ${err.message}`);
    }
  }
});

Cloak has no channel-mention entity. Writing <#channelId> in a message body renders as literal text, not a link, so name the channel in plain text as above. The only id-keyed mention Cloak renders is the user mention, produced by userMention(). Role, @everyone, and @here mentions are name-keyed literal text.

The announcement uses msg.channel.send(), a plain send into the same channel. msg.reply() would post a true reply with a quote header and fire a mute-piercing “replied to you” notification, which a status line does not need.

send() and msg.channel.send() are fire-and-forget. The promise resolves when the frame leaves the process, not when the server accepts it. A denied send arrives later on the sendRejected event, so the try/catch above sees channel failures but not send failures. The channel and group methods on this page are different: they are awaited actions that really do reject.

Listen for lifecycle changes

Every create, rename, move, and delete fires an event, so your bot can react to structural changes it did not make. These events fire for the bot’s own mutations too, so filter by the ids you just acted on when you only want changes from elsewhere.

Event	Payload	Fires when
`channelCreate`	`{ channelId, name, groupId, type, serverId }`	A channel is created.
`channelUpdate`	`{ channelId, name, serverId }`	A channel is renamed.
`channelDelete`	`{ channelId, serverId }`	A channel is deleted.
`groupCreate`	`{ groupId, name, serverId }`	A group is created.
`groupUpdate`	`{ groupId, name, serverId }`	A group is renamed.
`groupDelete`	`{ groupId, serverId }`	A group is deleted.

client.on('channelCreate', ({ channelId, name, groupId, serverId }) => {
  console.log(`channel ${name} (${channelId}) created in group ${groupId} on ${serverId}`);
});

client.on('groupDelete', ({ groupId, serverId }) => {
  console.log(`group ${groupId} removed from ${serverId}`);
});

Routing these events to a bot for a server it has not selected requires a current Cloak server. An older server delivers them only for the selected server.

Servers are owner-level

There are no methods to edit or delete a server. Those actions are owner-level and reach your bot only as events, so your bot can observe them but not perform them.

Event	Payload	Fires when
`serverUpdate`	`{ serverId, name }`	A server is renamed.
`serverDelete`	`{ serverId }`	A server is deleted.

client.on('serverUpdate', ({ serverId, name }) => {
  console.log(`server ${serverId} is now called ${name}`);
});

Events

Every lifecycle event and its payload.

Errors

Catch a CloakActionError when the server denies an action.

Permissions

Why these methods need manage_channels.

The guild() handle

Bind a server id and pass one fewer argument.

Get started

Core concepts

Messaging

Slash commands

Embeds and cards

Voice

Server management

Advanced

Running in production

Examples

API reference

Reference

Channels live inside groups

Create a channel

Rename a channel

Move a channel

Delete a channel

Work with groups

Create a group

Rename a group

Delete a group

Use the guild() handle

Listen for lifecycle changes

Servers are owner-level

Next

Events

Errors

Permissions

The guild() handle

​Channels live inside groups

​Create a channel

​Rename a channel

​Move a channel

​Delete a channel

​Work with groups

​Create a group

​Rename a group

​Delete a group

​Use the guild() handle

​Listen for lifecycle changes

​Servers are owner-level

​Next

Events

Errors

Permissions

The guild() handle

Channels live inside groups

Create a channel

Rename a channel

Move a channel

Delete a channel

Work with groups

Create a group

Rename a group

Delete a group

Use the guild() handle

Listen for lifecycle changes

Servers are owner-level

Next