carl.
Add Carl
Documentation

Get Carl
set up.

Everything you need to add Carl to your Yapper community and run this website.

Overview

Carl is a multipurpose moderation and community bot built specifically for Yapper. It brings moderation tools, welcome messages, logging, leveling, custom commands and reaction roles into one bot.

Documentation status

Sections about the bot describe the intended setup. Anything not yet confirmed against the bot's source is labelled as unverified.

01

Invite Carl

Add Carl to your server with the official invite link.

02

Check permissions

Grant only what the enabled features need.

03

Configure modules

Set up welcome, logging, moderation and more.

Invite Carl

Invite link not configured yet

No official invite URL has been set for this site, and a guessed link would be worse than none. Site owners: add your real URL to js/config.js.

js/config.js
window.CARL_CONFIG = {
  inviteUrl: "https://your-real-invite-url",
  siteUrl: "https://carl-yapin.best"
};

Once inviteUrl is set, every “Add Carl” button on the site opens it automatically.

Permissions

Give Carl only the permissions needed for the features you enable. As a rule of thumb:

  • Moderation tools need the matching moderation permissions.
  • Welcome messages and logs need permission to send messages in the chosen channels.
  • Reaction roles need permission to manage the roles they assign.

The exact permission names depend on Yapper, so check them in your server's role settings.

Configure modules

Welcome & goodbye

Customize join and leave messages with the server and member details Carl supports.

Moderation & logging

Enable moderation tools and choose which events are logged and in which channel.

Leveling

Reward participation with activity levels and optional level-up announcements.

Custom commands & reaction roles

Create repeatable responses and let members pick their own roles.

Message variables are unverified

The dashboard preview uses {user}, {server} and {level} as sample placeholders. Confirm the real variable names against the bot before relying on them.

Using commands

Browse everything in the command directory. The prefix shown there (c!) and the example commands are unverified until the real list is added to js/commands-data.js.

js/commands-data.js
// one entry per real command
{ name: "ping", category: "general",
  description: "…", usage: "c!ping", verified: true }

Dashboard

The dashboard is currently a front-end preview. It is not connected to Yapper sign-in or to Carl's configuration store, so it cannot change a live server. You can write drafts, which are stored only in your own browser.

Dashboard login

The dashboard requires signing in with Yapper using a standard OAuth 2 authorization-code flow (with state and PKCE) handled by Pages Functions. The browser never sees your client secret or access token; it only receives a signed, HttpOnly session cookie.

You must supply Yapper's OAuth details

Nothing here is guessed. Register an application with Yapper, then copy its real endpoints and credentials into the values below.

YAPPER_CLIENT_ID
Your app's client ID.
YAPPER_CLIENT_SECRET
Your app's client secret (store as a secret).
YAPPER_AUTH_URL
Yapper's authorization endpoint.
YAPPER_TOKEN_URL
Yapper's token endpoint.
YAPPER_USER_URL
Endpoint returning the signed-in user's profile as JSON.
YAPPER_SCOPES
Optional. Space-separated scopes.
YAPPER_SERVERS_URL
Optional. Endpoint listing the user's servers, for the server picker.
SESSION_SECRET
Long random string used to sign sessions.

Register this redirect URI with Yapper: https://carl-yapin.best/api/auth/callback

Generate a session secret
openssl rand -base64 48

If Yapper's profile or server JSON uses different field names, adjust normalizeUser and normalizeServers in api/auth/callback.js.

Deploy the website

For site owners. This site is deployed on Vercel from GitHub. The login, status and admin features run as Vercel Functions, and homepage uploads use Vercel Blob.

  1. Push the project to GitHub and import it in Vercel (framework: Other, no build command).
  2. In Vercel, Storage → create a Blob store and connect it to the project.
  3. Add the environment variables below (mark secrets as Sensitive).
  4. Add your domain under Settings → Domains.
Terminal
git push   # Vercel deploys automatically on every push
BLOB_READ_WRITE_TOKEN
Added automatically when you connect a Blob store.
SITE_URL
Optional. https://carl-yapin.best
ADMIN_PASSWORD
Protects the admin page and uploads.
BOT_STATUS_URL
Optional HTTPS endpoint. Optional JSON: online, servers, users.
Security

Never put your bot token in front-end files. For production, add Vercel password protection or an IP allow-list for /admin.html, and use a long unique ADMIN_PASSWORD.

Troubleshooting

Admin says 503
ADMIN_PASSWORD is not set in Vercel.
Admin API unreachable
Functions only run on the deployed site (or vercel dev), not a plain static preview.
Upload rejected
Only GIF, PNG, JPG and WebP up to 4 MB are accepted (a Vercel request limit).
Hero shows the bundled GIF
No custom image is stored, or no Blob store is connected.
Status says “not connected”
BOT_STATUS_URL is not set, so no bot status can be reported.