Mention helpers

A Cloak mention is two independent halves, and you supply both: the pill is literal text inside the encrypted body, and the ping is an [id, isRole] pair in SendOptions.mentions. These helpers build and read both halves. For the model and the patterns, see Mentions and replies.

Mention targets are not end-to-end encrypted. Message bodies are, the list of who a message pings is not. It rides the send frame in plaintext because the server routes notification fanout without decrypting anything. Anyone with server-side visibility can see who your bot pinged, just not what it said. This is Cloak’s design and it is true of every Cloak client.

import {
  userMention,
  roleMention,
  mentionPairs,
  parseMentions,
  EVERYONE,
  HERE,
  MENTION_ENTITY_RE,
} from '@cloak-software/bot-sdk';
import type { MentionTarget, MentionPair, MessageMentions } from '@cloak-software/bot-sdk';

userMention

userMention(user: string | { id: string }): string

The rendered form of a user mention: Cloak’s id-keyed wire entity, HTML-escaped exactly as every human client writes it. Accepts a raw id or anything with an id, and normalizes dashed uuids to undashed lowercase hex.

userMention('0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0');
// '&lt;@0f1e2d3c4b5a69788796a5b4c3d2e1f0&gt;'

Because the pill is keyed by id, it follows the user across nickname and display-name changes.

client.on('messageCreate', (msg) => {
  if (msg.isDM || !msg.serverId) return;
  if (msg.authorId === client.user?.id) return;
  msg.channel.send(`${userMention(msg.authorId)} pong`, {
    mentions: [{ userId: msg.authorId }],
  });
});

The text alone renders a pill and notifies nobody. Pass mentions too, or the ping does not happen.

roleMention

roleMention(role: string | { name: string }): string

The rendered form of a role mention: literal @Name. Roles are still name-keyed on the wire, so the pill renders only for viewers whose client resolves that role name, and renaming the role stops old messages from rendering it. The ping itself rides the id pair and is unaffected. Multi-word role names work, because clients match them longest first. Single-word names must match [\w-]+ to render as a pill.

await client.send(serverId, channelId, `${roleMention('Moderators')} heads up`, {
  mentions: [{ roleId }],
});

Role, @everyone and @here pings are gated server-side on mention_roles. client.can('mention_roles', serverId) is an advisory pre-check, and the server remains authoritative.

mentionPairs

mentionPairs(targets: readonly MentionTarget[] | undefined): MentionPair[]

Builds the plaintext ping array for the outbound frame. Deduplicates, and drops empty ids. send() calls this for you on SendOptions.mentions, so you rarely call it directly. Reach for it when you are building a frame yourself with client.raw. The pairs it produces:

Target	Pair
`{ userId }`	`[id, 0]`
`{ roleId }`	`[id, 1]`
`'here'`	`[0, 0]`
`'everyone'`	`[1, 0]`

Ids may be passed dashed or undashed. The backend validates direct mention ids as uuids and silently discards targets that are not members of the server.

parseMentions

parseMentions(content: string): MessageMentions

Recovers the mentions carried by a decrypted message body. This is how the real clients decide “was I mentioned”. The ping array a sender supplies is routing metadata the server consumes and never echoes back, so the decrypted text is the only inbound source. Message.mentions and Message.mentionsMe are produced by this function, and fetched history is populated identically.

const parsed = parseMentions('hey &lt;@0f1e2d3c4b5a69788796a5b4c3d2e1f0&gt; and @Moderators');
parsed.userIds;  // ['0f1e2d3c4b5a69788796a5b4c3d2e1f0']
parsed.names;    // ['Moderators']
parsed.everyone; // false

@Everyone and @Here are matched case-insensitively, exactly like the clients.

EVERYONE and HERE

const EVERYONE = '@everyone';
const HERE = '@here';

The literal pill text for the two broadcast mentions. Pair each with the matching target, because text alone notifies nobody.

await client.send(serverId, channelId, `${EVERYONE} maintenance in 5`, {
  mentions: ['everyone'],
});

MENTION_ENTITY_RE

const MENTION_ENTITY_RE: RegExp

Matches a user-mention wire entity, raw or HTML-escaped, dashed or raw hex. Exported so you can scan text yourself without re-deriving the pattern.

It carries the global flag. Reset MENTION_ENTITY_RE.lastIndex = 0 before every use, or a second scan starts wherever the previous one stopped. Prefer parseMentions() unless you specifically need the raw matches.

Types

MentionTarget

type MentionTarget =
  | { userId: string }
  | { roleId: string }
  | 'everyone'
  | 'here';

What SendOptions.mentions accepts. Ids may be dashed or undashed.

MentionPair

type MentionPair = [string | number, 0 | 1];

One entry of the plaintext ping array. The second element is 1 for a role and 0 for everything else.

MessageMentions

What parseMentions() returns, and the shape of Message.mentions.

string[]

Normalized (undashed, lowercase) ids of the user-mention entities in the body.

string[]

Literal @name tokens that are neither @everyone, @here, nor an id entity. A name may be a role, an older-format user mention, or just text. The SDK cannot tell them apart without the server’s role list.

boolean

The body contains @everyone, case-insensitively.

boolean

The body contains @here, case-insensitively.

Message.mentionsMe covers direct mentions only. A role mention cannot be resolved to “this means me”: the SDK does not know which roles the bot holds, because permission verdicts carry an effective rank rather than role ids. Compare names against guild(serverId).fetchRoles() if you need that.

Do not compare names against fetchMembers(). That method is broken against every current backend: it awaits a frame the backend no longer sends, so it neither resolves nor rejects, and awaiting it hangs your handler. fetchRoles() works.

Mentions and replies

The two-part model, and true replies.

Sending messages

Where SendOptions is documented.

Encryption lanes

What leaves the encrypted envelope, and why.

Types

Message, SendOptions, and the rest.

Get started

Core concepts

Messaging

Slash commands

Embeds and cards

Voice

Server management

Advanced

Running in production

Examples

API reference

Reference

userMention

roleMention

mentionPairs

parseMentions

EVERYONE and HERE

MENTION_ENTITY_RE

Types

MentionTarget

MentionPair

MessageMentions

Next

Mentions and replies

Sending messages

Encryption lanes

Types

​userMention

​roleMention

​mentionPairs

​parseMentions

​EVERYONE and HERE

​MENTION_ENTITY_RE

​Types

​MentionTarget

​MentionPair

​MessageMentions

​Next

Mentions and replies

Sending messages

Encryption lanes

Types

userMention

roleMention

mentionPairs

parseMentions

EVERYONE and HERE

MENTION_ENTITY_RE

Types

MentionTarget

MentionPair

MessageMentions

Next