Permissions

Permissions are referenced by name throughout the SDK. You declare them in requiredPermissions, check them with can(), and read them from a PermissionSet. The names below are the exact strings to use. There are 31 permissions, codes 0 through 30. Names are what you write; the integer codes are the wire contract, and they matter only if you decode a raw grant yourself. For how declaring and granting work together, see the Permissions concept.

const client = new Client({
  token: process.env.CLOAK_TOKEN!,
  requiredPermissions: ['view_text', 'message_send', 'reaction_add'],
});

Administrator

Name	Code	Controls
`administrator`	0	Grants every permission.

If your bot holds administrator in a server, can() returns true for every other permission there. Ask for it only when your bot genuinely needs full control.

The expansion happens in can() only. administrator stays a distinct bit in a decoded PermissionSet, so a set where only administrator is true still has every other boolean false. Read it through can(), not by inspecting the booleans directly.

Server management

Name	Code	Controls
`manage_channels`	3	Create, edit, and delete channels.
`view_audit`	4	View the audit log.
`view_insights`	5	View server insights.
`manage_server`	6	Change server settings, and manage webhooks.
`invite_creation`	7	Create invites to the server.
`emoji_gif_manage`	10	Manage the server’s emoji and GIFs.
`event_invite`	29	Invite members to calendar events.

Most bots should not hold manage_server. It is only needed to mint or rotate webhooks. If your bot posts webhook embeds, have a human create the webhook in the Cloak app and pass its url in an environment variable instead. See Webhook embeds.

Viewing

Name	Code	Controls
`view_text`	1	View text channels. Required to receive their messages.
`view_voice`	2	View voice channels.
`message_read_history`	20	Read past messages in a channel.

view_text is what puts a text channel on your bot’s firehose. Without it in a given channel, your bot does not receive that channel’s messages at all.

Messaging

Name	Code	Controls
`message_send`	14	Send messages. Also all that `sendCard()` needs.
`message_manage`	15	Manage other members’ messages, such as deleting them.
`embed_link`	16	Post links that render as unfurled previews.
`upload_file`	17	Attach files.
`reaction_add`	18	Add reactions to messages.
`mention_roles`	19	Mention roles.
`commands`	21	Use commands.

Members

Name	Code	Controls
`nickname_change`	8	Change the bot’s own nickname.
`nickname_manage`	9	Change other members’ nicknames.
`member_kick`	11	Remove members from the server.
`member_ban`	12	Ban members from the server.
`member_timeout`	13	Time members out.

Voice

Name	Code	Controls
`voice_connect`	22	Connect to voice channels.
`voice_speak`	23	Speak in voice channels.
`voice_video`	24	Share video in voice channels. Not available to bots, see below.
`voice_activity`	25	Use voice activity detection.
`members_mute`	26	Mute members in voice.
`members_deafen`	27	Deafen members in voice.
`members_move`	28	Move members between voice channels.
`voice_listen`	30	Receive other members’ voice media.

voice_listen is the permission that decides whether your bot can hear anything. voice_connect does not imply it.Without it, your bot joins voice and publishes audio normally, the SFU sends it nothing, and it is never given a key that could decrypt anyone. joinVoice() deliberately succeeds without it, because publishing while deaf is the normal configuration for a music or announcement bot. The failure mode for a bot that was supposed to listen is total silence with no error anywhere. See Voice keys.

A bot holding voice_video still cannot publish camera or screenshare. A bot session’s media credential is minted microphone-only, so video is denied at the credential rather than by the SDK, and peer-to-peer video is deleted from the platform. There is no video path to enable.

Using names in code

Every name above is a value of the PermissionName type.

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

const needed: PermissionName[] = ['view_text', 'message_send'];

Ask only for the permissions your bot actually uses. A smaller request is easier for a server admin to approve, and it keeps the bot’s footprint honest.

PermissionName

type PermissionName = 'administrator' | 'view_text' | /* ...29 more... */ | 'voice_listen';

A union of all 31 names, so you get autocomplete and compile-time checking.

PERMISSION_CODES

const PERMISSION_CODES: Record<PermissionName, number>

Maps each name to its wire code, 0 through 30.

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

PERMISSION_CODES.message_send; // 14

PERMISSION_NAMES

const PERMISSION_NAMES: PermissionName[]

Every name, indexed by wire code: PERMISSION_NAMES[14] is 'message_send'. That holds because the code map is dense with no gaps.

PermissionSet

type PermissionSet = { effectiveRank: number } & Record<PermissionName, boolean>;

The resolved capability set for one server: 31 named booleans plus a numeric rank. You get one from permissions(serverId), and the same shape is spread into the permissionsUpdate payload.

number

The bot’s effective rank in the server. Moderation actions compare ranks: your bot cannot kick, ban, or time out a member whose rank is not below its own.

boolean

One boolean per permission name. true means the bot holds it in this server.

client.on('permissionsUpdate', ({ serverId, effectiveRank, ...perms }) => {
  console.log(`send in ${serverId}: ${perms.message_send}, rank ${effectiveRank}`);
});

decodePermArray

decodePermArray(permArray: unknown[], effectiveRank: number): PermissionSet

Decodes a raw code-indexed boolean array plus a rank into a named PermissionSet. Missing or falsy entries decode to false. You need this only when reading a grant off a raw frame; the SDK already decodes the ones it delivers.

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

const set = decodePermArray(rawBooleans, rank);
if (set.message_send) { /* ... */ }

decodePermArray does not expand administrator. A set decoded from an administrator grant has administrator: true and every other boolean false. Only can() applies the implies-all rule.

Permissions concept

How declaring and granting fit together.

Errors

Reading the permission a denial names.

Client

can(), permissions(), and visibleChannelIds().

Voice keys

Why voice_listen decides what a bot hears.

Get started

Core concepts

Messaging

Slash commands

Embeds and cards

Voice

Server management

Advanced

Running in production

Examples

API reference

Reference

Administrator

Server management

Viewing

Messaging

Members

Voice

Using names in code

PermissionName

PERMISSION_CODES

PERMISSION_NAMES

PermissionSet

decodePermArray

Next

Permissions concept

Errors

Client

Voice keys

​Administrator

​Server management

​Viewing

​Messaging

​Members

​Voice

​Using names in code

​PermissionName

​PERMISSION_CODES

​PERMISSION_NAMES

​PermissionSet

​decodePermArray

​Next

Permissions concept

Errors

Client

Voice keys

Administrator

Server management

Viewing

Messaging

Members

Voice

Using names in code

PermissionName

PERMISSION_CODES

PERMISSION_NAMES

PermissionSet

decodePermArray

Next