Skip to content

The /privacy command

createPrivacyCommand(lens) gives you a /privacy command with four subcommands. Replies are ephemeral, so only the user sees them.

Subcommand What it does
/privacy info Explains what the bot records, with a link to your privacy policy
/privacy optout Stops recording the user’s usage
/privacy optin Allows recording again
/privacy erase Deletes what was recorded about the user that the bot can still find, and opts them out

The command works in servers, in DMs with the bot and in private channels, for both server and user installs.

bot.ts
import { createPrivacyCommand, createShardlens } from '@shardlens/discordjs';
import { Client, Events, GatewayIntentBits, REST, Routes } from 'discord.js';
// Your own storage for opt-outs (a database table, a JSON file…).
declare function loadOptOuts(): Promise<string[]>;
declare function saveOptOut(userId: string, optedOut: boolean): Promise<void>;
const client = new Client({ intents: [GatewayIntentBits.Guilds] });
const lens = createShardlens(client, {
endpoint: process.env.SHARDLENS_URL!,
apiKey: process.env.SHARDLENS_INGEST_KEY!,
optedOut: await loadOptOuts(), // users who opted out before this restart
// It may be async: a failed save is counted (see lens.on('error')), never thrown into your bot.
onOptOutChange: (userId, optedOut) => saveOptOut(userId, optedOut),
});
const privacy = createPrivacyCommand(lens, { policyUrl: 'https://example.com/privacy' });
// Register it with your other commands (once, from a deploy script).
const rest = new REST().setToken(process.env.DISCORD_TOKEN!);
await rest.put(Routes.applicationCommands(process.env.DISCORD_APP_ID!), { body: [privacy.data] });
client.on(Events.InteractionCreate, async (interaction) => {
if (interaction.isChatInputCommand() && (await privacy.handle(interaction))) return;
// … your other commands
});

Opt-outs live in the SDK’s memory. To keep them across restarts, save them in onOptOutChange and pass them back in optedOut when the bot starts, as above. An opted-out user’s events are dropped inside your bot, before hashing.

/privacy erase calls lens.forgetUser(). You can call it yourself, for example from support tooling:

import type { Shardlens } from '@shardlens/discordjs';
declare const lens: Shardlens;
// For example from your support tooling, after a verified erasure request.
export async function eraseUser(userId: string) {
lens.optOut(userId); // stop collecting in this process (persist it with onOptOutChange)
const result = await lens.forgetUser(userId); // never throws; undefined if the collector couldn't be reached
return result?.erased ?? 0;
}

The collector deletes the user’s raw events, unique-user rows, install and premium rows, and in audit mode their encrypted activity. Aggregate counts are kept, because they are anonymous. Every erasure is logged.

How far back it reaches depends on who can still compute the user’s hash:

  • From the bot, in privacy mode, the user’s rows are found by hash, and the bot holds only the current salt and the previous one. With a monthly or weekly salt that is every period that can still be linked to the user. With a daily salt, the days before yesterday keep their rows until their salt is destroyed, a week after each day ends; from then on nobody can link them to the user.
  • From the dashboard (Settings → Privacy), which takes an exact user ID, and from the bot in audit mode, the collector hashes the ID with every salt that still exists, so every period that can still be linked is erased.

The /privacy erase reply says what was done in those terms: what the bot can link to the user was deleted, and anything older expires on its own. See the privacy model.

forgetUser first sends whatever the SDK still has queued, so nothing about the user arrives after the erasure. It resolves to { erased }, the number of stored rows that were deleted: 0 means nothing was stored about them, or it had already expired. It resolves to undefined when the collector couldn’t be reached, so you can try again.

npx shardlens privacy prints a privacy-policy paragraph that matches your configuration, for example:

Terminal window
npx shardlens privacy --option-values language --webhook-events --retention 35