Manual

Quick Start

Five steps from an empty server to a working one.

This is the assembly guide for your server. Follow the five steps in order and you will have a bot that greets, gates, rewards and moderates your community. Each step links to a fuller page if you want detail.

The five steps

1. Invite the bot. Use your invite link and, on Discord's screen, keep the “Manage Roles”, “Manage Channels” and “Manage Server” permissions ticked. Make sure the invite includes the applications.commands scope, or the slash commands never appear.
2. Give it room to work. In Server Settings → Roles, drag the bot's role ABOVE every role it will hand out (Guest, region roles, level roles, etc.). A bot can only manage roles that sit below its own. See the Bot Permissions page.
3. Create the structure. Fastest way: install a Template (a ready-made set of categories and channels). Or build the events area with Events Hub. Nothing is created until you press the button: you always preview first.
4. Map your roles and channels. Open Server Config and tell the bot which of your Discord roles is “Guest”, which channel is the verification channel, and so on. Verification, regions, protection and scoring do nothing until these are mapped.
5. Turn on what you want. Open Control Center and flip the switches for the modules you'll use: XP, Greeting, Raffles, Protection, and the rest. Disabled modules stay hidden and idle. Done, your server is live.

In a hurry? Steps 1, 2 and 5 are the minimum to get a bot that responds. Steps 3 and 4 are what make it feel like your community.

XP & Levels

Reward chatting with XP, levels and automatic level-up roles.

What it does

Members earn XP for sending messages. XP adds up into levels, and you can attach a Discord role to any level so people are rewarded automatically as they climb. There is also a daily reward with a streak bonus, and an optional leaderboard.

Why use it

It gives quiet lurkers a reason to talk and gives your most active members visible status. It's the simplest way to make a server feel alive.

Setting it up

1. Turn the module on (top of the XP page, or in Control Center).
2. Set XP per message and the cooldown (the pause before a message counts again. This stops spam-farming).
3. Set the daily reward and streak bonus if you want people to return every day.
4. Add level-reward roles: pick a level and the role to grant at it. The bot assigns them automatically.
5. Optionally tune the level curve to make levelling faster or slower. The preview shows the XP needed per level.

Bot permissions needed

• Manage Roles: to grant level-reward roles. The bot's role must sit above every reward role.
• Read messages in the channels where you want XP earned.

If you don't set it up

With the module off, no XP is counted and no roles are granted: nothing breaks, the feature simply sleeps. If it's on but you added no level roles, members still gain XP and levels but receive no roles.

Common mistakes

• Reward role sits above the bot's role → the bot can't grant it. Move the bot up.
• Cooldown set to 0 → members farm XP with one-word spam. Keep a few seconds.

Who can open this: Admin access level or higher (see Roles & Access).

Greeting Signal

A signature word members type to say hello: rewarded with XP and a reaction.

What it does

You choose a signature greeting word. When a member types exactly that word in the greeting channel, the bot reacts with an emoji and awards a little XP. It's a small daily ritual that builds community identity. You can optionally make the channel strict: deleting anything that isn't the greeting.

Setting it up

1. Turn the module on.
2. Set the trigger word (the greeting itself). Choose whether case matters.
3. Pick the greeting channel. Leave it blank to accept the greeting anywhere.
4. Set the reaction emoji and the XP reward per greeting.
5. Optional: turn on strict mode to delete non-greeting messages, and a per-user cooldown so it can't be farmed.

Bot permissions needed

• Add Reactions: to react to the greeting.
• Manage Messages: only if you use strict mode / delete wrong messages.

If you don't set it up

Off by default. Nothing happens until you enable it and set a word. On free plans the greeting word is fixed to the default; customizing your own word is a paid perk (see Plans).

Common mistakes

• Strict mode on in a normal chat channel → real conversation gets deleted. Use a dedicated greeting channel.
• Bot lacks Manage Messages → strict mode silently fails to delete.

Who can open this: Admin access level or higher (see Roles & Access).

Raffles

Run giveaways with a Join button; winners drawn automatically. Prizes can be XP, roles, fast entry, or a wallet claim.

What it does

You post a raffle; members click Join; when it ends the bot picks winners at random and announces them. Prize types: FAST (bragging-rights / quick draw), XP (award experience), ROLE (grant a Discord role), and WALLET (winners click Claim and submit a wallet address you collect). Raffles can also be automatic/recurring on a schedule.

Setting it up

1. Turn the module on.
2. Create a raffle: give it a title, choose the prize type, the number of winners, and when it ends.
3. For a ROLE prize, pick the role to grant. For WALLET, winners will be asked for an address after they win.
4. Publish. Members see the embed and a Join button.
5. Optional: set up automatic raffles that repeat on a schedule (paid plans).

Bot permissions needed

• Send Messages / Embed Links, to post the raffle.
• Manage Roles: only for ROLE prizes, and the reward role must be below the bot's role.

If you don't set it up

No raffles run until you create one. Free plans cap how many raffles you can create per month and don't allow automatic raffles, see Plans.

Common mistakes

• ROLE prize role above the bot → winners can't be given the role.
• Hitting the monthly raffle limit on a free plan → upgrade or wait for the next month.

Who can open this: Admin access level or higher (see Roles & Access).

Quizzes

Project-knowledge trivia. Questions are built only from your own text, never invented.

What it does

Quizzes test what your members know about your project. You can write questions by hand, or paste your own project text and the generator turns it into fill-in-the-blank questions by hiding key words. It never makes up facts: every answer comes straight from the text you provided. Correct answers award XP.

Setting it up

1. Turn the module on.
2. Create a quiz by hand, or paste project text and let the generator draft fill-in-the-blank questions from it.
3. Review the questions, then publish. Members answer and earn XP for correct answers.
4. Close the quiz when you're done, or set auto-scheduling on paid plans.

If you don't set it up

Off by default. Nothing is posted until you create and publish a quiz.

Common mistakes

• Pasting a tiny snippet → the generator has too few key words to hide. Give it a few full sentences.
• Expecting invented trivia. It only asks about text you supply. That's by design.

Who can open this: Admin access level or higher (see Roles & Access).

Rumble Arena

A last-one-standing battle mini-game with round-by-round eliminations.

What it does

Members press Join, then the bot runs a fun battle in rounds, eliminating players with playful messages until one winner remains. It announces the winner and the top three. The winner can receive XP, a role, or nothing (just glory).

Setting it up

1. Turn the module on.
2. Start a battle manually, or set an auto-schedule so it runs on its own.
3. Choose the winner reward: XP, a role, or none.

Bot permissions needed

• Send Messages / Embed Links, to run the battle.
• Manage Roles: only if the winner reward is a role.

If you don't set it up

Nothing runs until you start a battle or enable auto-scheduling. Free plans cap how many battles can be started per month (see Plans).

Who can open this: Admin access level or higher (see Roles & Access).

Events Hub

One click builds the events area: category, channels, permissions and pinned intros.

What it does

Events Hub creates the home for your engagement modules in one go: an events category with channels for announcements, raffles, quizzes, rumble, rank-checking and logs, with the right permissions and a pinned intro message in each. It's the fastest way to give raffles and quizzes somewhere to live.

Setting it up

1. Open Events Hub and review what will be created: nothing happens until you press Create.
2. Press Create. The category, channels and pinned intros appear.
3. Later you can delete or hide what it made from the same place (teardown).

Bot permissions needed

• Manage Channels: to create the category and channels.
• Manage Messages / Send Messages: to post and pin the intros.

If you don't set it up

Engagement modules still work, but their announcements have no dedicated channels. You'd point each module at your own channels instead. Events Hub just saves you that manual work.

Who can open this: Admin access level or higher (see Roles & Access).

Protection

Anti-raid and moderation guards: warnings, timeouts, spam detection, domain blacklist, user whitelist.

What it does

Protection watches for trouble and helps your staff respond. It records warnings, applies timeouts, detects spam bursts, blocks messages containing blacklisted domains, and lets you whitelist trusted members. Moderation actions respect a hierarchy: staff can't action someone above their own tier.

Setting it up

1. Map your logs channel in Server Config so raid alerts and security logs have somewhere to go.
2. Open Protection to review warnings, spam events, the domain blacklist and the user whitelist.
3. Add domains you want blocked and whitelist members who should never be auto-actioned.

Bot permissions needed

• Moderate Members (Timeout), to time out offenders.
• Kick / Ban Members: for the corresponding actions.
• Manage Messages: to remove spam / blacklisted links.

If you don't set it up

Without a logs channel you won't see alerts. Moderation targeting also needs your staff (TEAM) role mapped so the hierarchy check knows who outranks whom.

This is a home-community page: it appears only when your own server is selected, not for a managed client guild.

Who can open this: Moderator access level or higher.

Verification

A captcha gate: new members prove they're human to get the Guest role and access.

What it does

New members see a verification panel and must pass a quick challenge (they have a short time limit). On success the bot grants the Guest role, which unlocks the rest of the server. It keeps out bots and raiders. GitHub Builder verification is a separate, optional path to a Builder role (see GitHub Builder).

Setting it up

1. In Server Config, map the Guest role and the verification channel.
2. Post the verification panel to that channel (via Panels).
3. Set your other channels so only Guest (and above) can see them: verification then becomes the real gate.

Bot permissions needed

• Manage Roles: to grant the Guest role. The bot's role must sit above Guest.
• Send Messages / Embed Links: to post the verification panel.

If you don't set it up

If the Guest role isn't mapped or the bot can't grant it, members pass the captcha but get no role: the server won't open. Map the role and fix the role order first.

This is a home-community page: it appears only when your own server is selected.

Who can open this: Admin access level or higher (see Roles & Access).

Genesis (NFT holders)

Optional: let members prove on-chain NFT ownership to receive a role.

What it does

Genesis lets holders of a specific NFT collection verify ownership and receive a special role. It's an opt-in module: off unless you turn it on and provide your chain and contract.

Setting it up

1. Open Modules and find Genesis.
2. Enter the chain ID and the NFT contract address, and the role key to grant.
3. Turn it on. The switch stays locked until a contract address is provided.

Bot permissions needed

• Manage Roles: to grant the holder role (must sit below the bot's role).

If you don't set it up

It stays off and invisible. A non-crypto community can ignore it entirely.

Who can open this: Admin access level or higher (see Roles & Access).

GitHub Builder

Optional: members connect GitHub to earn a Builder role, gated by repo and account age.

What it does

Builder verification lets members connect their GitHub account to apply for a Builder role. You can require a specific repository and a minimum account age, so the role reflects real contributors. It's an opt-in module. Members usually must be verified (have Guest) first.

Setting it up

1. Open Modules and find GitHub Builder.
2. Enter the required repository (owner/repo), the owner username, and the minimum account age in days.
3. Turn it on (locked until a repo is set).

Bot permissions needed

• Manage Roles: to grant the Builder role (below the bot's role).

If you don't set it up

It stays off. Communities that aren't developer-focused can leave it disabled.

Who can open this: Admin access level or higher (see Roles & Access).

Server Builder

A live editor for roles, channels and permission overwrites: build your server from the dashboard.

What it does

Server Builder lets you create and edit roles, channels and their permission overwrites directly from the dashboard, without touching Discord's own settings. It checks that the bot has the permission and role position to make each change, and warns you if a role is still in use by a module before you remove it.

Setting it up

1. Open Server Builder. You'll see your roles and channels.
2. Add, rename or reorder roles; create channels; set who can see or post in each.
3. The editor blocks changes the bot can't perform (e.g. moving a role above itself) and explains why.

Bot permissions needed

• Manage Roles and Manage Channels. This is the core of what it edits.
• The bot's role must sit above any role you want it to edit or move.

Deleting a channel or role is irreversible in Discord. The builder warns you when a role is still used by a module: read those warnings before confirming.

Who can open this: Admin access level or higher (see Roles & Access).

Server Config

Map your Discord roles and channels to the modules. Nothing works until these are set.

What it does

This is the wiring page. The bot doesn't guess which of your roles is “Guest” or which channel is for verification. You tell it here. Verification, regions, protection, scoring and the access system all read these mappings. You can also create a new role or channel right from this page and map it in one step.

What you map

• Roles: Guest (base access after verification), Builder, region roles, Team (staff: unlocks dashboard and moderation), and optional roles like Genesis.
• Channels: the verification channel, the region-select channel, general chat (slowmode target in emergencies) and the logs channel for security alerts.

Setting it up

1. Open Server Config. Each row shows a status: Configured, Configured (env) or Needs setup.
2. For each item, pick an existing role/channel, or create a new one, and save.
3. Aim to clear every “Needs setup” that a module you use depends on.

This is the single most important page. If a feature “does nothing”, check its mapping here first.

Who can open this: Admin access level or higher (see Roles & Access).

Templates

Install a ready-made server structure (categories and channels) in one click.

What it does

A template is a pre-designed layout. A gateway area, official channels, a community zone, regions and an events hub, installed at once so you don't build from scratch. It creates channels and categories; roles and integrations are configured separately. You can also uninstall a template later, which removes the channels it created (roles are left untouched).

Setting it up

1. Open Templates and browse the presets.
2. Pick one and install it. Review before confirming: it creates real channels.
3. Then finish setup in Server Config (map roles/channels) and Control Center (turn on modules).

Bot permissions needed

• Manage Channels: to create the categories and channels.

Free plans can install one basic “clean setup” template; paid plans unlock every preset (see Plans).

Who can open this: Admin access level or higher (see Roles & Access).

Panels

Edit the Discord gateway panels (verification, regions, welcome) and publish them without code.

What it does

Panels are the interactive messages the bot posts in Discord. The verification panel with its button, the region-select panel with its dropdown, the welcome message. Here you edit their text, preview them, and publish (or re-publish) to a channel without touching code. You can also reset a panel to its default.

Setting it up

1. Make sure the target channels are mapped in Server Config first.
2. Open Panels, pick a panel, edit its text and preview.
3. Publish it to Discord. Re-publish after edits to update the live message.

Bot permissions needed

• Send Messages / Embed Links in the panel's channel.

This is a home-community page: it appears only when your own server is selected.

Who can open this: Admin access level or higher (see Roles & Access).

Regions

Let members pick their region from a panel and get the matching role (one per member).

What it does

Regions group your community by location or language. A member picks their region from a dropdown panel and the bot assigns the matching role: swapping it if they change region, so each member has exactly one. Region roles are also used for regional helpers/moderators.

Setting it up

1. In Server Config, map each region to a Discord role and set the region-select channel.
2. In Panels, publish the region-select panel to that channel.
3. Members use the panel (or the /region command) to choose. Requires the Guest role.

Bot permissions needed

• Manage Roles: to assign region roles (each region role must sit below the bot's role).

If you don't set it up

If a region has no role mapped, choosing it tells the member the region isn't configured. Map every region you offer.

Who can open this: Admin access level or higher (see Roles & Access).

Branding

Your display name, logo and embed color across the bot and this dashboard.

What it does

Branding controls how your community is presented: the display name shown in embed titles/footers and the dashboard sidebar, your logo, and the accent color used in the bot's embeds. Blank fields fall back to a neutral default (your server name), so it's safe to leave anything empty.

Setting it up

1. Open Branding and set your display name.
2. Add a logo URL and an embed color (hex, e.g. #8b5cf6).
3. Save. Changes appear in the bot's embeds and the sidebar.

The “powered by” line in bot embeds is removed only on the top plan (see Plans).

Who can open this: Admin access level or higher (see Roles & Access).

Control Center

The dashboard home: see every module's status and switch them on or off in one place.

What it does

Control Center is your overview page. It gathers every module: XP, Greeting, Raffles, Quizzes, Rumble, Events, Protection, Verification, Genesis, GitHub, Panels, Regions, and shows whether each is on or off, with a switch for each. Flip a switch here and it saves through the same settings the module's own page uses.

How to use it

1. Open the dashboard home (Control Center is the first item in the sidebar).
2. Scan the module cards to see what's active.
3. Toggle any module on/off. For deeper settings, open that module's own page.

This page loads everything in a single request, so it's the cheapest place to check status: it won't chew through your rate limit.

Who can open this: Viewer access level or higher.

Plans

What each subscription tier includes. New servers get a one-time 7-day PRO trial.

How plans work

Higher tiers raise the caps on raffles and rumble battles, unlock automatic/recurring events, a custom greeting word, all templates, longer log history, and (top tier) removing the “powered by” branding. A brand-new server gets a one-time 7-day PRO trial automatically; when it ends the server drops to FREE with no loss of data.

There is no payment provider wired in. The price grid is informational and the owner sets a server's tier manually (Admin → Subscriptions). An expiry in the past reverts a server to FREE automatically.

Bot Permissions

Which Discord permission each feature needs, and what breaks without it.

Discord permissions decide what the bot is allowed to do. Grant these when you invite the bot (or in Server Settings → Roles → the bot's role). Two rules matter most: the bot needs the permission, AND, for anything role-related, the bot's role must sit ABOVE the roles it touches.

Permission by permission

• Manage Roles: grant Guest, level roles, region roles, Builder, Genesis and raffle/rumble role prizes. Without it, no role is ever handed out.
• Manage Channels: create categories and channels for Templates, Events Hub and Server Builder. Without it, structure can't be built.
• Manage Server: needed by some setup actions. Recommended at invite time.
• Send Messages & Embed Links: post panels, raffles, quizzes, rumble and announcements. Without them the bot stays silent.
• Manage Messages: pin intros (Events Hub), delete wrong greetings (strict mode), remove spam/blacklisted links (Protection).
• Add Reactions: react to the greeting word.
• Moderate Members / Kick / Ban: Protection timeouts, kicks and bans.

The #1 cause of “the bot won't give roles” is role order, not a missing permission. Drag the bot's role to the top of the list.

Roles & Access

The dashboard access levels: who can see and change what.

Access to this dashboard is tiered. Each person is granted a level (on the Access page, by the Owner). A level can do everything below it plus its own powers. This is separate from Discord roles: it controls the dashboard, not the server.

The five levels

• Viewer: read only. Sees analytics, members, logs, Control Center. Changes nothing.
• Moderator: Viewer + moderation: Protection, warnings, member actions.
• Admin: Moderator + configuration: modules, XP, panels, roles, verification, branding, settings.
• Deputy: Admin + extra trust, but still NOT the most critical actions.
• Owner. Everything, including irreversible actions and granting access. Only the configured Owner is Owner.

Critical actions (deleting channels, resetting stats, granting access) are reserved for the Owner exactly: never delegated, not even to a Deputy.

Trust & Safety

How payments work, what we can and cannot touch, and what you can verify yourself.

A Discord bot that accepts cryptocurrency looks, from the outside, like something you should be careful with. That is a reasonable instinct. Rather than ask you to trust us, this page describes exactly what happens to your money and your data: most of which you can check without taking our word for any of it.

We never hold your money

There is no wallet you top up, no balance we keep for you, and no smart contract holding funds. A payment is one ordinary transfer from your wallet straight to ours. Nothing sits in between, so there is nothing to be drained, frozen or lost, and nothing for us to run away with, because at no point are we holding anything of yours.

Every payment is public

Payments happen on Base, a public blockchain. The address you send to is shown before you pay and is the same for everyone. After paying you can open any block explorer, paste the transaction, and see the amount, the time and both wallets. We cannot alter that record and neither can anybody else.

• The amount and the receiving address are shown before you send anything.
• A transfer is checked against the blockchain itself, not against anything we type in.
• Sending less than the price is not lost: it counts, and you send the difference.
• One transfer can only ever pay for one subscription: a transaction cannot be reused.

What the bot can and cannot do

When you add the bot, Discord shows you the exact list of permissions it asks for, and you can read it before agreeing. It deliberately does not ask for Administrator. A bot with Administrator can do anything, and you would have no way to see what it actually does. Everything it needs is requested individually, so the list itself tells you the limits.

You can remove it at any time from your server settings. Removing it stops everything immediately; your configuration is kept for a while in case you come back, and your members keep their levels and history either way.

What we store

• Discord IDs and display names of your members: the minimum needed to award XP and roles to the right person.
• Your server's settings: which modules are on, channels, schedules, branding.
• An email address, only if you consent to it at sign-in, and only to tell you when a subscription is about to lapse.
• Message CONTENT is never stored. XP counts that a message happened; it does not keep what it said. The spam filter needs to recognise the same message sent twice, so it keeps a one-way fingerprint of the last few: for seconds, and it cannot be turned back into text.

Being honest about what this is not

• The payment verifier, the spam filter and the complete data model are published at github.com/maysonkiller/artsoul-os-transparency: the actual code, not a description of it.
• How to report a security problem, and what we promise in return, is at artsoul-os.com/.well-known/security.txt
• The bot carries Discord's verified badge. Worth knowing exactly what that is: Discord verifies the identity of the team behind an app and lets it grow past 100 servers. It is not a security audit, and we do not present it as one.

There is no third-party security audit yet, and we would rather say so than buy a badge. Not having a smart contract removes one class of risk, and it is worth being precise about what that does not remove: a review of the dashboard, the authorisation between servers, session handling and the payment logic would still have plenty to look at, and we intend to have one. Until then, what is checkable is above, plus the code we publish.

If something here does not match what you see, write to us. The address is at the bottom of the sidebar and on the sign-in page. A question about security gets an answer from a person.

How to tell a real message from us

A product that takes crypto payments attracts people who impersonate it. Two things make that harder, and both are worth knowing.

• Every email from us comes from [email protected]. The domain publishes SPF, DKIM and a DMARC policy, so a forged message from that address is flagged or filtered by the receiving mail server rather than reaching you looking genuine.
• We never ask for a password, a seed phrase or a wallet's private key, and we never send a payment address by email. The address is shown in the dashboard before you pay, and that is the only place it comes from.

If a message asks you to send funds somewhere new, or to confirm a wallet, treat it as fake no matter how it looks. Open the dashboard and check there, and write to us at the address above.

Who builds this

The same small team builds ArtSoul, a separate protocol with its own site and public work. That is worth knowing for one reason only: it is a second place to look at what we ship and how long we have been shipping it. The two products share no data and no accounts: ArtSoul OS never touches the protocol, and vice versa.

• Protocol site: artsoulprotocol.com
• Protocol on X: @ArtSoulProtocol

FAQ & Troubleshooting

The common “why isn't this working?” answers.

The slash commands don't appear

The bot was invited without the applications.commands scope. Re-invite it using a link that includes that scope. Commands can also take a little while to register the first time.

The bot won't give out roles

Almost always role order. A bot can only manage roles below its own. In Server Settings → Roles, drag the bot's role above every role it should grant. Also confirm it has Manage Roles.

A page won't load

Use the Refresh button on the page. If it persists, your session may have expired: log out and back in. Some pages (Members, Protection, Logs, Panels, Verification) only work for your own home server, not a managed client guild.

“Too many requests” / rate limit

The dashboard limits how many requests it makes to stay fast and fair. If you hit it, wait a moment and it clears. You won't be logged out. Control Center is the lightest page to check status.

The bot seems asleep / slow first response

On some hosting the database sleeps when idle and takes a few seconds to wake on the first action. The second action is fast. If it never wakes, check that the services are running.

A feature does nothing

Two checks: is the module turned on in Control Center, and are its roles/channels mapped in Server Config? Most “it doesn't work” cases are one of these two.