Start here

Your rating bot, explained.

A practical handbook for members, raters, and the people running the server.

4 media per ticket4 rater ranks14 tiers per scale

Find your starting point

The usual ticket journey

  1. A member clicks Request Rating in the server's request channel.
  2. The bot opens a private ticket using the member's configured Male or Female role.
  3. The member uploads 1–4 photos or videos, checks the preview, and clicks Submit for Rating. If questions are enabled, they complete a short form.
  4. Authorized raters choose tiers. The bot combines their weighted votes using the server's scoring mode.
  5. Once the weighted vote target is reached, a Senior Rater, Head Rater, or Administrator can assign the result.
  6. The role is applied and the member receives an Accept Role / Deny Role DM. Staff can then close the ticket.

A few Discord basics

TermWhat it means here
Slash commandType / in a server message box, choose this bot, then select a command. You don't type the square brackets shown around optional inputs in this guide.
RoleA server badge that can give permissions. This bot uses role IDs, so a similar role name alone does not grant access.
TicketA channel for one member's rating session. It is visible to that member, mapped raters, the bot, and administrators.
EmbedA formatted bot message. Buttons below it perform actions; opening a menu is not the same as submitting it.
Private responseA response Discord marks as visible only to you. This is different from a private ticket, which raters can also read.
RateeThe person being rated.
MappingConnecting an existing Discord role or channel to a function in the bot's settings.

About this edition

This guide was checked against rating-ticket-bot.zip, package version 1.0.0, on 16 November 2026. It describes the uploaded code, not a connected live server. Your administrator can change settings and role names. Names such as Verified Rater in this guide refer to the configured rank, even if your server uses a different name.

The uploaded build differs from the earlier design: it accepts four media files, uses weighted votes, and has level-based promotion applications with staff approval. The build notes explain the remaining differences and operating limits.

Use Search to find a command, button, or error. Every article has its own link. You can download the complete guide or open a printable copy.

Members

Request a rating

Open the right ticket and know who can see it.

Before you begin

You need exactly one of the two gender-routing roles configured by the server: Male or Female. The bot uses that role to select a voting scale; it does not infer gender from a photo. If you have both roles or neither, ask an administrator to correct your roles.

A server may require a whitelist role or block a blacklist role. If both apply, the blacklist takes priority. Administrator status only bypasses the rating cooldown; it does not bypass these access or gender checks.

Open your ticket

  1. Find the server's rating request channel.
  2. Click Request Rating under the bot's panel.
  3. Follow the private response's channel link to your new ticket.
  4. Read the welcome message, then attach your files to that ticket. Continue with upload and submit.

The ticket name contains a gender icon and a version of your username. Its permissions allow you, all configured rater ranks, and the bot to read it. Server administrators can also see it. This is a shared staff ticket, not a private conversation with only the bot.

If a ticket won't open

Message or situationWhat to do
Missing or conflicting gender rolesAsk an admin to give you exactly one configured routing role.
Whitelist required or blacklist restrictionAsk server staff about access. Removing a cooldown does not remove a role restriction.
You already have an active ticketUse the channel link in the response. Complete or close that ticket first.
Cooldown activeWait for the time shown. The standard setting is seven days after assignment.
Channel creation failsAsk an admin to check the category, bot permissions, and server channel capacity.
No panel is visibleAsk an admin to deploy it. Members do not need a ticket-opening slash command.

Returning for another rating

The cooldown starts when a result is assigned, not when you first open a ticket. Closing a ticket or denying its role does not remove that cooldown. The standard duration is seven days, but the server can change it.

Once your assigned ticket's cooldown permits another request, the bot can open a new ticket. An older assigned channel may remain visible until staff delete it; it is not automatically removed by opening the new ticket.

Before you submit, you can use Close Ticket to cancel the channel. After submission, ask Senior staff or an administrator to close it.

Members

Upload, check, and submit

Keep control of the draft before voting begins.

Add 1–4 files

Send photos or videos as Discord attachments inside your own ticket. You may attach them in one message or across multiple messages, up to four files total. Photos and videos share the same limit. Pasting a link alone does not add a file to the draft.

Recognized file extensions include PNG, JPG/JPEG, WEBP, GIF, MP4, MOV, and WEBM. Files identified as images or videos by their media type are also accepted. Discord's upload limit still applies; the bot does not provide a larger upload allowance.

The bot copies accepted uploads, removes the original upload message, and creates a Confirm Your Submission preview with the files attached. Check that every file you intended to submit is visible. If an upload fails to download, it may not reach the preview even though the original message disappears.

Review the preview

Button or actionResult
Upload another supported attachmentAdds it to your current draft if there is room. The confirmation is replaced with an updated preview.
Submit for RatingSubmits the current draft, or opens the questionnaire first if enabled. Only the ticket owner can do this.
ScrapRemoves the whole unsubmitted draft and its stored local files. The ticket stays open for a fresh upload.
Close TicketStarts cancellation of the ticket while it is still unsubmitted. Confirm only if you want the channel deleted.

What happens with extra or unsupported files?

If a new batch contains more supported files than the remaining spaces, the bot rejects that incoming batch instead of partially filling the draft. For example, with three files already saved, send one more file, not two.

An entirely unsupported upload is rejected. In a mixed batch, supported files can be accepted while unsupported files are skipped. Warnings are temporary and the incoming upload message may be deleted, so the preview is the reliable way to check what was saved.

After you submit

Your selected media is placed in the Rater Voting Panel, with a separate Current Votes Breakdown below it. Raters can review the attachments and cast votes. Later uploads are not automatically added to the submitted set. If you need a correction, ask staff before they assign a result.

The draft preview is a confirmation step, not an extra privacy boundary: authorized raters can see the ticket while you prepare it. Normal ticket closure does not erase the host's stored media. Read the retention details.

Members

Complete the short form

Answer the server's questions before the voting panel appears.

When the form appears

If Ratee Questions are enabled, clicking Submit for Rating opens a form before voting begins. With the default questions, you will see:

QuestionRequired?
AgeYes
HeightNo
WeightNo

The server may replace these labels. There can be up to three questions: the first is required, and the second and third are optional. Each answer is a short text field with a 100-character limit. Empty optional answers are shown as Not provided.

Submit or return to the draft

  1. Read the question labels and enter your answers.
  2. Submit the form to finish submitting the media and open voting.
  3. If you cancel the form, return to the ticket's draft preview and click Submit for Rating again when ready.

Your answers are displayed to raters in the voting panel and included in assignment and closure logs. They are not a private note only to the bot owner.

If no form appears

That is normal when the feature is disabled. Fresh configuration defaults to questions being off; the setup wizard can enable them. An admin can change this under Thresholds → Ratee Questions. Administrator instructions.

Members

Your result and role

Understand assignment, the DM, and what happens when you decline.

When staff assign the result

Once staff click Assign, the bot applies the mapped rating role, records the result, and starts your cooldown. It removes other roles belonging to the configured male and female rating scales while keeping unrelated roles.

The ticket shows a confirmation. The bot also tries to DM you with Accept Role and Deny Role.

Choose in the DM

ChoiceWhat it does
Accept RoleRecords your acceptance and leaves the assigned role in place.
Deny RoleAttempts to remove the role assigned by this ticket, records the denial, and notifies Head staff. The rating cooldown stays active.
No responseLeaves the already-assigned role in place.

The bot accepts one recorded decision for a ticket. A denial is not an automatic appeal, rerating, or cooldown reset. Speak to Head staff if you want the result reviewed.

If something looks wrong

No DM: your DMs may be closed or delivery may have failed. The current build has no automatic replacement decision panel in the ticket. Ask staff for help.

Result announced but role missing: ask staff to check the tier mapping and the bot's role position. The build can record a result and cooldown even when Discord rejects the role change. Staff should check your actual role list.

Wrong role after a correction: tell Head staff which ticket and result you mean. Overrules and old DM decisions need staff attention; use the newest result and avoid acting on old messages during a correction.

Closing is separate

Assignment does not automatically close the channel. Senior Raters, Head Raters, or Administrators can choose Yes, close or Keep open. After submission, members cannot close their own channel through the close button, even after receiving a rating.

Closing deletes the Discord ticket channel after confirmation. It does not remove the assigned role, erase the rating cooldown, or delete all stored records.

Raters

Cast or change a vote

From the submitted media to the live vote breakdown.

Who can vote?

You need one of the server's mapped Verified, Trusted, Senior, or Head Rater roles. Having Administrator permission by itself does not grant a vote. You cannot vote on your own ticket.

If you hold several rater roles, the highest recognized rank is used: Head → Senior → Trusted → Verified. Rank names are configurable through role mappings; an unmapped role with a familiar name does not count.

Use the voting panel

  1. Open a submitted ticket and review all attached photos or videos plus any Ratee Details.
  2. Look at the panel's Male Scale or Female Scale label.
  3. Click the category containing your tier.
  4. Click the exact tier button revealed below it.
  5. Check the private confirmation and the updated vote breakdown.
Male categoryFemale categoryTier positions
Sub 3 / LTNSub 3 / LTB1–4
MTNMTB5–7
HTNHTB8–10
CL / ChadSL / Stacy11–14

Clicking a category only expands the available options; it does not cast a vote. Clicking an already-open category collapses it. Category expansion is shared, so another rater may change which options you see.

Changing your mind

Click a different tier to replace your previous vote. Each rater has one current vote per ticket. Changing a vote does not add another person or award the normal first-vote EXP again. Your rank weight is captured when you cast or update the vote; a later rank change does not automatically rewrite an existing vote's weight.

Voting stays open while the ticket is in the voting stage. After assignment it is locked unless Head staff reopen voting through an overrule.

Read the two messages

Rater Voting Panel: shows the media, scale, questionnaire answers, weighted progress, and current calculated result.

Current Votes Breakdown: groups votes by tier/category, shows weighted totals and distinct raters, and provides the voting controls plus staff buttons. A higher weighted count than headcount is expected.

The first time the vote target is reached, an assignment prompt appears. Later votes or changes can remove and refresh that prompt after about 10 seconds without another change. Allow the refreshed prompt to appear before staff assign a result.

You earn vote EXP for a new vote. Accuracy bonuses and completed-ticket statistics are processed when a result is assigned, not merely when you click a tier.

Raters

How the result is calculated

A weighted tier system, with a calculator you can try.

Vote weights and the target

Rater rankStandard vote weight
Verified1
Trusted2
Senior2
Head3

If both Trusted and Senior are unmapped, Head votes count as 2 instead. With at least one of those intermediate ranks configured, Head remains 3.

The setting labelled Minimum Raters is a weighted vote target. At the standard target of five, a Head vote worth three plus a Trusted vote worth two is enough to trigger review. This is two people, not five. Reaching the target asks staff to review; it does not assign a result automatically.

Three scoring modes

ModeCalculationTie or midpoint behavior
MeanAdd each tier position multiplied by its vote weight, then divide by total weight.Round to the nearest position; an exact .5 rounds upward.
MedianRepeat each selected position according to its weight, sort them, and take the middle. With an even total, average the two middle positions.Round an exact .5 upward.
ModeFind the tier or tiers with the largest total vote weight.If several tiers tie, average their positions equally, then round half upward.

Positions run from 1 to 14; they are not /10 scores. The two scales have different labels but use the same positions. See the complete tier ladder.

Mean example: Head selects position 8 and Trusted selects position 6. The result is (8 × 3 + 6 × 2) ÷ 5 = 7.2, which rounds to position 7: High MTN on the male scale or High MTB on the female scale.

Mode tie example: equally weighted leaders at positions 4 and 8 produce position 6, even if nobody voted for 6. This is the implemented tie rule.

Try an example

This calculator stays in your browser. It does not read or change Discord votes. Change ranks, tiers, or the scoring mode to see the result.

<p>Use the interactive calculator in the online handbook at <a href="index.html#scoring">the scoring article</a>.</p>

What staff should check

Wait for the newest assignment prompt and compare it with the current breakdown. All eligible votes can affect the result while voting remains open, including votes after the target is first reached. Avoid changing scoring settings, role mappings, or tier mappings during active tickets: this build reads live configuration rather than freezing a copy at ticket creation.

The displayed calculation may be rounded to two decimals, but the final mean/mode tier rounding uses the underlying fraction. A displayed value close to a midpoint should not be used to recompute the result by eye.

Raters

The two tier ladders

The exact built-in order used for voting and role assignment.

Positions and labels

PositionMale scaleFemale scale
1Sub 3Sub 3
2Low LTNLow LTB
3Mid LTNMid LTB
4High LTNHigh LTB
5Low MTNLow MTB
6Mid MTNMid MTB
7High MTNHigh MTB
8Low HTNLow HTB
9Mid HTNMid HTB
10High HTNHigh HTB
11Low CLLow SL
12Mid CLMid SL
13High CLHigh SL
14ChadStacy

Some stored labels and messages abbreviate Low/Mid/High CL as lcl / mcl / hcl, and the female equivalents as lsl / msl / hsl. The button labels may spell them out. These are the same positions.

How a tier becomes a Discord role

An administrator maps each position to a Discord role in Tiers & Roles. The selected tier's role is then applied when staff approve the result. The displayed role name may differ from the tier label.

The numeric order above controls calculations. Dragging roles up or down in Discord's role list does not change the scoring order. Discord's role order still matters for whether the bot has permission to add or remove them.

What can be customized here?

The dashboard can map existing roles, find matching roles by name, and create missing tier roles. It does not offer controls to add arbitrary tiers, rename the voting labels, or reorder the fourteen positions. Those changes would need a code/data change and a revised guide.

Use a distinct, appropriate role mapping for each result. An unmapped tier can be recorded as an assigned rating without applying a Discord role, so admins should verify every mapping before deploying the request panel.

Tier labels are the server's rating categories. The bot combines human votes; it does not analyze faces or generate an independent AI rating.

Raters

Who can do what?

The four rater ranks and the separate administrator and owner permissions.

Rater permissions

ActionVerifiedTrustedSeniorHeadAdministrator
View and chat in rating ticketsYesYesYesYesYes
Vote on another memberWeight 1Weight 2Weight 2Weight 3*Only with a mapped rater rank
Assign the normal calculated resultNoNoYesYesYes
Close another member's ticketNoNoYesYesYes
Close any submitted ticketNoNoYesYesYes
Reset votes or grant/change a result through OverruleNoNoNoYesYes
Approve or deny promotion applicationsNoNoNoYesYes
Configure the system or deploy panelsNoNoNoNoYes
Read the automatically locked log channelNoNoNoYesYes

*Head weight is 2 when both Trusted and Senior mappings are absent. The ticket owner may close their own ticket before submission, regardless of rater rank. Normal result assignment cannot be self-approved. Promotion approval cannot be self-approved either.

Owners are different from administrators

IdentityAdditional controls
Server Owner/give-rater-exp and /give-rater-levels for that server. An ordinary Administrator cannot use these.
Bot creator / configured bot ownerGlobal /bot announce broadcast. Verified through BOT_OWNER_ID, the Discord application owner, or the application team's owner.
Server Administrator or bot owner/bot name, /bot pfp, /bot banner. These alter the bot's global profile.

A Head Rater role does not automatically grant Discord's Administrator permission. It also does not automatically permit posting in an announcements channel; that channel's Discord permissions must be set by an admin.

Optional middle ranks

Verified and Head are the core ranks. Trusted and Senior can each be unset through Rater Ranks → Clear Optional. Clearing a mapping does not delete the Discord role or remove it from members; the bot simply stops recognizing it in that slot.

If Trusted is unset and Senior is configured, Verified raters may apply directly for Senior. If both middle ranks are unset, promotion applications are disabled. Head is appointed manually by server staff; there is no apply-for-Head command.

Permission changes and existing tickets

Opening a ticket creates channel permission entries using the rater roles configured at that moment. Replacing rank mappings later does not automatically repair all existing channel permissions. Check active tickets after changing roles, and finish ongoing sessions before major configuration changes where possible.

Raters

EXP, levels, and leaderboards

See what earns progress and what the statistics actually measure.

Earning EXP

EventStandard rewardWhen it happens
New vote on a ticketRandom 15–25 EXP, inclusiveOn the first recorded vote. The reward message is temporary.
Exact match with assigned tierRandom 5–10 EXP, inclusiveWhen the result is assigned. A one-tier near miss does not earn this bonus.
Server Owner grantThe amount or level count enteredWhen an owner uses the relevant grant command.

The configured preset can change these ranges. Updating your existing vote does not normally give another first-vote reward. Rater rank changes a vote's weight, not the configured base EXP range.

You start at Level 1. Completing a level needs current level × 100 EXP: 100 to reach Level 2, another 200 to reach Level 3, another 300 to reach Level 4, and so on. Extra EXP carries into the next level.

View a rank card

Use /rating level for yourself, or /rating level user:@Member for another person. The card is posted in the channel and includes rank, level, current and total EXP, progress, leaderboard position, completed ratings, distinct people, accuracy, average deviation, and promotion status.

A level-up announcement goes to the configured Rater Chat, falling back to Announcements. Crossing a configured promotion level can also send a DM explaining how to apply. Reaching a level does not automatically grant a rank role.

What accuracy means

Accuracy compares a rater's recorded tier position with the final assigned position on completed ratings. It measures agreement with the assigned result, not an objective assessment of a person's appearance or a staff-written quality review.

MetricMeaning
Completed ratingsCredited tickets whose results have been assigned. Clicking a vote alone does not complete a rating.
Distinct peopleDifferent members across those credited tickets. Rating the same person twice still counts as one distinct person.
Exact matchesYour recorded position equals the final position.
Close matchesDifference is zero or one tier position.
Average deviationAverage absolute difference between your position and the final position, rounded to two decimals.
Accuracy percentage100 − (average deviation × 12.5), bounded between 0% and 100% and displayed to one decimal.

With no completed ratings, the underlying default accuracy is 100%; this is not evidence of a rating history. Some displays may instead show an empty value. Look at the completed-rating count alongside accuracy.

Use the leaderboard

Run /leaderboard, then use its category dropdown. It shows up to ten members per category.

CategoryRanking basis
OverallLevel, then total EXP.
Weekly EXPEXP transactions in the last rolling seven days; this is not a fixed Monday-to-Sunday week.
Tickets RatedDistinct credited ticket count.
AccuracyAccuracy among members with at least one completed rating.

Leaderboards are scoped to the server. Owner-awarded EXP also contributes to the EXP records. Distinct people is a profile statistic, not a separate leaderboard category.

After corrections

A credited participation is stored once per rater and ticket. Reassigning or overruling a completed ticket does not reliably rewrite its original statistics, and repeated assignment paths can award accuracy EXP again. Staff should treat historical figures after corrections as approximate and avoid repeated assignment for routine testing. Build notes.

Raters

Apply for a promotion

Levels open an application; a staff decision grants the rank.

The normal path

Verified → Trusted → Senior → Head is the default rank order. Trusted and Senior have application commands. Head is appointed manually.

ApplicationDefault levelOther requirements
/rating apply-trustedLevel 5You are a Verified Rater, Trusted is configured, and you have no pending application.
/rating apply-seniorLevel 10You are Trusted if that rank is configured. If Trusted is unset, Verified can apply directly. Senior must be configured and you must have no pending application.

Admins can change the required levels. Already holding a higher rank does not let you apply for a lower rank through these commands. If both middle ranks are disabled, neither application path is available.

Submit and wait

  1. Check your current standing with /rating level.
  2. Run the application command for the next available rank.
  3. Read the private response. If eligible, the bot creates a review case for staff.
  4. Wait for an approval or denial. You may have only one pending case in that server.

The case goes to Head Raters Chat / Promotion Review, falling back to Rater Chat and then the log channel if the preferred destination is not configured. Admins should configure the intended private review channel before accepting applications.

How staff decide

The case displays your level, EXP, rating counts, distinct people, and accuracy statistics. Head Raters or Administrators can click Approve or Deny. They cannot approve their own application. Denial opens a required reason field, up to 500 characters, and the bot attempts to DM the applicant.

Approval adds the target role and attempts to remove the previous rank role. If Trusted is skipped, the original Verified role can remain; the bot still uses the highest recognized rank. Staff should verify the actual member roles because Discord permission errors can prevent a change.

There is no Defer control. A case remains pending until staff act. After denial, the current build does not impose a separate application cooldown; follow the server's staff instructions before applying again.

How this differs from a quality-gated system

The bot currently checks level, rank, configured roles, and pending-case status before an application. It displays experience and accuracy for human review, but it does not enforce a minimum number of people rated, a minimum accuracy percentage, or a separate quality-review score.

Admins and Head staff must make that judgment themselves. No automatic promotion happens when a threshold is crossed, and there is no active quality-review form or command in this build.

Senior staff

Review and assign a result

Approve the current calculation and verify the actual role change.

Open the current assignment prompt

Senior Raters, Head Raters, and Administrators can approve the normal result. You cannot approve your own ticket. Verified and Trusted raters cannot use Assign simply because they have voted.

The prompt appears after the weighted vote target is reached. If voting changes, wait for the refreshed prompt, which is normally posted after ten seconds without another vote change. Compare it with the current vote breakdown before acting.

Assign or skip

ButtonEffect
AssignAttempts the mapped Discord role change, records the assigned result, starts the cooldown, credits participating raters, awards exact-match EXP, sends the decision DM, writes a log, and offers to close.
SkipRemoves the current assignment prompt and leaves voting open. A later vote can produce another prompt. It does not choose a different tier.

To select a result other than the calculated tier, a Head Rater or Administrator must use Overrule.

Check the result, not just the success message

After assignment, confirm that the member has the intended role. This code can continue recording the result even if the mapped role is empty or Discord refuses the role change. Check for a Role Assignment Notice, missing mapping, or a bot hierarchy error.

The bot's highest role must be above the rating roles it manages, and it needs Manage Roles. Previous mapped rating roles from either gender's scale are removed when the new mapped role is applied. Unrelated roles are preserved.

What the member receives

The role is applied immediately. The later Accept Role / Deny Role DM confirms or declines that already-applied role. A denial keeps the cooldown and alerts Head staff. A failed DM does not undo the assignment or automatically post replacement controls.

Finish the session

Use Yes, close to close after discussion is complete, or Keep open to leave the channel available. The ticket does not auto-close. A standard closure logs the action and deletes the channel after a short delay. Closure details.

For sensitive staff corrections, coordinate in the Head Raters channel and use the latest ticket messages. Avoid repeatedly pressing old assignment controls; this build does not fully protect every stale-message or repeated-assignment path.

Senior staff

Close or cancel a ticket

Know what gets deleted and what stays recorded.

Who may close?

Ticket stageWho may close with the bot
Collecting media or draft previewTicket owner, Senior Rater, Head Rater, or Administrator.
Submitted and votingSenior Rater, Head Rater, or Administrator.
Result assignedSenior Rater, Head Rater, or Administrator.

A Verified or Trusted Rater can close their own unsubmitted draft as its owner, but cannot close other people's tickets or their own submitted ticket through these controls.

Use the close controls

  1. Click Close Ticket on a ticket message, or Yes, close after assignment.
  2. Where the bot shows a confirmation, choose Yes, Close Channel to proceed or Cancel to leave it open.
  3. The bot records the closure, sends the closure log, and attempts to delete the ticket channel after about three seconds.

Keep open dismisses the post-assignment choice for you and leaves the channel in place. It does not reopen voting or undo a rating.

What closure preserves

Closing does not remove a granted rating role, cancel a cooldown, reset rater EXP, erase rating history, or delete all locally stored media. The closure log can retain IDs, answers, and vote details. See logs and stored data.

Closing an unassigned draft does not itself start a rating cooldown. Assignment is what sets the cooldown.

If channel deletion fails

Ask an admin to check the bot's Manage Channels permission. The database can already mark the ticket closed even if deleting the Discord channel fails, so inspect both the channel and the bot's response before trying again.

Deleting a ticket channel manually in Discord is different from using the bot's normal closure flow. The channel-delete listener updates active ticket status, but does not perform the complete closure log and cleanup sequence.

For bulk removal, use Ticket Sweep only after reading its scope: it also deletes every channel inside the configured ticket category.

Senior staff

Head Rater overrules

Reset a vote set, grant a tier, or correct an assigned result.

Open the panel

A Head Rater or Administrator can run /rating overrule inside a rating ticket, or click Overrule below the vote breakdown. The private panel displays the ticket, current assigned result, and vote summary.

The actions are Reset Votes, Role Management, and Dismiss. Senior Rater alone does not grant access. These are exceptional staff controls; the normal self-approval protection is not consistently applied to direct overrules, so have another authorized staff member handle your own ticket.

Reset votes

ControlWhat is removed
Reset All Votes → Yes, Reset All VotesEvery current vote on that ticket.
Reset Selection → category → Confirm ClearAll votes for tiers in that category.
Reset Selection → exact tier dropdown → Confirm ClearAll votes for that tier.

A selection targets a tier or category, not one named rater. The bot updates the panel and posts an audit message in the ticket. Cancel leaves the votes unchanged; Back returns to the previous menu.

Resetting all votes on an assigned ticket moves it back to voting and clears the stored assigned label/role fields. It does not automatically remove the member's existing Discord role, undo their cooldown, reclaim EXP, or erase previously credited statistics. A partial reset does not automatically reopen an assigned ticket.

After a reset, wait for a fresh, consistent voting state. Do not use a pre-reset assignment prompt. New votes may earn EXP again after their previous vote records have been cleared.

Grant or change a role

  1. Open Role Management.
  2. Choose Role Grant for a result not yet assigned, or Role Change to correct one already assigned.
  3. Select the desired tier from that ticket's gender scale.
  4. Review the confirmation and click Yes, Grant Role or Yes, Change Role. Use Cancel to back out.

This deliberately bypasses the normal vote-target calculation. It attempts the role change, records the selected result and staff actor, sets a new cooldown from the time of the action, sends a decision DM, processes participation and exact-match EXP, writes an assignment log, and offers to close the ticket. Closed or cancelled tickets cannot receive a role change through this path.

Verify corrections

Check the member's role list and the latest ticket result. Historical participation rows are kept once per rater/ticket and do not necessarily change to reflect an overrule. A repeated assignment can also process accuracy EXP again. Do not rely on repeated overrules to recalculate a clean statistics history.

Old DM decisions may already be recorded. If the member's result changes after a prior Accept/Deny decision, handle any further role request with staff rather than promising a fresh decision cycle.

Administrators

Set up the server

A complete first-run walkthrough using the interactive wizard.

Before the wizard

You need Discord Administrator permission to configure the bot. The bot must be online, installed in the server, and able to use its commands. If it is not running yet, see hosting and maintenance.

Give the bot the permissions its work needs: View Channels, Send Messages, Read Message History, Embed Links, Attach Files, Manage Messages, Manage Channels, and Manage Roles in the relevant places. Manage Messages is needed for removing users' upload messages. Move the bot's highest role above rating and rater roles it must manage.

Use a dedicated category for temporary rating tickets. Keep permanent channels outside it, because Ticket Sweep deletes all category children. The auto-create helper initially places request, chat, review, logs, and announcements channels inside that category; move those permanent channels out after setup.

Run the six-step wizard

Type /quicksetup, or open /rating setup and choose Quick Setup Wizard. Some early screens still say “/5”; the implemented flow has six steps.

StepWhat to checkControls
1. ChannelsCategory, request panel channel, rater chat, Head review chat, logs, and announcements.Re-Detect, Auto-Create Missing, Confirm & Next.
2. Gender rolesOne Male routing role and one Female routing role.Re-Detect, Auto-Create Missing, Confirm & Next.
3. Rater ranksHead and Verified are required; Trusted and Senior are optional.Re-Detect, Auto-Create All 4, Confirm & Next.
4. Tier rolesFourteen mapped positions for each gender scale.Re-Detect, Auto-Create Missing Roles, Confirm & Next.
5. Ratee questionsWhether submitting a draft opens the form.Enable Questions (Defaults) or Skip / Disable Questions.
6. PresetVoting, cooldown, level requirements, and EXP ranges.Choose a preset, or Keep Current Settings & Exit.

Re-Detect searches existing names; auto-create adds missing items. Review the results instead of assuming similarly named roles or channels are correct. The wizard requires real Head and Verified roles before moving past step 3, but reaching the end does not prove every other mapping is valid.

Exit Wizard returns to the dashboard; changes already saved or items already created are not rolled back.

Finish the permissions

Open /rating setup and inspect Channels and roles. Explicitly set the private staff channels, announcement posting permissions, and all tier mappings. Auto-create does not fully lock every auxiliary channel for you.

Assign the appropriate gender roles to members and rank roles to raters yourself. Creating or mapping a role does not automatically give it to people. Configure the Head review channel after mapping Head Rater so the right role is allowed in.

Post the request panel

Click Deploy Rating Panel at the end of the wizard, or Deploy Panel on the dashboard. The bot posts in the saved request channel, falling back to the current channel if that mapping cannot be used.

Alternatively, run /rating panel in the channel where you want the panel. That command uses the current channel. Reposting creates another panel; it does not automatically replace or remove older panels.

Check one complete session

Use a consenting test member and a different authorized rater. Confirm ticket access, both gender scales, the media preview and Scrap action, submission, weighted voting, staff assignment, actual role change, DM decision, and closure logs. Check the view of a normal member as well as a staff member.

The guide is source-reviewed; this end-to-end check needs your real server. If you use the Fast preset for testing, restore your intended preset afterwards. Fast clears existing cooldowns, so avoid applying it casually on a live server.

Administrators

Map channels and roles

Connect each function to the correct Discord destination.

Channel mappings

Open /rating setup → Channels. Select a tab and choose the Discord channel or category in its selector. Changes save as you select them; there is no final global Save button.

TabPurposePermission guidance
CategoryWhere new rating tickets are created.Use a category dedicated to disposable ticket channels.
Request PanelWhere dashboard/wizard deployment posts the request button.Members need to see and use the panel.
Head Raters ChatPromotion review cases and role-denial alerts.Head Raters and admins only. Selecting this channel applies a private overwrite set.
Rater ChatRater discussion and the preferred destination for level-up announcements.Set access for the configured rater ranks manually.
Ticket LogsAssignment, closure, and denial records.Bot writes; Head Raters read; administrators retain access.
AnnouncementsOptional server announcement destination and level-up fallback.Manually allow Head Raters to send and the intended audience to read.

Auto-Map Channels finds likely existing channels. Auto-Create Missing creates missing defaults and saves their IDs. Check the resulting mappings, especially if your server has similarly named channels.

Permanent channels and Ticket Sweep

Auto-created permanent channels are initially placed under the rating category. Move request, staff chat, review, logs, and announcements elsewhere before ever using Sweep. Sweep deletes all children of the selected category, including non-ticket channels.

Automatic log permissions

The bot replaces the log channel's permission overwrites: everyone is hidden, the bot can read/write, Head can read but not send, and the other three rater roles are explicitly denied visibility. Administrators bypass channel restrictions. The lock is applied at startup and during relevant configuration changes, so extra custom log viewers may be overwritten.

Selecting Head Raters Chat also replaces that channel's overwrite list. Recheck permissions after changing the Head mapping. Auto-creation alone is not a guarantee that every staff channel is private.

Gender roles

Open Gender Roles, then select Male and Female roles. Auto-Map Roles looks for existing matches; Auto-Create Missing creates absent roles. The routing roles must be distinct. Members need exactly one to open a ticket.

These roles choose the rating scale. They do not grant rater permissions and do not represent a calculated rating.

Rater ranks

Open Rater Ranks and map Head, Senior, Trusted, and Verified to the appropriate Discord roles. Head and Verified are the core ranks. Use Auto-Map Ranks or Auto-Create All 4 if useful, then inspect the result.

Clear Optional lets you unset Trusted, Senior, or both. It does not delete the Discord roles. This changes promotion paths and can change Head vote weight. Rank behavior.

Tier role mappings

Open Tiers & Roles → Map Male or Map Female. Choose a tier from the first dropdown, then choose its Discord role. Repeat for each position. You can use Auto-Map All, the scale-specific auto-map button, or Create Missing Roles to speed this up.

Mappings use role IDs and save immediately. Keep the bot's highest role above the roles it manages. The tier order is fixed in this build; changing a role's position in Discord does not change voting math.

Administrators

Tune voting and progression

The settings behind the Thresholds menu.

Open the settings

Run /rating setup → Thresholds. Each control saves its change immediately. Back to Thresholds and Main Dashboard navigate without undoing edits; Refresh on the dashboard rereads the current saved configuration.

ControlChoices or limitsFresh default
Scoring ModeMean (Default), Median, Mode.Mean
Minimum RatersButtons for 3, 5, or 7; Custom accepts a whole number from 1 to 100.5 weighted votes
Rating Cooldown0, 1, 7, or 14 days; Custom accepts whole days from 0 to 365.7 days
Promotion & LevelsMinimum Trusted/Senior levels; configured ranks only. Each level must be at least 1, and Senior must exceed Trusted when both are set.Trusted 5, Senior 10
Vote EXPMinimum and maximum positive whole numbers; maximum must be at least minimum.15–25
Accuracy EXPSame range rules as Vote EXP.5–10
Ratee QuestionsToggle, customize up to three labels, or reset question defaults.Disabled
Ticket AccessOne whitelist role and one blacklist role, each optional.Neither configured
System PresetsApply a bundle of scoring, cooldown, progression, and EXP settings.See presets.

Minimum Raters is weighted

Despite its label, the requirement compares the sum of vote weights, not the number of different raters. There is no separate distinct-person quorum setting. Use the calculator to choose a target that fits your rank layout.

Cooldown changes

Cooldown is set when a result is assigned, including a direct overrule. Setting it to 0 clears existing cooldowns for the entire server. The Fast preset does this too.

Changing a nonzero duration does not simply recalculate every person's expiry from their last rating. On a later request, the code may cap an existing expiry relative to the current time and new duration. Treat old cooldowns as existing records, and check the time shown to the member.

Administrators bypass the cooldown check, but still need valid routing and access roles. There is no registered command for clearing one member's cooldown.

Promotion and EXP settings

Use Promotion & Levels to edit the relevant rank-level requirements and the two EXP ranges. At least one optional promotion rank must be configured to edit promotion thresholds. These settings do not enforce a distinct-people count or an accuracy threshold.

A preset overwrites these numeric values. A settings reset does not reset all of the newer EXP and level fields; read the reset table before relying on it.

Avoid changing an active session's rules

This build reads current settings and tier mappings during interactions. It does not keep a frozen rules snapshot for each ticket. Finish active voting sessions before major scoring, rank, or mapping changes when possible.

Administrators

Choose a system preset

All four bundles, with their exact saved values.

Compare the presets

Open Thresholds → System Presets, or choose one at the end of Quick Setup.

SettingStandard / BalancedCompetitive StrictCasual ConsensusFast-Paced (Instant)
Scoring modeMeanMedianModeMean
Weighted vote target5753
Cooldown7 days7 days14 days0 days
Trusted minimum level51043
Senior minimum level102086
First-vote EXP15–2510–2020–3025–40
Exact-match EXP5–1015–255–1010–15

All EXP ranges include both endpoints. Rater weights remain determined by the configured ranks.

What applying a preset changes

Choosing a preset saves every numeric/mode field in the table immediately. It replaces custom values for those fields. It does not configure channels, assign member roles, map tiers, turn questions on, or set whitelist/blacklist roles.

Fast-Paced sets cooldown to zero and clears existing server cooldowns. In a four-rank setup, a single Head vote has weight three and can meet its target alone. Fast is useful for an intentional test, but check its consequences before applying it to a live server.

Which result should you expect?

Standard calculates a weighted arithmetic average. Competitive uses a weighted median. Casual uses the most heavily supported tier with the implemented tie-average rule. Their names are preset labels, not a guarantee that one method is fairer or more accurate.

Try the same sample votes in the scoring calculator before choosing a mode. Staff approval is still required for the normal assignment path in every preset.

After editing individual fields, the dashboard or logs may describe the configuration as Custom if it no longer matches a recognized bundle.

Administrators

Access rules and questions

Control who can open tickets and what they answer before submission.

Whitelist and blacklist

Open Thresholds → Ticket Access.

SettingResult
Select a whitelist roleMembers must hold that role to open a ticket. Only one whitelist role is stored.
Clear WhitelistRemoves that requirement. Other restrictions still apply.
Select a blacklist roleMembers with that role cannot open tickets. Only one blacklist role is stored.
Clear BlacklistRemoves this role-based block.
Member has both mapped rolesThe blacklist wins.

These checks happen when opening a ticket; they do not automatically evict someone from an already-open ticket. Administrator status does not bypass them. If a configured access role has been deleted from Discord, the open-ticket code clears that stale mapping, so a deleted whitelist will no longer restrict entry.

Enable or disable questions

Open Thresholds → Ratee Questions. Use Enable Questions or Disable Questions. Enabled questions appear when the member clicks Submit for Rating, before the voting panel is posted.

Reset Defaults restores Age (required), Height (optional), and Weight (optional). Check the enabled status separately. The wizard's Enable Questions (Defaults) both restores those questions and enables them.

Customize the form

Click Customize Questions and edit the labels:

FieldBehavior
Question 1Required label; the member's response is required.
Question 2Optional label; leave it blank to omit this question. Its response is optional.
Question 3Optional label; leave it blank to omit this question. Its response is optional.

Labels have a 45-character limit. Saving custom labels automatically enables questions. Member answers are limited to 100 characters each, and blank optional answers become Not provided.

The dashboard does not expose additional field types, more than three questions, configurable age validation, or a required/optional toggle for each individual question. The first is always required and the remaining two are optional.

Where answers are shown

Answers appear in the voting panel and in ticket logs, including role-denial logs. Ask only for information the staff handling the ticket should see. An age label is only a text prompt; this code does not check age or enforce a minimum-age rule.

Administrators

Logs and stored data

Understand the audit trail and the limits of deletion.

Automatic log events

Set Channels → Ticket Logs to receive the bot's structured event messages.

EventIncluded information
Rating AssignedMember and ticket IDs, opened/assigned times, detected preset, gender scale, assigned role, assigning actor, answers, and individual votes with weights.
Rating Ticket ClosedMember and ticket IDs, opened/closed times, preset, scale, rating role if any, assigning/closing actors, answers, and votes.
Rating Role DeniedMember, denied result and role, ticket and timing, assigning actor, cooldown status, answers, and original votes.

Overrules also post action messages inside the ticket; direct grants/changes use the assignment logger. Promotion reviews are posted to their configured review destination. The bot does not provide a full HTML transcript export of every chat message or a public results gallery.

If a log is absent, check the mapping and bot permissions. Logging errors do not necessarily undo the action that was being logged. A deleted ticket may appear as an unknown channel in an old log, while its ID remains present.

Who can read logs?

The automated log permission set allows Head Raters to read, the bot to write, and administrators to access the channel. Other rater ranks and ordinary members are hidden. The bot reapplies this policy at startup and during relevant setup actions, replacing custom overwrite entries.

What the host stores

The bot uses a local SQLite database, normally data/bot.db, plus downloaded attachments under data/media/. Records include configuration, roles and tier mappings, tickets, media metadata, questionnaire answers, votes, cooldowns, rater EXP and transactions, participation history, promotion cases, and role decisions.

Changing DATABASE_PATH moves the database location, not the separate media folder. The host needs persistent storage for both. The public guide itself does not connect to your Discord server or expose those records.

What each deletion does

ActionScope
ScrapRemoves the current unsubmitted draft records, stored draft files, and draft preview. It does not erase messages someone else has already seen or copied.
Normal Close TicketDeletes the ticket channel after logging. Local media and database history remain.
Manual Discord channel deletionMarks an active ticket closed through the listener; not a complete normal-close workflow.
Ticket SweepAttempts to delete ticket media and ticket channels, deletes all children of the configured category, and clears ticket/media/vote records.
Configuration resetChanges settings/mappings. It is not a complete personal-data deletion or rater-stat reset.

Sweep leaves separate participation/EXP records, promotion cases, cooldowns, and existing Discord log messages. File or channel deletion failures may occur. There is no automatic retention schedule or complete user-data deletion command in the uploaded build. Contact the bot operator for a specific data-removal request.

Administrators

Resets and Ticket Sweep

Read the scope before confirming a destructive action.

Find the controls

Open /rating setup → Resets. Choose an action, read the confirmation, and use Yes, Confirm Reset to apply it or Cancel to return. These actions do not have an undo button. Back up important configuration and records first.

Configuration reset scopes

ActionActually changesDoes not do
Reset Roles OnlyClears the two gender role mappings and four rater rank mappings.Does not delete Discord roles, remove roles from members, or clear tier/access-role mappings.
Reset Tiers OnlyClears the role ID for every tier position.Does not delete roles, rename tiers, or remove the fourteen-position ladders.
Reset Channels OnlyClears the category and five channel mappings.Does not delete Discord channels or reverse their permission overwrites.
Reset Settings OnlyRestores mean, target 5, cooldown 7 days; clears access roles; disables and resets questions; resets legacy rating-count fields.Does not reset the newer EXP ranges or promotion-level values, clear existing cooldown records, or change role/channel mappings.
Reset ALL Rating ConfigCombines the mapping/settings effects above, including cleared tier role mappings.Still does not reset newer EXP/promotion-level values or erase tickets, statistics, existing roles, channels, or logs.

The “factory defaults” wording in the bot is broader than this implementation. If you need all progression values restored, apply the Standard / Balanced preset after reconfiguring mappings, then verify each setting.

Ticket Sweep is broader than its name

When confirmed, Sweep:

  1. Attempts to delete stored media files associated with every recorded ticket in the server.
  2. Attempts to delete those tickets' Discord channels, including channels outside the current category.
  3. Deletes every remaining child channel inside the configured category.
  4. Clears the server's ticket, draft-media, and vote records from the database.

This covers closed records as well as active ones. It does not individually run the normal closure log for every ticket, and it does not remove the category itself.

What Sweep leaves behind

Separate rater EXP, EXP transactions, credited participation, promotion cases, and cooldown records are not cleared. Rating roles already assigned to members are not removed. Existing log messages remain unless their channels were themselves deleted.

After a sweep, inspect the reported channel count, your Discord channel list, and the saved channel mappings. A successful response does not guarantee every attempted deletion succeeded. Recreate or remap deleted permanent destinations before reopening requests.

Reference & owner tools

Every available command

The registered commands in the uploaded build, with examples and permissions.

How to read the examples

Type / and choose this bot's command from Discord's menu. Select users and attachments using the fields Discord opens. Text in [square brackets] below is optional; do not type the brackets. @Member and image URLs are examples to replace with your own selection.

Rating commands

CommandWho can use it?Purpose
/rating panelAdministratorPosts a Request Rating panel in the current channel.
/rating setupAdministratorOpens the interactive configuration dashboard.
/rating level [user]Members with command accessPosts your rank card, or the selected member's card.
/rating apply-trustedEligible Verified RaterCreates a Trusted promotion application.
/rating apply-seniorEligible Trusted, or Verified if Trusted is unsetCreates a Senior promotion application.
/rating overruleHead Rater or AdministratorOpens ticket overrule controls; run inside a rating ticket.
/quicksetupAdministratorOpens the six-step configuration wizard.
/leaderboardMembers with command accessPosts a leaderboard with Overall, Weekly EXP, Tickets Rated, and Accuracy choices.
/rating level
/rating level user:@Member
/rating apply-trusted
/rating overrule

Owner grants

CommandRequired fieldsAccess and result
/give-rater-expuser, amountServer Owner only. Adds a positive whole number of EXP.
/give-rater-levelsuser, levelsServer Owner only. Adds a positive whole number of levels by awarding the corresponding EXP.
/give-rater-exp user:@Member amount:100
/give-rater-levels user:@Member levels:2

These reject bot accounts and do not accept negative amounts. They can trigger level-up announcements and promotion notifications, but do not automatically promote someone. There is no matching deduct-EXP or remove-levels command.

Bot profile and global broadcast

CommandInputsWho can use it?
/bot nameRequired username (up to 32 characters).Administrator or bot owner.
/bot pfpimage attachment or url; provide at least one.Administrator or bot owner.
/bot bannerimage attachment or url; provide at least one.Administrator or bot owner.
/bot announceOptional title, message, ping, image_url; missing title/message opens a form.Bot creator/owner only.
/bot name username:CA Rating Bot
/bot pfp image:[select an uploaded image]
/bot banner url:https://example.com/banner.png
/bot announce

Profile changes affect the bot across servers. Announce is a confirmed all-server broadcast, not a Head Rater's local announcement command. Read the owner tools.

Commands that are not registered

The supplied older documentation mentions commands that this startup does not register, including /rating stats, /rating view-config, /rating upload, /rating setup-channels, /rating setup-roles, /rating setup-settings, /rating map-tier, and standalone /overrule or /rater level.

Use /rating level, /rating setup, ordinary ticket attachments, and /rating overrule instead. There is also no /help, /bot bio, individual cooldown-reset, automatic quality-review, or user-data export command in the current command set.

Discord command visibility can also be restricted by server integration settings and channel permissions. A visible button or command does not bypass the bot's own rank checks.

Reference & owner tools

Profile and announcements

Separate local Head Rater posts from global bot-owner broadcasts.

Local Head Rater announcements

Map Channels → Announcements to the desired server channel. In that channel's Discord permissions, allow Head Raters to View Channel and Send Messages, allow the intended audience to read, and prevent other roles from posting if you want a read-only announcement feed.

Head Raters then post ordinary Discord messages there. The bot does not provide a dedicated local Head Rater broadcast command or automatically finish this permission setup. This channel is also a fallback destination for level-up notices and the first choice for global owner broadcasts.

Change the bot profile

Administrators or the bot owner can use /bot name, /bot pfp, and /bot banner. These change the bot's account profile globally, including in other servers where it is installed. They do not change the guide's branding or automatically update its bio link.

For PFP and banner, provide an attachment through image or a direct image URL through url. If both are supplied, the attachment wins. The bot downloads the image and asks Discord to apply it. If the URL cannot be downloaded or Discord rejects the image, the command reports an error.

Discord may rate-limit profile changes. Follow the returned error and try later rather than repeatedly sending the command. The code's error messages include simplified rate-limit wording; they are not a reliable promise of a universal numeric limit.

Send a global announcement

Only the bot creator/owner may use /bot announce. Ownership comes from BOT_OWNER_ID or the Discord application's owner; for team-owned applications the code restricts this to the team owner, not every team member. A server's Head Rater or Administrator role alone is not enough.

  1. Run /bot announce to open the form, or supply title and message directly.
  2. Enter a title (up to 100 characters) and announcement details (form limit 4,000 characters).
  3. Choose none, everyone, or here for the ping, and optionally include a direct image/GIF URL.
  4. Review the private preview and server count.
  5. Click Send to All Servers (n) to broadcast, or Cancel to discard it.

The draft is kept only in memory and is cleaned up after roughly 30 minutes. A restart loses pending drafts. If it has expired or was already sent, create a new draft. A broadcast sends real messages and can notify large audiences, so check the preview and ping choice carefully.

Where broadcasts go

For each connected server, the bot looks for the first usable destination in this order:

  1. Configured Announcements channel.
  2. Configured Ticket Logs channel.
  3. Configured Request Panel channel.
  4. Server system channel.
  5. The first available non-thread text-based channel where it can view, send, and embed.

The final response reports successes, skips, and failures. The fallback can place a broadcast in a public or operational channel, so configure Announcements deliberately in every server. Choosing Cancel does not send the announcement.

Reference & owner tools

Hosting and maintenance

For the person who runs the bot process—not required for everyday raters.

What this project runs

The upload is a TypeScript/Node.js bot using discord.js, better-sqlite3, @napi-rs/canvas, and dotenv. The supplied package scripts are:

ScriptUse
npm run devRuns the TypeScript entry point with tsx for development.
npm run buildCompiles the TypeScript project with tsc.
npm startRuns the compiled dist/index.js bot. Build first.

Use a Node.js environment compatible with the locked dependencies, including their native modules. This guide documents the scripts; it does not certify a particular host or runtime version. The guide website is a separate static site and does not host the Discord bot process.

Configure the environment

Create a private .env file based on .env.example in the bot project. Keep real credentials out of public guides, repositories, and screenshots.

VariablePurpose
DISCORD_TOKENThe bot token used to connect to Discord.
CLIENT_IDThe Discord application ID used to register commands.
GUILD_IDOptional server ID used for initial default-tier setup; it does not restrict the bot to just that server.
BOT_OWNER_IDExplicit Discord user ID allowed as the bot owner, including global broadcasts.
DATABASE_PATHSQLite location; default ./data/bot.db.

Install the supplied locked dependencies with npm ci, build with npm run build, then start with npm start. Run these from the bot project directory and keep its storage persistent. Native dependency installation may require host support; inspect installation errors instead of assuming the bot is online.

Discord intents and permissions

The code requests Server Members and Message Content privileged intents, as well as standard guild/message/DM events. Enable the required privileged intents under your application's Bot → Privileged Gateway Intents settings and complete any access review required by Discord. Missing access can prevent startup or attachment handling. Source: Discord Gateway documentation.

Check the bot's server/channel permissions and role hierarchy using the setup checklist. Intents, channel permissions, and role order are separate requirements.

Startup and restarts

At startup, the bot initializes SQLite, ensures the default tier ladders, reapplies log-channel permissions, clears its application's global command registration, and registers this command set in connected servers. The application should be dedicated to this bot; do not expect unrelated global commands on the same application to survive.

There is no guild-join registration handler in this build. If you add it to another server while it is already running, restart it to synchronize commands there.

Core ticket and vote state lives in SQLite, but delayed assignment-prompt timers and announcement drafts are in memory. Restarting does not guarantee every pending prompt resumes automatically. Inspect active tickets after a restart; a fresh valid vote change may recreate a missing assignment prompt.

Back up and update

Keep a consistent backup of the database and data/media/. Stopping the bot cleanly before copying its data is a straightforward way to avoid copying a database mid-write. SQLite may have associated journal/WAL files depending on its state; use a database-aware backup or preserve the complete consistent storage set.

When updating code, preserve persistent data and environment settings, install the matching lockfile dependencies, build, and restart. Verify a small test session and update this guide when commands, permissions, or workflow change. The uploaded bot has no automated backup, media-retention schedule, or guide synchronization feature.

Reference & owner tools

Put the guide in your bot bio

One public link for members and staff, plus direct links to individual articles.

Use the main guide URL

https://cayzratingbot-guide.pages.dev

The handbook is designed to be readable on desktop and mobile. It does not ask readers to connect their Discord account. Search, the example calculator, and navigation run in the browser.

Add it to the bot profile

  1. Sign in to the Discord Developer Portal with access to the bot's application.
  2. Select the application and open General Information.
  3. Add the guide URL to its Description field and save.
  4. Open the bot's profile in Discord and check that readers can see the link.

Discord documents this Description field as the text shown on the bot user's profile, with a 400-character limit. Source: Discord's application description guidance.

Suggested short description:

Private rating tickets, weighted voting, and rater progression.
Guide: https://cayzratingbot-guide.pages.dev

The bot has no /bot bio command. Its name, avatar, and banner commands do not update this description. You must make the profile change in the portal; publishing this guide alone does not edit the bot's profile.

Send someone to the right instructions

Use Copy article link at the top of any article. Useful destinations include:

AudienceArticle
New memberRequest a rating
New raterCast or change a vote
Someone asking about averagesHow the result is calculated
Staff onboardingWho can do what?
Server adminSet up the server
Someone with an errorTroubleshooting

You can also pin the main URL in the request channel, use the printable guide, or download guide.md. The site does not automatically post to Discord or add a Help command to the bot.

Reference & owner tools

Troubleshooting

Start with the symptom, then check the smallest likely cause.

Members and uploads

SymptomCheck or next step
“You need a Male or Female role”You need exactly one role mapped to those slots, not merely a role with a matching name. Ask an admin.
Request blocked despite being an adminAccess roles and gender routing still apply; only cooldown is bypassed.
Active ticket message points to an old channelUse the existing channel if present. If it was deleted, try requesting again; the bot checks for missing channels.
Cooldown after denying a roleExpected. Denial and closure do not clear the rating cooldown.
Upload disappearsThe bot normally deletes the original and reattaches accepted files to the confirmation. Check the preview.
No confirmation previewAttach a supported file in your own unsubmitted ticket. Check the bot is online and has Message Content access, attachment/message permissions, writable media storage, and network access to the attachment.
Four files, but voting has not startedClick Submit for Rating. Reaching four does not auto-submit.
One file missing from a mixed uploadUnsupported files can be skipped or a download may fail. Check the preview; Scrap and resend the intended draft if necessary.
Submit opens a formComplete the server's enabled questionnaire. Cancelling the form leaves you at the draft stage.
Uploaded more files after voting beganThey are not automatically added to the submitted set. Ask staff to handle the correction.
Photo link stopped workingTry the actual attachment on the bot's message. Original attachment links can become invalid after the source message is removed.
No Accept/Deny DMDM delivery can fail. Ask staff; the role may already be assigned.

Voting and results

SymptomCheck or next step
Administrator cannot voteAdmin alone is insufficient. Assign a mapped rater role; do not self-vote.
Category button does not record a voteChoose the exact tier after expanding the category.
Vote total exceeds the number of peopleExpected weighted behavior. Check the separate rater count.
Result is a tier nobody selectedPossible under mean, median midpoints, or mode ties. See the scoring rules.
Assignment prompt disappears brieflyA later vote can replace it after about ten seconds without another change. Wait for the latest prompt.
Enough votes, but no roleStaff must still click Assign. Then check the actual role mapping and hierarchy.
Success message, but no role on the memberThe current code can record assignment despite a Discord role error. Check Manage Roles, bot role position, and the mapped role ID.
Member cannot close the ticketOwners can close only before submission. Ask Senior/Head staff or an admin afterwards.
Overrule button refuses accessIt requires Head Rater or Administrator; Senior alone is insufficient.
Statistics look stale after an overruleExisting credited rows are not reliably rewritten by corrections. See build notes.

Progression and setup

SymptomCheck or next step
Promotion application rejectedCheck configured target rank, current rank, minimum level, and existing pending case.
Level reached but no promotionApply with the correct slash command; staff approval is required.
Approval message but rank missingCheck actual Discord roles and the bot's Manage Roles permission/hierarchy.
Leaderboard blankEXP and completed-ticket categories need corresponding stored activity. Accuracy requires a completed rating.
Command from an older guide does not appearUse this guide's registered command reference. Some old names are not active.
Commands missing in a newly joined serverRestart the bot to register the server commands, then check application command access.
Missing staff logsCheck the saved log channel and bot permissions. Startup reapplies the log visibility policy.
Permanent channels vanished after SweepSweep deletes every channel in the configured category. Restore/recreate the needed channels and remap them; the bot has no undo.
Settings reset left custom EXP valuesExpected limitation: newer EXP and promotion-level fields are not reset. Apply a preset or edit them explicitly.
Broadcast says draft expiredRecreate it with /bot announce; drafts are in memory and are cleaned up after about 30 minutes.
“Interaction failed” or unexpected errorConfirm the bot is online. Reopen the relevant menu, check host logs and permissions, and verify the action's actual result before retrying a destructive operation.

What to tell your administrator

Include the command or button you used, the ticket/channel, approximate time, visible error, and what you expected. For a missing role, include the intended tier. Never include a bot token or private environment file. Administrators can then compare the saved configuration, Discord permissions, and host error logs.

Reference & owner tools

Coverage and build notes

What was verified, what differs from the plan, and what this build does not do.

Basis of this guide

Reviewed source: rating-ticket-bot.zip, package 1.0.0, dated 16 November 2026. The command builders, startup registration, interaction handlers, configuration, database queries, and services were inspected. The bundled older guide was cross-checked against those active paths.

This is a source-based operating guide. It is not a live Discord server test or a guarantee that the deployed bot runs the same upload. Server-specific values are not known; defaults are labelled and configurable values are explained. No bot credentials, member photos, server IDs, or private database records are published here.

Earlier plan versus uploaded behavior

Earlier idea or wordingUploaded implementation
Up to three photos/mediaUp to four total photos/videos.
Automatically submit when maximum reachedExplicit Submit for Rating confirmation remains required.
Average all equal votesRank-weighted votes; mean, median, or mode selectable.
Minimum number of peopleWeighted vote threshold, with distinct people shown separately.
Role only assigned after acceptanceRole applied first; DM accepts keeping it or declines it.
Promotions based on quantity, quality, and approvalLevel/rank checks and human approval; counts/accuracy are shown but not enforced as separate gates.
Five-step wizardSix implemented steps, with some outdated step labels.
Completely customizable tier structureFixed fourteen-position scales with configurable Discord role mappings.

Features covered

AreaIncluded controls and behavior
Member workflowPanel, role-based access/routing, cooldowns, one active unassigned ticket, 1–4 media drafts, submit/scrap, questions, results, DM decisions, closure.
RatingFour ranks, dynamic weights, category/tier buttons, changeable votes, live breakdown, three scoring modes, assignment prompts, staff approval, role replacement.
ProgressionVote and exact-match EXP, levels, graphical cards, four leaderboards, application eligibility, approve/deny review, owner grants.
Staff operationsClose/keep-open, full/category/tier vote resets, direct role grant/change, assignment/closure/denial logs.
AdministrationSix-step wizard, channel and role selectors, auto-map/create, tier mapping, optional ranks, thresholds, presets, question customization, access lists, panel deployment, refresh, all resets and Sweep.
Owner toolsGlobal name/avatar/banner updates, confirmed cross-server announcements, bot-bio instructions, host configuration and backups.

Operating limits to remember

Assignment is not fully transactional. Discord role failures can still leave a recorded result and cooldown. Repeated or stale staff actions are not guarded consistently. Check actual member roles and use the latest prompt.

Overrules do not cleanly rewind history. Vote resets and reassignment do not reliably undo prior roles, EXP, cooldowns, or credited statistics. Correct live roles deliberately and treat affected statistics with care.

Privacy setup needs a manual check. New tickets have explicit access controls, but auto-created auxiliary staff channels do not all receive a complete private policy. Sweep can delete permanent channels if left under the ticket category.

Retention is not automatic. Normal closure keeps local media; there is no scheduled purge, complete data-export command, or complete per-user deletion command. Logs and statistics can outlive ticket records.

Some state is temporary. Assignment refresh timers and announcement drafts are in memory. Database persistence does not mean every delayed action survives a restart.

Settings are live. Tickets do not preserve a frozen copy of rank weights, scoring mode, or tier mappings. Avoid changing these in the middle of active sessions.

Not implemented as user-facing features

There is no active rubric-based quality-review form, quantity/quality promotion gate, automatic Head promotion, arbitrary tier editor, per-photo draft remove button, built-in transcript export, reminder system, automatic idle-ticket closure, dedicated local Head announcement command, /help, or /bot bio command.

These are coverage notes, not changes to your bot. The original code was not modified to create this handbook. A future bot update should be audited and the guide refreshed before it is treated as current.