Start here / 2 MIN READ
Your rating bot, explained.
A practical handbook for members, raters, and the people running the server.
Find your starting point
Open a ticket, check your uploads, and receive your result.
02 / RATERSCast your voteChoose a tier, understand your vote weight, and track progress.
03 / SENIOR STAFFReview a resultApprove ratings, close tickets, and handle corrections.
04 / ADMINSSet up the serverConnect channels and roles, choose settings, and post the panel.
The usual ticket journey
- A member clicks Request Rating in the server's request channel.
- The bot opens a private ticket using the member's configured Male or Female role.
- 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.
- Authorized raters choose tiers. The bot combines their weighted votes using the server's scoring mode.
- Once the weighted vote target is reached, a Senior Rater, Head Rater, or Administrator can assign the result.
- The role is applied and the member receives an Accept Role / Deny Role DM. Staff can then close the ticket.
A few Discord basics
| Term | What it means here |
|---|---|
| Slash command | Type / 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. |
| Role | A server badge that can give permissions. This bot uses role IDs, so a similar role name alone does not grant access. |
| Ticket | A channel for one member's rating session. It is visible to that member, mapped raters, the bot, and administrators. |
| Embed | A formatted bot message. Buttons below it perform actions; opening a menu is not the same as submitting it. |
| Private response | A response Discord marks as visible only to you. This is different from a private ticket, which raters can also read. |
| Ratee | The person being rated. |
| Mapping | Connecting 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 / 2 MIN READ
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
- Find the server's rating request channel.
- Click Request Rating under the bot's panel.
- Follow the private response's channel link to your new ticket.
- 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 situation | What to do |
|---|---|
| Missing or conflicting gender roles | Ask an admin to give you exactly one configured routing role. |
| Whitelist required or blacklist restriction | Ask server staff about access. Removing a cooldown does not remove a role restriction. |
| You already have an active ticket | Use the channel link in the response. Complete or close that ticket first. |
| Cooldown active | Wait for the time shown. The standard setting is seven days after assignment. |
| Channel creation fails | Ask an admin to check the category, bot permissions, and server channel capacity. |
| No panel is visible | Ask 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 / 2 MIN READ
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 action | Result |
|---|---|
| Upload another supported attachment | Adds it to your current draft if there is room. The confirmation is replaced with an updated preview. |
| Submit for Rating | Submits the current draft, or opens the questionnaire first if enabled. Only the ticket owner can do this. |
| Scrap | Removes the whole unsubmitted draft and its stored local files. The ticket stays open for a fresh upload. |
| Close Ticket | Starts 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 / 1 MIN READ
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:
| Question | Required? |
|---|---|
| Age | Yes |
| Height | No |
| Weight | No |
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
- Read the question labels and enter your answers.
- Submit the form to finish submitting the media and open voting.
- 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 / 2 MIN READ
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
| Choice | What it does |
|---|---|
| Accept Role | Records your acceptance and leaves the assigned role in place. |
| Deny Role | Attempts to remove the role assigned by this ticket, records the denial, and notifies Head staff. The rating cooldown stays active. |
| No response | Leaves 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 / 2 MIN READ
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
- Open a submitted ticket and review all attached photos or videos plus any Ratee Details.
- Look at the panel's Male Scale or Female Scale label.
- Click the category containing your tier.
- Click the exact tier button revealed below it.
- Check the private confirmation and the updated vote breakdown.
| Male category | Female category | Tier positions |
|---|---|---|
| Sub 3 / LTN | Sub 3 / LTB | 1–4 |
| MTN | MTB | 5–7 |
| HTN | HTB | 8–10 |
| CL / Chad | SL / Stacy | 11–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 / 2 MIN READ
How the result is calculated
A weighted tier system, with a calculator you can try.
Vote weights and the target
| Rater rank | Standard vote weight |
|---|---|
| Verified | 1 |
| Trusted | 2 |
| Senior | 2 |
| Head | 3 |
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
| Mode | Calculation | Tie or midpoint behavior |
|---|---|---|
| Mean | Add each tier position multiplied by its vote weight, then divide by total weight. | Round to the nearest position; an exact .5 rounds upward. |
| Median | Repeat 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. |
| Mode | Find 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.
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 / 2 MIN READ
The two tier ladders
The exact built-in order used for voting and role assignment.
Positions and labels
| Position | Male scale | Female scale |
|---|---|---|
| 1 | Sub 3 | Sub 3 |
| 2 | Low LTN | Low LTB |
| 3 | Mid LTN | Mid LTB |
| 4 | High LTN | High LTB |
| 5 | Low MTN | Low MTB |
| 6 | Mid MTN | Mid MTB |
| 7 | High MTN | High MTB |
| 8 | Low HTN | Low HTB |
| 9 | Mid HTN | Mid HTB |
| 10 | High HTN | High HTB |
| 11 | Low CL | Low SL |
| 12 | Mid CL | Mid SL |
| 13 | High CL | High SL |
| 14 | Chad | Stacy |
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 / 2 MIN READ
Who can do what?
The four rater ranks and the separate administrator and owner permissions.
Rater permissions
| Action | Verified | Trusted | Senior | Head | Administrator |
|---|---|---|---|---|---|
| View and chat in rating tickets | Yes | Yes | Yes | Yes | Yes |
| Vote on another member | Weight 1 | Weight 2 | Weight 2 | Weight 3* | Only with a mapped rater rank |
| Assign the normal calculated result | No | No | Yes | Yes | Yes |
| Close another member's ticket | No | No | Yes | Yes | Yes |
| Close any submitted ticket | No | No | Yes | Yes | Yes |
| Reset votes or grant/change a result through Overrule | No | No | No | Yes | Yes |
| Approve or deny promotion applications | No | No | No | Yes | Yes |
| Configure the system or deploy panels | No | No | No | No | Yes |
| Read the automatically locked log channel | No | No | No | Yes | Yes |
*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
| Identity | Additional controls |
|---|---|
| Server Owner | /give-rater-exp and /give-rater-levels for that server. An ordinary Administrator cannot use these. |
| Bot creator / configured bot owner | Global /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 / 3 MIN READ
EXP, levels, and leaderboards
See what earns progress and what the statistics actually measure.
Earning EXP
| Event | Standard reward | When it happens |
|---|---|---|
| New vote on a ticket | Random 15–25 EXP, inclusive | On the first recorded vote. The reward message is temporary. |
| Exact match with assigned tier | Random 5–10 EXP, inclusive | When the result is assigned. A one-tier near miss does not earn this bonus. |
| Server Owner grant | The amount or level count entered | When 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.
| Metric | Meaning |
|---|---|
| Completed ratings | Credited tickets whose results have been assigned. Clicking a vote alone does not complete a rating. |
| Distinct people | Different members across those credited tickets. Rating the same person twice still counts as one distinct person. |
| Exact matches | Your recorded position equals the final position. |
| Close matches | Difference is zero or one tier position. |
| Average deviation | Average absolute difference between your position and the final position, rounded to two decimals. |
| Accuracy percentage | 100 − (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.
| Category | Ranking basis |
|---|---|
| Overall | Level, then total EXP. |
| Weekly EXP | EXP transactions in the last rolling seven days; this is not a fixed Monday-to-Sunday week. |
| Tickets Rated | Distinct credited ticket count. |
| Accuracy | Accuracy 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 / 2 MIN READ
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.
| Application | Default level | Other requirements |
|---|---|---|
/rating apply-trusted | Level 5 | You are a Verified Rater, Trusted is configured, and you have no pending application. |
/rating apply-senior | Level 10 | You 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
- Check your current standing with
/rating level. - Run the application command for the next available rank.
- Read the private response. If eligible, the bot creates a review case for staff.
- 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 / 2 MIN READ
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
| Button | Effect |
|---|---|
| Assign | Attempts 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. |
| Skip | Removes 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 / 2 MIN READ
Close or cancel a ticket
Know what gets deleted and what stays recorded.
Who may close?
| Ticket stage | Who may close with the bot |
|---|---|
| Collecting media or draft preview | Ticket owner, Senior Rater, Head Rater, or Administrator. |
| Submitted and voting | Senior Rater, Head Rater, or Administrator. |
| Result assigned | Senior 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
- Click Close Ticket on a ticket message, or Yes, close after assignment.
- Where the bot shows a confirmation, choose Yes, Close Channel to proceed or Cancel to leave it open.
- 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 / 2 MIN READ
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
| Control | What is removed |
|---|---|
| Reset All Votes → Yes, Reset All Votes | Every current vote on that ticket. |
| Reset Selection → category → Confirm Clear | All votes for tiers in that category. |
| Reset Selection → exact tier dropdown → Confirm Clear | All 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
- Open Role Management.
- Choose Role Grant for a result not yet assigned, or Role Change to correct one already assigned.
- Select the desired tier from that ticket's gender scale.
- 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 / 3 MIN READ
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.
| Step | What to check | Controls |
|---|---|---|
| 1. Channels | Category, request panel channel, rater chat, Head review chat, logs, and announcements. | Re-Detect, Auto-Create Missing, Confirm & Next. |
| 2. Gender roles | One Male routing role and one Female routing role. | Re-Detect, Auto-Create Missing, Confirm & Next. |
| 3. Rater ranks | Head and Verified are required; Trusted and Senior are optional. | Re-Detect, Auto-Create All 4, Confirm & Next. |
| 4. Tier roles | Fourteen mapped positions for each gender scale. | Re-Detect, Auto-Create Missing Roles, Confirm & Next. |
| 5. Ratee questions | Whether submitting a draft opens the form. | Enable Questions (Defaults) or Skip / Disable Questions. |
| 6. Preset | Voting, 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 / 3 MIN READ
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.
| Tab | Purpose | Permission guidance |
|---|---|---|
| Category | Where new rating tickets are created. | Use a category dedicated to disposable ticket channels. |
| Request Panel | Where dashboard/wizard deployment posts the request button. | Members need to see and use the panel. |
| Head Raters Chat | Promotion review cases and role-denial alerts. | Head Raters and admins only. Selecting this channel applies a private overwrite set. |
| Rater Chat | Rater discussion and the preferred destination for level-up announcements. | Set access for the configured rater ranks manually. |
| Ticket Logs | Assignment, closure, and denial records. | Bot writes; Head Raters read; administrators retain access. |
| Announcements | Optional 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 / 2 MIN READ
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.
| Control | Choices or limits | Fresh default |
|---|---|---|
| Scoring Mode | Mean (Default), Median, Mode. | Mean |
| Minimum Raters | Buttons for 3, 5, or 7; Custom accepts a whole number from 1 to 100. | 5 weighted votes |
| Rating Cooldown | 0, 1, 7, or 14 days; Custom accepts whole days from 0 to 365. | 7 days |
| Promotion & Levels | Minimum 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 EXP | Minimum and maximum positive whole numbers; maximum must be at least minimum. | 15–25 |
| Accuracy EXP | Same range rules as Vote EXP. | 5–10 |
| Ratee Questions | Toggle, customize up to three labels, or reset question defaults. | Disabled |
| Ticket Access | One whitelist role and one blacklist role, each optional. | Neither configured |
| System Presets | Apply 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 / 1 MIN READ
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.
| Setting | Standard / Balanced | Competitive Strict | Casual Consensus | Fast-Paced (Instant) |
|---|---|---|---|---|
| Scoring mode | Mean | Median | Mode | Mean |
| Weighted vote target | 5 | 7 | 5 | 3 |
| Cooldown | 7 days | 7 days | 14 days | 0 days |
| Trusted minimum level | 5 | 10 | 4 | 3 |
| Senior minimum level | 10 | 20 | 8 | 6 |
| First-vote EXP | 15–25 | 10–20 | 20–30 | 25–40 |
| Exact-match EXP | 5–10 | 15–25 | 5–10 | 10–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 / 2 MIN READ
Access rules and questions
Control who can open tickets and what they answer before submission.
Whitelist and blacklist
Open Thresholds → Ticket Access.
| Setting | Result |
|---|---|
| Select a whitelist role | Members must hold that role to open a ticket. Only one whitelist role is stored. |
| Clear Whitelist | Removes that requirement. Other restrictions still apply. |
| Select a blacklist role | Members with that role cannot open tickets. Only one blacklist role is stored. |
| Clear Blacklist | Removes this role-based block. |
| Member has both mapped roles | The 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:
| Field | Behavior |
|---|---|
| Question 1 | Required label; the member's response is required. |
| Question 2 | Optional label; leave it blank to omit this question. Its response is optional. |
| Question 3 | Optional 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 / 2 MIN READ
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.
| Event | Included information |
|---|---|
| Rating Assigned | Member and ticket IDs, opened/assigned times, detected preset, gender scale, assigned role, assigning actor, answers, and individual votes with weights. |
| Rating Ticket Closed | Member and ticket IDs, opened/closed times, preset, scale, rating role if any, assigning/closing actors, answers, and votes. |
| Rating Role Denied | Member, 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
| Action | Scope |
|---|---|
| Scrap | Removes 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 Ticket | Deletes the ticket channel after logging. Local media and database history remain. |
| Manual Discord channel deletion | Marks an active ticket closed through the listener; not a complete normal-close workflow. |
| Ticket Sweep | Attempts to delete ticket media and ticket channels, deletes all children of the configured category, and clears ticket/media/vote records. |
| Configuration reset | Changes 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 / 2 MIN READ
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
| Action | Actually changes | Does not do |
|---|---|---|
| Reset Roles Only | Clears 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 Only | Clears the role ID for every tier position. | Does not delete roles, rename tiers, or remove the fourteen-position ladders. |
| Reset Channels Only | Clears the category and five channel mappings. | Does not delete Discord channels or reverse their permission overwrites. |
| Reset Settings Only | Restores 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 Config | Combines 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:
- Attempts to delete stored media files associated with every recorded ticket in the server.
- Attempts to delete those tickets' Discord channels, including channels outside the current category.
- Deletes every remaining child channel inside the configured category.
- 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 / 2 MIN READ
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
| Command | Who can use it? | Purpose |
|---|---|---|
/rating panel | Administrator | Posts a Request Rating panel in the current channel. |
/rating setup | Administrator | Opens the interactive configuration dashboard. |
/rating level [user] | Members with command access | Posts your rank card, or the selected member's card. |
/rating apply-trusted | Eligible Verified Rater | Creates a Trusted promotion application. |
/rating apply-senior | Eligible Trusted, or Verified if Trusted is unset | Creates a Senior promotion application. |
/rating overrule | Head Rater or Administrator | Opens ticket overrule controls; run inside a rating ticket. |
/quicksetup | Administrator | Opens the six-step configuration wizard. |
/leaderboard | Members with command access | Posts a leaderboard with Overall, Weekly EXP, Tickets Rated, and Accuracy choices. |
/rating level
/rating level user:@Member
/rating apply-trusted
/rating overrule
Owner grants
| Command | Required fields | Access and result |
|---|---|---|
/give-rater-exp | user, amount | Server Owner only. Adds a positive whole number of EXP. |
/give-rater-levels | user, levels | Server 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
| Command | Inputs | Who can use it? |
|---|---|---|
/bot name | Required username (up to 32 characters). | Administrator or bot owner. |
/bot pfp | image attachment or url; provide at least one. | Administrator or bot owner. |
/bot banner | image attachment or url; provide at least one. | Administrator or bot owner. |
/bot announce | Optional 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 / 2 MIN READ
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.
- Run
/bot announceto open the form, or supply title and message directly. - Enter a title (up to 100 characters) and announcement details (form limit 4,000 characters).
- Choose none, everyone, or here for the ping, and optionally include a direct image/GIF URL.
- Review the private preview and server count.
- 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:
- Configured Announcements channel.
- Configured Ticket Logs channel.
- Configured Request Panel channel.
- Server system channel.
- 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 / 3 MIN READ
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:
| Script | Use |
|---|---|
npm run dev | Runs the TypeScript entry point with tsx for development. |
npm run build | Compiles the TypeScript project with tsc. |
npm start | Runs 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.
| Variable | Purpose |
|---|---|
DISCORD_TOKEN | The bot token used to connect to Discord. |
CLIENT_ID | The Discord application ID used to register commands. |
GUILD_ID | Optional server ID used for initial default-tier setup; it does not restrict the bot to just that server. |
BOT_OWNER_ID | Explicit Discord user ID allowed as the bot owner, including global broadcasts. |
DATABASE_PATH | SQLite 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 / 1 MIN READ
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
- Sign in to the Discord Developer Portal with access to the bot's application.
- Select the application and open General Information.
- Add the guide URL to its Description field and save.
- 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:
| Audience | Article |
|---|---|
| New member | Request a rating |
| New rater | Cast or change a vote |
| Someone asking about averages | How the result is calculated |
| Staff onboarding | Who can do what? |
| Server admin | Set up the server |
| Someone with an error | Troubleshooting |
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 / 4 MIN READ
Troubleshooting
Start with the symptom, then check the smallest likely cause.
Members and uploads
| Symptom | Check 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 admin | Access roles and gender routing still apply; only cooldown is bypassed. |
| Active ticket message points to an old channel | Use the existing channel if present. If it was deleted, try requesting again; the bot checks for missing channels. |
| Cooldown after denying a role | Expected. Denial and closure do not clear the rating cooldown. |
| Upload disappears | The bot normally deletes the original and reattaches accepted files to the confirmation. Check the preview. |
| No confirmation preview | Attach 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 started | Click Submit for Rating. Reaching four does not auto-submit. |
| One file missing from a mixed upload | Unsupported files can be skipped or a download may fail. Check the preview; Scrap and resend the intended draft if necessary. |
| Submit opens a form | Complete the server's enabled questionnaire. Cancelling the form leaves you at the draft stage. |
| Uploaded more files after voting began | They are not automatically added to the submitted set. Ask staff to handle the correction. |
| Photo link stopped working | Try the actual attachment on the bot's message. Original attachment links can become invalid after the source message is removed. |
| No Accept/Deny DM | DM delivery can fail. Ask staff; the role may already be assigned. |
Voting and results
| Symptom | Check or next step |
|---|---|
| Administrator cannot vote | Admin alone is insufficient. Assign a mapped rater role; do not self-vote. |
| Category button does not record a vote | Choose the exact tier after expanding the category. |
| Vote total exceeds the number of people | Expected weighted behavior. Check the separate rater count. |
| Result is a tier nobody selected | Possible under mean, median midpoints, or mode ties. See the scoring rules. |
| Assignment prompt disappears briefly | A later vote can replace it after about ten seconds without another change. Wait for the latest prompt. |
| Enough votes, but no role | Staff must still click Assign. Then check the actual role mapping and hierarchy. |
| Success message, but no role on the member | The 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 ticket | Owners can close only before submission. Ask Senior/Head staff or an admin afterwards. |
| Overrule button refuses access | It requires Head Rater or Administrator; Senior alone is insufficient. |
| Statistics look stale after an overrule | Existing credited rows are not reliably rewritten by corrections. See build notes. |
Progression and setup
| Symptom | Check or next step |
|---|---|
| Promotion application rejected | Check configured target rank, current rank, minimum level, and existing pending case. |
| Level reached but no promotion | Apply with the correct slash command; staff approval is required. |
| Approval message but rank missing | Check actual Discord roles and the bot's Manage Roles permission/hierarchy. |
| Leaderboard blank | EXP and completed-ticket categories need corresponding stored activity. Accuracy requires a completed rating. |
| Command from an older guide does not appear | Use this guide's registered command reference. Some old names are not active. |
| Commands missing in a newly joined server | Restart the bot to register the server commands, then check application command access. |
| Missing staff logs | Check the saved log channel and bot permissions. Startup reapplies the log visibility policy. |
| Permanent channels vanished after Sweep | Sweep 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 values | Expected limitation: newer EXP and promotion-level fields are not reset. Apply a preset or edit them explicitly. |
| Broadcast says draft expired | Recreate it with /bot announce; drafts are in memory and are cleaned up after about 30 minutes. |
| “Interaction failed” or unexpected error | Confirm 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 / 3 MIN READ
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 wording | Uploaded implementation |
|---|---|
| Up to three photos/media | Up to four total photos/videos. |
| Automatically submit when maximum reached | Explicit Submit for Rating confirmation remains required. |
| Average all equal votes | Rank-weighted votes; mean, median, or mode selectable. |
| Minimum number of people | Weighted vote threshold, with distinct people shown separately. |
| Role only assigned after acceptance | Role applied first; DM accepts keeping it or declines it. |
| Promotions based on quantity, quality, and approval | Level/rank checks and human approval; counts/accuracy are shown but not enforced as separate gates. |
| Five-step wizard | Six implemented steps, with some outdated step labels. |
| Completely customizable tier structure | Fixed fourteen-position scales with configurable Discord role mappings. |
Features covered
| Area | Included controls and behavior |
|---|---|
| Member workflow | Panel, role-based access/routing, cooldowns, one active unassigned ticket, 1–4 media drafts, submit/scrap, questions, results, DM decisions, closure. |
| Rating | Four ranks, dynamic weights, category/tier buttons, changeable votes, live breakdown, three scoring modes, assignment prompts, staff approval, role replacement. |
| Progression | Vote and exact-match EXP, levels, graphical cards, four leaderboards, application eligibility, approve/deny review, owner grants. |
| Staff operations | Close/keep-open, full/category/tier vote resets, direct role grant/change, assignment/closure/denial logs. |
| Administration | Six-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 tools | Global 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.